[joris-sevenlab]

What this changes

One PR for the battlestack pull work that was spread over #94, #97, #100 and #89, plus the fixes their reviews asked for. After this merges, pull merges upstream changes into files you edited, never overwrites local work, generates a migration when it changes the schema (and says so honestly when it could not), and reports what is left to do in .battlestack/pull/REPORT.md with exit code 2.

Supersedes and closes #94, #97 and #100. Closes #89.

Why

The three PRs fixed overlapping parts of pull from different angles: #100's ordering bug is already fixed at the root by #94's hash handling, and #97 sat on top of the same lines in pull.ts. Reviewing and merging them one by one meant three rounds of conflicts in the same file. Testing them together against a real scaffold also turned up bugs none of them caught on their own (see below).

What is in here

From #94 (seamless upgrade), unchanged apart from the merge with main: three-way merge into edited files, the overwrite check after the update, the clean-tree preflight, REPORT.md and exit code 2. The merge with #93 keeps the rename re-render; its warning now points at REPORT.md instead of patch files.

From #97 (migrations), reworked for the review in Slack:

• A migration only counts as generated when a new .sql file appears. drizzle-kit exits 0 when it stops at a rename prompt without a TTY, so the old "ran db:generate" line showed up with no migration written. Scaffold's initial migration uses the same check.
• When a schema file is staged or has conflicts, pull does not generate (the change is not on disk yet) and lists "finish the merge, then run db:generate" in REPORT.md.
• Anything left to do goes to REPORT.md and exit code 2, instead of a warning that changed nothing.
• drizzle-kit's own error line is quoted (not a stack frame), with a hint to run it in a terminal for a rename. "No schema changes" is treated as nothing to do, only the files drizzle.config.ts reads are hashed, and the hint names the project's package manager.

From #100: its test only. The reorder is not needed on top of #94. Separately, pull now removes files no feature ships any more only after every feature has updated, so a file moving between features is never deleted and written back in the same run, whatever the order.

From #89 (rateLimiter gate), reworked: the gate is applied through the config AST instead of a regex, so a limiter with nested options is gated too, a commented-out one is ignored, and false, an already-gated value or a variable is left alone.

Found while testing against a real nuxt4-fullstack scaffold: every nuxt4:database bump staged server/database/schema/users.ts for a manual merge, because nuxt4:storage patches in avatarKey after the database feature recorded the file. Taking the staged file and running db:generate would drop the avatar_key column. nuxt4:database now ships a users.ts variant with avatarKey when storage is on (same pattern as health/with-db), and a test pins it byte-for-byte to storage's patch.

Review follow-ups from #95, #96, #98 and #99:

• runtimeConfig that is not an inline object gives a clear error instead of a proxy crash, skipped nested defaults are warned about, an explicit null is kept. setRuntimePublicDefault goes through the same merge.
• A sessionHeader other than false is kept with a warning; two more e2e cases for the session header (revoked on another device, live session in the header only).
• Icon detection covers shortcut icon, any casing, and useHead in app/app.vue and layouts; pull notes when it skips the template links.
• CI prints server.log when the tests fail, the readiness curl has timeouts, stale comments fixed, and the ruleset file turns on strict status checks.

Also: a rename stays pending when a feature fails or its plugin does not load during the re-render (edge case from the #93 review), and .claude/worktrees/ is ignored.

Fixes from the in-depth review of this PR

• A file moving to another feature with changed content was deleted when its old owner updated first (a regression in the deferred deletion above). The new owner now sees the old owner's queued hash.
• Monorepos: the clean-tree check, the overwrite repair and the git-history merge base are scoped to the project folder (--relative, HEAD:./<rel>).
• Checkout filters: HEAD and history are read with git cat-file --filters, so core.autocrlf or eol=crlf no longer make pristine files look edited. The history lookup is async and reads each blob once.
• Files claimed with battlestack own are skipped by every recorded writer again (the Dockerfile was merged), and a feature with structural files no longer drops own entries from the manifest.
• shared:github ignores a retired workflow path it never wrote (a project's own production.yml).
• battlestack add puts its section above an earlier pull's REPORT.md instead of erasing it.
• --force / --overwrite start over conflict markers; the overwrite repair keeps a .bak under --force and stays out of the way under --overwrite. Its staged fallback restores the writing feature's own hash and writes the promised .patch.
• Report: a restored file is listed once, and feature lines count every merge, conflict and staged file.
• Migrations: "No schema changes" is read from both streams. On a storage project an edited users.ts gets a stored merge base, and pull repairs a migration that drops users.avatar_key, which earlier pulls could have led to: it takes the drop out of the migration and drizzle's snapshots, and adds a migration (ADD COLUMN IF NOT EXISTS, made with drizzle-kit generate --custom) that puts the column back where the drop already ran. Verified with real drizzle-kit: a fresh db:generate afterwards finds no schema changes.
• A rename stays pending while a plugin is not loaded.
• ^0.x ranges: a higher 0.x minor is not kept over a feature's range.
• Template favicon links an earlier pull added are removed once the project has its own (only when all three are present).
• One core helper (trackersOf / recordedFiles) replaces four copies of the recorded-files walk; duplicated sha256 helpers are gone.

Finishing touches

• .battlestack/base/ is a local merge cache and stays out of git: new projects ignore it, the docs and the upgrade skill no longer say to commit it, and pull lists git rm -r --cached .battlestack/base for a project that committed it.
• A project scaffolded before the release-age policy moved to pnpm-workspace.yaml can have a lockfile pnpm then rejects. The pull that adds the policy checks it with pnpm install --frozen-lockfile --lockfile-only, and when it fails, skips lint and db:generate and lists the lockfile rebuild in REPORT.md. Rare in practice, since older projects had a policy in .npmrc that pnpm did not enforce, so only recently updated packages trip it.
• The battlestack-upgrade skill covers migrations, set-aside schema files, --force backups, monorepos and checking that a second pull exits with code 0.
• Run against a real client project's upgrade from wolf 2.3.9: same conflict set as the pull: merge into edited files, never overwrite local work #94 run, a clean generated migration (no drops), users.ts kept avatarKey, and the overwrite repair caught five files a feature wrote over.

Type of change

• Bug fix
• New feature or template
• Refactor with no behaviour change
• Documentation
• Build, CI or release tooling

AI assistance

• No AI agent involved
• Claude Code
• Cursor
• GitHub Copilot
• Codex
• Other, named below

Agent, service and model, if you know it: Claude Code, Opus 5.5

How much of this is agent-written?

• Whole change, reviewed by me before opening
• Substantial parts, with my own edits on top
• Small parts, or just the tests or docs
• Only the commit message or this description

Feature versions

• I changed what a feature emits, and bumped that feature's version: nuxt4:auth 1.10.8, nuxt4:essentials 1.2.4, nuxt4:database 1.7.5, nuxt4:storage 1.3.4, shared:security 1.0.5, plus pull: merge into edited files, never overwrite local work #94's own bumps
• I changed a collectDocs or collectEnv contribution, and also bumped the feature that writes the target file
• Not applicable

Changelog

• I added a line under ## Unreleased saying what changes for someone using battlestack
• Not applicable

Testing

pnpm tsc
pnpm test                                   # 105 files, 1171 passed, 1 skipped
BUMP_CHECK_BASE=origin/main pnpm bump:check # OK

Against a real nuxt4-fullstack scaffold (installed, committed), running the CLI from source:

• plain pull with no template change: every feature up to date, exit 0, nothing in REPORT.md

• index added to the auth sessions.ts template: generated 0001_*.sql, exit 0, SQL is the CREATE INDEX

• column renamed: no SQL, REPORT.md quotes drizzle-kit, exit 2 (the stack-frame quoting found here is fixed)

• sessions.ts edited by the user: a clean merge generates the migration with both edits; a conflict skips generation and lists the merge, exit 2

• nuxt4:database bump with storage on: reproduced the users.ts staging above, now fixed

• pnpm tsc passes

• pnpm test passes

• I removed the behaviour each new assertion covers, watched the test fail, and put it back

Checklist

• Scoped to one concern. Unrelated cleanups are in their own commit or PR
• Public-facing docs updated where behaviour changed (docs/, README.md)
• No internal tracker numbers, post-mortem narrative, or internal infrastructure details in the diff
• Files under packages/*/templates/** are LF
• No secrets, tokens or real credentials, including in test fixtures

Not one concern on purpose, see Why. Each fix is its own commit, and the merges of #94, #96, #97 and #89 are kept as merge commits, so the history reads per topic.

Anything else

• The two new auth e2e tests and the template edits are not covered by pnpm tsc; the scaffold e2e job in CI is their first run.
• Strict status checks are only on in .github/rulesets/require-ci-to-pass.json. Someone with admin rights still needs to apply the ruleset and enable allow_update_branch (docs/repository-settings.md has the command).
• setRuntimePublicDefault changes reach projects at the next bump of nuxt-ui, auth-verification, build-info or health; they were not bumped for it.
• Known limits, deliberately left for later: battlestack add and remove do not generate migrations yet; --skip-install always skips db:generate; pull --dry-run lists no per-file preview; k8s files are staged, not merged.
• Decisions from pull: merge into edited files, never overwrite local work #94 still open for the reviewer: the build-info footer separator changed from an em-dash to ·, and the runningLow strings in dashboard.json were reworded.
• The rustfs image in CI stays on :latest: Dependabot does not update images in a workflow's services:, so a digest pin would go stale.

[JoeyHoutenbos]

Reviewed at 6a6bf7d. pnpm tsc, pnpm test (1179 passed) and bump:check are green, and replaying a real 1.3 → 1.4 project pull with this build keeps the moved auth e2e test and the project name. Docs, changelog and the upgrade skill match the code. Four things need fixing before this merges, though.

Blockers

1. A file moving to an earlier-stage feature is deleted and never comes back (packages/core/src/utils/templates.ts, deferredToLater in sharedRelOwnership + removeQueuedObsoleteFiles)
The mirror of the case #100 was about. Old owner A (later stage) ships moved.ts at v1; at v1.1 it moves to B (earlier stage). B still sees the rel in A's seeded files: map, so it defers to the "later owner" and neither writes nor records it. A then drops it as obsolete, nobody tracks it, and the queued deletion removes it. Pull exits 0, and a second pull does not restore it.
Repro: in packages/cli/test/pull.test.ts "a file moving to a later feature", swap the stages in setup (from = STAGE.AUTH, to = STAGE.NAMING); "keeps a pristine file and hands its record to the new owner" fails with ENOENT. Suggest: ignore a later feature's rel in deferredToLater when that feature's new version no longer ships it, and add the swapped-stage variants as tests.

2. The avatar_key repair rewrites a migration that may already be applied (packages/preset-nuxt4/src/utils/migrations.ts, repairDroppedAvatarColumn)
The project's own templates/database/tools/migrate.mjs skips a migration only when its sha256 is in __drizzle_migrations. After the repair the file has a new hash, so the next deploy runs it again. With the PR's own fixture (DROP COLUMN "avatar_key" + CREATE INDEX "users_email_idx") that is "relation already exists", rollback, failed deploy. Only a migration whose sole statement was the drop survives (SELECT 1;). Safer: leave applied SQL alone and only add the ADD COLUMN IF NOT EXISTS migration, or report the drop and let the user decide.

3. With npm, the repair overwrites a real schema migration (migrations.ts, the generateMigration(ctx, ['--custom', '--name=restore_avatar_key']) call and the write of RESTORE_SQL)
npm run db:generate --custom --name=… hands the flags to npm, not the script (no --), so drizzle-kit runs a plain generate. If the pull also changed the schema, that writes the real migration, exactly one new file appears, and it is overwritten with the avatar SQL. The snapshot already holds the real change, so the next generate says "No schema changes" and the change never reaches the database. The fallback hint gives npm users the same command. Suggest: put -- before extra args, and only write RESTORE_SQL into an empty file named *_restore_avatar_key.sql.

4. On a core.autocrlf=true checkout an untouched file becomes one whole-file conflict (templates.ts, classifyForUpdate / mergeInPlace)
The working copy is CRLF, the recorded hash is of the LF bytes, so the file counts as drifted; findBase finds the LF blob and git merge-file turns every line into one diff3 conflict, written in place. Before this PR it was staged untouched. repairOverwrites already compares the --filters form; the drift check needs the same. The test "finds a file battlestack wrote as LF under core.autocrlf" never re-checks the file out, so the working copy stays LF and this path is not exercised.

Should fix

• Owned files get merged into via a second tracker (writeGuarded → ownedRelsFor(ctx, featureId)): battlestack own records ownership on the first tracker only, so a second feature writing the same rel (e.g. app/app.config.ts, nuxt-ui and landing-shell) merges into the owned file. Check ownership across every tracker.
• Merging only works on the machine that ran the previous merge: after a merge the manifest records the upstream hash, but those bytes live only in .battlestack/base/, which is now gitignored. On another clone or in CI findBaseInGit finds no blob with that hash, so every later pull of an edited file stages instead of merging.
• A later pull wipes unfinished work from REPORT.md and exits 0: pull stages a.ts (exit 2), a same-version re-run skips every feature and rewrites the report to "Nothing needs attention" while .battlestack/pull/a.ts.new is still there. Same for the --skip-install "run db:generate" action: the next pull sees no schema change and the reminder is gone. Carry unresolved items forward, or leave the report alone when nothing ran.
• The drop match ignores the table (AVATAR_COLUMN and the statement filter): a deliberate ALTER TABLE "teams" DROP COLUMN "avatar_key" gets rewritten too, and the users.ts check is a plain includes('avatar_key'). With prefix: 'timestamp', parseInt of the file name makes the snapshot repair skip every snapshot while the SQL drop is still removed.
• The new e2e test "a session revoked from another device is refused…" cannot fail on revocation: with sessionHeader: false every header-only request is 401, as the next test asserts. It passes with revocation broken. Send the cookie and assert the revocation check refuses it, or drop it.
• runtimeConfig: { public: pub } aborts the feature's pull (nuxt-config.ts / ts-file.ts) with "runtimeConfig.public is not an object literal", while any other non-literal nested parent is a warning. Treat public the same, or document it.

Nits

• An obsolete, locally edited file gives "Nothing needs attention" and exit 0 alongside a "No longer managed" section asking for a decision.
• add's warning can read "merging into 0 existing file(s)" when only actions are left.
• The sessionHeader warning runs on update only, not on add.
• rateLimiter: { … } as any / satisfies X stays ungated without a note.
• Icon detection misses :rel="'icon'" and unquoted rel=icon.
• The lockfile check: execFile('pnpm') cannot start pnpm.cmd on Windows, and offline or ERR_PNPM_OUTDATED_LOCKFILE both read as "not blocked".
• Migration detection reads only server/database/migrations, so a project with another out gets "wrote no migration" when one was written.
• pull-safety.test.ts "pull with --allow-dirty skips the overwrite check" never calls repairOverwrites or pull, so it passes with the guard removed; the merge outcome of repairOverwrites has no test.