From 7b9459c774b986d76107f33ee39276d6fcb251b6 Mon Sep 17 00:00:00 2001
From: "Danilo M." <danix@danix.xyz>
Date: Wed, 1 Jul 2026 09:58:49 +0200
Subject: Extract full zip; excluding storage broke Laravel boot

Excluding storage/ from extraction (unzip -x 'storage/*') dropped the
storage/framework/{cache,views,sessions} skeleton Laravel needs to boot, so
the first artisan call died with a misleading "Target class [auth] does not
exist" (the real boot error is masked by the exception reporter, which calls
auth()). Extract the whole archive and overlay live user data on top instead.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CLAUDE.md      |  7 +++++++
 firefly-update | 14 ++++++++------
 2 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 2c745ae..4ccf70c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -40,6 +40,13 @@ Debian. See README.md for usage; this file is the non-obvious context.
   space then `*`); `cut -d' ' -f1` gets the hash. The script verifies it when
   `sha256sum` is available, and validates the extracted tree before swapping.
 
+- **Extract the FULL zip, do NOT `unzip -x 'storage/*'`.** The zip's storage
+  skeleton provides `storage/framework/{cache,views,sessions}`, which Laravel
+  needs to boot. Excluding it and recreating only the data dirs makes artisan
+  die with the misleading `Target class [auth] does not exist` (the real boot
+  failure is masked by the exception reporter, which itself calls `auth()`).
+  Extract everything, then overlay live user data (uploads/exports/DB) on top.
+
 ## Conventions
 
 - Config via env vars (`WORKDIR`, `INSTANCE`, `BACKUPDIR`), matching the
diff --git a/firefly-update b/firefly-update
index e8209c5..59cfc28 100644
--- a/firefly-update
+++ b/firefly-update
@@ -160,9 +160,11 @@ if command -v sha256sum >/dev/null && curl -fLs -o "${zip}.sha256" "${base}.sha2
 	echo "checksum OK"
 fi
 
-# Exclude storage/ from extraction: we carry over the live storage below, and
-# the zip's storage skeleton would only get in the way.
-unzip -q "$zip" -x 'storage/*' -d "$UPDATED"
+# Extract the full archive, storage skeleton included. That skeleton provides
+# storage/framework/{cache,views,sessions}, which Laravel needs to boot; without
+# them artisan dies with a misleading "Target class [auth] does not exist". Live
+# user data (uploads, exports, DB) is overlaid on top below.
+unzip -q "$zip" -d "$UPDATED"
 rm -f "$zip"
 
 # Validate the extracted tree before proceeding. A partial extract must not be
@@ -172,9 +174,9 @@ for item in artisan bootstrap vendor public/v1/js/app.js; do
 	[ -e "${UPDATED}/${item}" ] || { echo "extracted install incomplete, missing: $item" >&2; exit 1; }
 done
 
-# Carry over config and user data. cp -a of dir/. copies contents incl. dotfiles,
-# and does not fail on an empty source directory. mkdir -p in case the zip
-# ships these dirs gitignored/absent.
+# Carry over config and user data, overlaying onto the extracted skeleton.
+# cp -a of dir/. copies contents incl. dotfiles and does not fail on an empty
+# source. mkdir -p is belt-and-suspenders should a future zip omit a dir.
 cp "${LIVE}/.env" "${UPDATED}/.env"
 mkdir -p "${UPDATED}/storage/upload" "${UPDATED}/storage/export" "${UPDATED}/storage/database"
 cp -a "${LIVE}/storage/upload/." "${UPDATED}/storage/upload/"
-- 
cgit v1.2.3