[jcombs-pointblue]

Phase R2 of project-per-environment.md. User reference: docs/compare-projects.md.

Needs DirXMLDev 0.54.0 (PointBlueTechnology/DirXMLDev#96: Promote.preview). The pom pins it, so CI fails until that release is out.

What's in it

• Compare projects (left-hand menu; shown when the server holds more than one project).
  • What's compared: this project and another, both read from their base branch as the repository has it. A server-side clone under data.dir/promotion/<project>/ is fetched for each request, so what's reviewed is what's applied, whatever the person's own copies hold.
  • The list: differences by driver and bucket (pending, both changed, this project's own, not paired yet; known and unchanged behind a toggle). Map lines are proposed for drivers that look alike under other names.
  • The review: each file side by side in Monaco, this project's against what promoting writes. Blocks can be kept from this project, or the right side edited, as in Update this branch from….
  • Ticked to begin with: pending files only. Never a value, never own or both changed.
  • Warning: a file added or removed without its changed manifest is flagged before Promote.
• Promote (POST /api/promote/apply, editors):
  • It re-reads both base branches and refuses a stale review (409).
  • It plans first, so a refusal (a validation error, a missing manifest) makes no branch.
  • Then it opens promote/<source>-<yyyyMMdd-HHmmss> from the base, applies, and commits as the person: files, values, then the Promoted-from: <source>@<commit> trailer, with the record in the same commit. It pushes and moves the session to the branch. The page lands on Changes, vs main, where the bar offers the pull request or Merge into main….
  • Audit: promote, with the source, its commit, the objects, values and branch.
• API: GET /api/promote/projects, GET /api/promote/compare?from=, POST /api/promote/apply (fields in the doc).
• Small changes:
  • Git.must is package-visible.
  • App's workspace-changed handler takes where to land.
  • The promote route is handled in route.ts.

Not in R2 (R3)

Pair with… on the page (bin/idm promote.pair for now), accepting known differences on the page, cases moving with their driver, and MCP compare_projects / promote_changes.

Testing

• PromotionServiceTest: two bare repositories as QA and production on one server.
  • Compare shows the policy and the value.
  • A stale revision is refused.
  • A bad path is refused without a branch.
  • Apply pushes promote/acme-qa-…, holding QA's policy, production's value and the record. The commit is Alice's, with the trailer naming QA's head. Production's main is untouched.
• Builds and smoke: mvn -o clean package passes (112 tests, 1 skipped); vitest passes (54, including the promote route); bin/smoke.sh and bin/smoke-hosted.sh pass. All of these ran against a local 0.54.0-SNAPSHOT of Vault view: engine strip and per-driver manage panel (#68, #69) #96.
• In the browser: two projects on a scratch hosted server built from the synthetic fixture, with QA changed (rule added, GCV value changed).
  • Compare listed the policy and the value as not paired yet, with the diff side by side.
  • Ticking the policy and promoting opened promote/acme-qa-…. Its vs main showed the policy and promotions/acme-qa.json.

🤖 Generated with Claude Code