Install from release zip; fix Passport migration collision

Two root causes made the composer-based update produce a broken install:

- composer create-project ships source only, without the compiled frontend
  bundles (public/v1/js/app.js etc.), leaving the UI broken (no graphs, 404s).
  Switch to downloading and extracting the official GitHub release zip, which
  is prebuilt. Normalize the version so both "6.6.5" and "v6.6.5" resolve to
  the correct v-prefixed release asset.

- Laravel Passport renames its migration files between versions, so a
  carried-over DB has the oauth_* tables while the new filenames look pending,
  and migrate aborts trying to recreate existing tables. Reconcile the
  migrations ledger before migrate: record already-present tables, let missing
  ones be created.

Also add an ERR trap so a failed run names the failing line and cannot
masquerade as success (a silent mid-run failure left a half-built dir that
looked done), a dependency check (curl/unzip/php), and mkdir guards for the
storage carry-over. Document all of it in README.md and CLAUDE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

1 files changed, 47 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c1c103b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,47 @@
+# CLAUDE.md
+
+Single bash script, `firefly-update`, that updates a Firefly III instance on
+Debian. See README.md for usage; this file is the non-obvious context.
+
+## Hard-won gotchas (do not relearn these)
+
+- **Install from the GitHub release zip, never `composer create-project`.** The
+  composer/Packagist dist ships source only, no compiled frontend bundles
+  (`public/v1/js/app.js`, `app_vue.js`, ...). A composer install looks fine but
+  the UI is broken: no graphs, `404 /v1/js/app.js`, and the v2 error/login
+  pages throw `Vite manifest not found (public/build/manifest.json)` as a
+  secondary symptom. The zip is prebuilt and is the supported artifact.
+
+- **Release tag carries a leading `v`** (`v6.6.5`). Asset name is
+  `FireflyIII-<tag>.zip` with the `v` included. `--version` is normalized so
+  both `6.6.5` and `v6.6.5` work; don't reintroduce a double-`v` bug.
+
+- **Passport OAuth migration collision.** Laravel Passport renames its
+  migration files between versions, so a carried-over DB has the `oauth_*`
+  tables while the new filenames look pending; a naive `migrate` dies with
+  `table "oauth_auth_codes" already exists` (then `oauth_device_codes`, ...).
+  The script reconciles the `migrations` ledger before migrating (records
+  already-present tables, lets missing ones create). Do NOT "fix" a collision
+  by dropping tables, it is whack-a-mole and can lose
+  `oauth_personal_access_clients`.
+
+- **The Vite/`public/build` error is a red herring for graphs.** It only fires
+  on the v2 error and login pages. Graphs breaking = missing `public/v1/js`
+  bundles (see the zip point above), a different cause.
+
+## Conventions
+
+- Config via env vars (`WORKDIR`, `INSTANCE`, `BACKUPDIR`), matching the
+  existing style; no new CLI flags unless asked.
+- Keep it a single file. `set -euo pipefail` + `ERR` trap are load-bearing:
+  the script must abort before the live swap on any failure and never leave a
+  half-update looking successful.
+- Any change to the install/migrate flow: test the download+extract and the
+  migrate path before claiming it works. The script touches a live personal
+  finance instance; a bad run is not cheap.
+
+## Testing without a target machine
+
+There is no Firefly instance in this repo. Test URL construction and
+download/extract against the real GitHub releases (the asset URLs are public);
+the artisan/migrate steps can only be exercised on the actual host.