Skip to content

versionctl: several mirror pointers per file for npm lockfiles (#273) - #274

Merged
lukemaj merged 1 commit into
mainfrom
mirror-package-lock-versions
Nov 18, 2026
Merged

lukemaj merged 1 commit into
mainfrom
mirror-package-lock-versions

Conversation

@lukemaj

@lukemaj lukemaj commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

What changed: A version policy can declare several mirror pointers in one file, so versionctl prepare updates both package-lock.json version fields (/version and /packages//version) and doctor/release-check verify both.
Why: Policy validation allowed one mirror per file, and adopt/prepare built each mirror's new text from disk, so a second pointer in the same file would have overwritten the first.
So what: Ready for the user's merge approval once independent review passes; release and install follow under repository policy.

Closes #273

Design choice

Chose several mirror pointers per file over special-casing npm lockfiles. It is the smaller and more general change: uniqueness moves from path to (path, pointer), and adopt/prepare pass the already-updated text of a file into the next pointer's edit (updated_mirror_text(..., text=changes.get(path))). No npm-specific code, no new policy field, and any other file with two version fields works the same way. doctor and release-check already read each mirror independently, so they needed no change.

Proof

  • Red before fix: test_npm_lockfile_declares_both_version_fields failed with INVALID_POLICY: mirror paths must be unique and cannot equal versionSource. With only the policy fix (no chaining) it failed with {'version': '0.1.0', 'packages': {'': {'version': '0.1.1'}}} (first field clobbered).
  • Green after: the test runs doctor, prepare patch (updates package.json, /version, /packages//version), release-check, then checks doctor flags exactly the stale /packages//version and release-check exits 15.
  • test_duplicate_mirror_pointer_is_rejected keeps exact duplicates invalid.
  • python3 -m unittest discover -s tools/versionctl/tests -p 'test_*.py': OK. python3 -m unittest discover -s tests: 515 tests OK.
  • versionctl release-check on a1d56d9: ok, 17.6.0 (minor: compatible capability).
  • Website impact: none (internal CLI policy capability; docs updated in project-policy.md).

Elon record

🤖 Generated with Claude Code

…273)

Mirrors are unique per (path, pointer) instead of per path, and adopt and
prepare chain edits to one file so later pointers keep earlier ones.

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

lukemaj commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

What: Independent review approves this exact candidate with no blocking findings.
Why: Generic mirror identity and chained edits satisfy #273 without adding a component or npm-specific handling.
So what: Independent review is complete; final merge remains with the user.

Candidate and verdict

  • Head: a1d56d94503f6536069646b44eb94d34b967da23 (mirror-package-lock-versions).
  • Base: cbe8032b2ab03ce0d1c73ecb19696f9c5c01cd44 (main).
  • Live head/base verified at review start and immediately before publication.
  • Blocking findings: none. Verdict: approve.
  • Nonblocking notes: the additional adoption, TOML, dry-run and staged-index cases below were independent scratch proof, not new committed regressions.

Review evidence

I read the full gh pr diff 274 -R toolboxmd/agentsmd, gh issue view 273 -R toolboxmd/agentsmd, and exact-head surrounding code with git -C <worktree> show <sha>:<path>.

  • policy.py:147-155: uniqueness is the normalized path plus pointer; duplicate pairs and canonical VERSION mirrors remain rejected.
  • service.py:266-272,380-386 and files.py:177-185: both adopt and prepare chain changes.get(path) into updated_mirror_text; each reported before value is read from the original disk text.
  • service.py:702-709: staged doctor parses every pointer from index content, independently of working-tree content.
  • Existing JSON Pointer parsing preserves empty tokens; both /packages//version and the single empty-key pointer / were exercised.
  • Reviewed project-policy documentation, 17.5.0 to 17.6.0 compatible minor transition, changelog, and all five package/plugin version mirrors. No new component.

Independently executed proof

All execution used a disposable export, never either protected checkout:

git -C /Users/rocky/.t3/worktrees/agentsmd/cb0d6c7f-ee124e5bf59e5982 archive a1d56d94503f6536069646b44eb94d34b967da23 | tar -x -C <scratch>
cd <scratch>
python3 -m unittest discover -s tools/versionctl/tests -p 'test_*.py'

Result: 9 tests passed, initially and again after restoring the exact candidate from the discrimination checks.

Additional python3 independent_proof.py in scratch passed:

  • npm prepare dry-run leaves all non-Git file bytes unchanged and reports both original before values, then prepare updates both fields;
  • doctor and release-check independently reject either stale lockfile pointer (exit 15);
  • staged doctor accepts a correct index with stale working-tree content and rejects a stale nested index value with correct working-tree content;
  • generic JSON and TOML two-pointer adopt/prepare, adopt dry-run byte preservation, distinct original before values, empty JSON key, unrelated JSON data and TOML quote/comment preservation;
  • exact duplicate pairs and normalized canonical versionSource rejection (exit 11).

Regression discrimination command:
python3 -m unittest discover -s tools/versionctl/tests -p test_versionctl.py -k test_npm_lockfile_declares_both_version_fields

  • With base policy/files/service in scratch: fails at doctor with exit 11, INVALID_POLICY: mirror paths must be unique and cannot equal versionSource.
  • With candidate policy only and base writers: fails because root version remains 0.1.0 while nested version becomes 0.1.1.
  • Restored candidate: full versionctl suite passes. This rejects both the original restriction and a plausible incomplete fix.

Also passed: git diff --check <base> <head>, and direct exact-export validation of canonical 17.6.0 plus all five declared mirrors.

Limits and cleanup

This is deterministic CLI proof and source review, not behavioral Live Verification or a complete release/package/install gate. I did not independently rerun the author's 515-test root suite, release or install anything, or modify either checkout. All created scratch files, exports, bytecode and temporary test repositories were removed; scratch absence verified. Both protected checkout status checks were clean.

Elon record

Requirements and who asked: #273 and this review request require both npm lockfile fields to track VERSION and both verification commands to check them, advancing deterministic delivery.
Deleted: No new component, npm-specific path, or per-project sync step is needed.
Bottleneck: Path-only uniqueness and independently rebuilt file text were the failing owners.
Checked myself: Full diff and consumers, exact-head suite, independent edge cases, base and policy-only failures, version mirrors and cleanup.

@lukemaj

lukemaj commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Agent cost not published: agent-observer publish --task toolboxmd/agentsmd#274 reported "nothing to publish: no sessions in scope".

@lukemaj
lukemaj merged commit 77d76de into main Nov 18, 2026
2 checks passed
@lukemaj
lukemaj deleted the mirror-package-lock-versions branch November 18, 2026 13:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

versionctl cannot mirror both version fields of package-lock.json

1 participant