upgrade repairs the installed-file record, legacy request.body migration hint, shared env/secrets (#1131, #1132, #1133)

[jimhoyd]

Problem and change

#1131: urlcode upgrade leaves addon-files.lock.json unwritten, so extensions list --strict fails

• Root cause: the old release's upgrade code runs the upgrade. 0.6.5's had no record-writing step; it first shipped in 0.6.6 (Artifact inspection follow-ups: $id bases, registry integrity, $ref in data, YAML anchors, catalog documents #857). Main records on a moving upgrade, but if the site was already up to date it returned early, so a second upgrade could never repair the missing record.
• Repair on an up-to-date upgrade: it now records every installed catalog add-on that still matches its pin but has no entry. An add-on npm moved off its pin is left for list --strict to report. UpgradeResult.recorded lists what was recorded, and the CLI prints it.
• Atomic record writes: writeFilesLock writes a temporary file and renames it into place. A failure names the file and fails the upgrade; a moving upgrade rolls back everything.
• Output of extensions add: it reports "Recorded the installed files of X…" when it only writes the record. "nothing to do" appears only for a true no-op. --json carries recorded.

#1132: targeted migration hint for the route-wide request.body shape (#870)

• One targeted error: the old shape (required, maxBytes, contentTypes, format or schema directly under request.body, in a route or a shared block) is refused with one error, code legacy-request-body, before the generic schema errors.
• What it says: it names the file:line:column, the route and the keys. It says which method to move them under, gives a before/after, and links the new docs/HTTP.md#moving-from-the-route-wide-body-shape through docsUrl(). Extra places are listed with their line and column, capped at 8.
• Same text everywhere: the CLI, MCP validate and explain_error all give it.

#1133: shared: blocks may carry env and secrets (owner reversed #576)

• Schema: route and shared blocks share $defs/envBindings and $defs/secretBindings, so shapes and limits are identical.
• Merge rule: resolved when the project loads, name by name, and the route's own entry wins. use stays a single name, so two blocks never conflict.
• Visibility preserved:
  • permissions lists the inherited grants under each route that uses the block, and only there.
  • Adding a route to a block changes its grants and projectSha256, so an old policy is refused. A policy granting /a still refuses /b.
  • Inline and inherited bindings give the same route version and grants.
  • explain shows binding names and never values.
  • Sandboxed routes behave the same.
• Docs: SPECIFICATION, yaml/organization, FUNCTION-SECURITY, SECURITY.md (the reversed decision and how per-route visibility is kept) and the RIM-CFG-002 card. There is a new examples/shared-bindings example.

Also included: the #1121 agent-facts check now counts only packages/ directories that hold source. Before, an older checkout's leftover dist/ or node_modules/ from a removed package failed check:docs.

Verification

• npm run verify exits 0 on this exact tree.

  • Core: 1414 pass.
  • Workspaces: auth 33, mcp 47, store 239.
  • Add-ons and proofs: addons 9, proof 12, authjs 13, native 7, ecosystem 13.
  • 0 failures anywhere.

• npm run test:package exits 0: "43 packaged example commands ran from consumer copies; Packed installation and starter/cookbook checks passed".

• New tests:

  • test/upgrade.test.ts: 4 new; three fail on main.
  • test/addon-files.test.ts: record-only add output.
  • test/legacy-request-body.test.ts: 5 tests, including the exact-message snapshot.
  • test/shared-blocks.test.ts: 9 new.

• Core package budget, from the merged measurement:

  	Old budget	New budget	Measured
  Packed	1090 KiB	1098 KiB	1120281 bytes
  Unpacked	4274 KiB	4300 KiB	4396305 bytes
  Entries	561	570	565

Limitations

• [Bug]: urlcode upgrade does not write addon-files.lock.json, so extensions list --strict fails after a successful upgrade #1131:
  • The released 0.6.5 can't be fixed. Sites already on 0.6.6 need one more urlcode upgrade under the next release, then a commit of addon-files.lock.json. This belongs in the release notes.
  • A stale record (version or integrity changed outside urlcode) still needs add or npm ci.
  • Tested with the fake npm only.
• [Request]: targeted migration hint for the legacy request.body shape (move keys under the method key) #1132:
  • A shared block's suggested methods come only from routes in the entry file.
  • The linked anchor resolves at the next release tag.
• [Request]: shared: blocks may carry env and secrets (reverses #576) #1133:
  • urlcode routes doesn't list bindings for any route (existing behaviour).
  • The example shows only env; secret inheritance is covered by tests.
  • The repeated MCP_ENABLED_SKILLS routes that motivated this live in the private urlcode-ai project, not this repo, so they're a follow-up there after release.
• Review: no independent security review.

Closes #1131
Closes #1132
Closes #1133

🤖 Generated with Claude Code