@tokenoftrust/cli 1.4.0-rc.14 → 1.4.0-rc.16

package/src/commands/sync.mjs

@@ -0,0 +1,192 @@
+/**
+ * `tot sync` — the common candidate CONFLICT-RECOVERY path (branch-lifecycle
+ * contract, docs/architecture/branch-lifecycle-and-integration-preview.md,
+ * "Two developers touch the same file" / P1 item 12):
+ *
+ *   Both candidate previews may be green in isolation. After the first
+ *   integrates, the second may become conflicted. The queue blocks that PR
+ *   and prints the conflicting paths. The second developer syncs from
+ *   `preview`, resolves locally, reruns `tot preview`, and obtains evidence
+ *   for the new head. Prior approval is stale and must not carry forward
+ *   automatically.
+ *
+ * `tot sync` fetches the protected `preview` branch and MERGES it into the
+ * developer's current local branch — this repo's own canonical policy for
+ * bringing a protected line into a working branch (see playbook/merge.md:
+ * `git fetch` + `git merge --no-edit`, never a history-rewriting rebase of
+ * shared history). It never writes `preview`/`main` (fetch is read-only on
+ * the remote), never force-pushes anything, and never runs `git add -A` — on
+ * a conflict it stops immediately and leaves the merge in progress so the
+ * developer resolves it the normal git way (`git add <file>` + `git commit`,
+ * or `git merge --abort` to back out).
+ *
+ * Distinct from `tot preview`/`tot accept`: sync touches ONLY the developer's
+ * own local branch. It never pushes, never opens/updates a candidate, and
+ * never touches the shared `preview` aggregate or live. A successful sync
+ * moves local HEAD, which makes any prior preview/approval stale by
+ * definition (they were evidence for the OLD head) — so this always closes
+ * by pointing the developer at a fresh `tot preview`.
+ *
+ * Dependency-free (global `git`, no MCP/network beyond `git fetch`).
+ */
+import { execFileSync } from "node:child_process";
+import { fail } from "../errors.mjs";
+
+/** The protected branch `tot sync` fetches + merges from by default. */
+export const DEFAULT_SYNC_BRANCH = "preview";
+
+const USAGE = `tot sync — fetch \`preview\` and merge it into your local branch
+
+  tot sync                    fetch origin/${DEFAULT_SYNC_BRANCH} and merge it into your current branch
+  tot sync --branch <name>    sync against a different protected branch (default: ${DEFAULT_SYNC_BRANCH})
+  tot sync --help             show this help
+
+  The common conflict-recovery path: after another candidate integrates first,
+  yours may conflict on \`tot accept\`. \`tot sync\` fetches the protected
+  \`${DEFAULT_SYNC_BRANCH}\` branch and merges it into your local branch so you can resolve the
+  conflict locally, THEN re-run \`tot preview\` for a fresh candidate head.
+
+  On a conflict, sync stops SAFELY: it prints the conflicting paths and leaves
+  the merge in progress for you to resolve by hand — it never force-pushes
+  \`${DEFAULT_SYNC_BRANCH}\`/main and never runs \`git add -A\`.
+
+  A successful sync moves your local HEAD, so any prior preview/approval — it
+  was evidence for the OLD head — is now stale. Re-run \`tot preview\` before
+  your next \`tot accept\`.`;
+
+/** Parse `tot sync` argv. Pure — unit-testable. */
+export function parseArgs(argv) {
+  const a = { branch: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--branch") a.branch = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/** Unmerged (conflicting) paths from `git diff --name-only --diff-filter=U`.
+ *  Pure — unit-tested without git. */
+export function parseConflictPaths(text) {
+  return String(text)
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Fetch `origin/<branch>` and merge it into the current branch. Never throws
+ * for an ordinary merge conflict — git's own nonzero exit on `merge` IS the
+ * conflict signal, and we turn it into a `"conflict"` result with the
+ * conflicting paths; a merge failure that ISN'T an ordinary conflict (no
+ * unmerged paths found) rethrows so the caller reports the real failure
+ * instead of a misleading "conflict".
+ *
+ * @param {(cargs:string[]) => string} git  a THROWING `git -C <workspace>` runner
+ *   (execFileSync-backed) — throws carry `.stderr`/`.message` like execFileSync.
+ * @param {{ branch?: string }} [opts]
+ * @returns {{ state: "up-to-date" } | { state: "synced", sha: string } | { state: "conflict", paths: string[] }}
+ */
+export function syncWithBranch(git, { branch = DEFAULT_SYNC_BRANCH } = {}) {
+  git(["fetch", "origin", branch]);
+
+  // How many commits on origin/<branch> the local branch is missing. 0 means
+  // local HEAD already contains everything from the protected branch —
+  // nothing to merge, regardless of how far ahead the local branch itself is.
+  const ahead = git(["rev-list", "--count", `HEAD..origin/${branch}`]).trim();
+  if (ahead === "0") return { state: "up-to-date" };
+
+  try {
+    git(["merge", "--no-edit", `origin/${branch}`]);
+  } catch (e) {
+    const paths = parseConflictPaths(git(["diff", "--name-only", "--diff-filter=U"]));
+    if (paths.length === 0) throw e; // not an ordinary conflict — surface the real failure
+    return { state: "conflict", paths };
+  }
+  const sha = git(["rev-parse", "HEAD"]).trim();
+  return { state: "synced", sha };
+}
+
+/** Render a `syncWithBranch` result in house style; returns the process exit
+ *  code. Pure given its inputs. */
+export function reportSync(result, { branch }) {
+  if (result.state === "up-to-date") {
+    console.log(`\n  ✓ already in sync with origin/${branch} — nothing to merge.`);
+    return 0;
+  }
+  if (result.state === "synced") {
+    console.log(`\n  ✓ synced with origin/${branch} — new HEAD ${result.sha.slice(0, 9)}.`);
+    console.log(`  → next: any prior preview/approval was evidence for the OLD head and is now stale.`);
+    console.log(`    re-run \`tot preview\` to get a fresh candidate + evidence for this head.`);
+    return 0;
+  }
+  // conflict — stop safely; the merge is left in progress for the developer.
+  console.error(fail(`sync conflicts with origin/${branch} — ${result.paths.length} file(s)`) + "\n");
+  for (const p of result.paths) console.error(`  ✗ conflict: ${p}`);
+  console.error(`\n  → next: resolve each conflict above, then \`git add <file>\` and \`git commit\` to finish the merge`);
+  console.error(`    (or \`git merge --abort\` to back out). Once resolved, re-run \`tot preview\` for a fresh candidate.`);
+  return 1;
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (ctx.mode !== "checkout") {
+    console.error(
+      fail(
+        "`tot sync` runs from inside a tenant checkout",
+        "tot clone <tenant> <dir>   (then `cd` in, and re-run)",
+      ),
+    );
+    return 2;
+  }
+
+  const workspace = ctx.workspacePath;
+  const branch = (args.branch || DEFAULT_SYNC_BRANCH).trim();
+  const git = (cargs) => execFileSync("git", ["-C", workspace, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+  const gitSafe = (cargs) => {
+    try {
+      return git(cargs);
+    } catch {
+      return "";
+    }
+  };
+
+  // Refuse a dirty tree up front — a merge on top of uncommitted edits is how
+  // local work gets silently entangled with the merge, and we never sweep
+  // anything in with `git add -A`. Commit or stash first, then re-run.
+  const status = gitSafe(["status", "--porcelain", "--untracked-files=all"]);
+  if (status.trim()) {
+    console.error(
+      fail(
+        "your working tree has uncommitted changes",
+        "commit them, or `git stash --include-untracked`, then re-run `tot sync`",
+      ) + "\n",
+    );
+    for (const line of status.trim().split("\n")) console.error(`  ${line}`);
+    return 2;
+  }
+
+  console.error(`~ fetching origin/${branch}…`);
+  let result;
+  try {
+    result = syncWithBranch(git, { branch });
+  } catch (e) {
+    console.error(
+      fail(
+        `sync failed: ${String(e.stderr || e.message || e)}`,
+        "check your network / that the checkout's remote is reachable, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  return reportSync(result, { branch });
+}

package/src/plan.mjs

@@ -2,9 +2,10 @@
  * The shared "operation plan" affordance (unit U10) — the load-bearing
  * cross-cutting requirement from decision `operator-verb-and-hosting-model`:
  * every MUTATING operator verb (build / accept / ship / retire) must STATE
- * EXACTLY what it will do — which PR moves to main, which deploy targets
- * (preview / live) are touched, and their URLs — and get an explicit confirm
- * before acting. No silent multi-step mutations, in either surface (the CLI
+ * EXACTLY what it will do — which PR is queued/integrated/deployed, which
+ * deploy targets (preview / live) are touched, and their URLs — and get an
+ * explicit confirm before acting. (`accept` now queue-integrates a PR into the
+ * `preview` aggregate — unit b08 — rather than merging it to main.) No silent multi-step mutations, in either surface (the CLI
  * here, and `AdminPublishTab.astro`'s confirm dialog, which renders the same
  * shape of plan text server-side/inline).
  *
@@ -14,13 +15,14 @@
  * half — print the plan, then gate on an explicit yes (reusing `prompt.mjs`'s
  * TTY-safe `promptYesNo`; a non-TTY without `--yes` never silently proceeds).
  *
- * SHIP is context-dependent (decision `ship-context-dependent-semantics`):
- * run by the developer in their own checkout, the candidate is still open, so
- * shipping means accept-then-deploy (merge PR → main, THEN deploy main to
- * preview + live). Run by an operator already targeting a PR that's merged,
- * shipping means just deploy (main → preview + live) — there's nothing left
- * to merge. `planForAction` takes an explicit `context` so the caller (which
- * knows which situation it's in) picks the right narration; it never guesses.
+ * SHIP has ONE meaning (unit b10 — supersedes the retired context-dependent
+ * ship, decision `ship-context-dependent-semantics`): it publishes the
+ * tenant's CURRENT GREEN AGGREGATE — the batch of PRs that integrated
+ * cleanly — to live. No merge, no PR/candidate targeting, no developer-vs-
+ * operator branching. The plan states the pinned aggregate sha, its
+ * content-addressed artifact digest, every included PR, the rollback target,
+ * and the go-live paywall verdict, so the human reviews EXACTLY what "green"
+ * means before confirming.
  *
  * Dependency-free (no imports besides the sibling `prompt.mjs`).
  */
@@ -44,14 +46,23 @@ function targetLabel({ pr, changeId }) {
  * console output, no network, no prompting.
  *
  * @param {{
- *   action: "build"|"accept"|"ship"|"retire",
+ *   action: "build"|"accept"|"ship"|"retire"|"revert"|"cleanup"|"hotfix",
  *   tenant: string,
  *   pr?: number|string|null,
  *   changeId?: string|null,
  *   headSha?: string|null,
+ *   integrationSha?: string|null,
  *   endpoint?: string|null,
  *   targets?: { preview?: string|null, live?: string|null },
  *   context?: "developer"|"operator",
+ *   pinnedSha?: string|null,
+ *   artifactDigest?: string|null,
+ *   includedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>,
+ *   rollbackTarget?: { receiptId: string, aggregateSha: string } | null,
+ *   paywall?: { allowed: boolean, message?: string|null } | null,
+ *   refs?: Array<{ ref: string, sha?: string|null, reason?: string|null }>,
+ *   bypassedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>,
+ *   bypassedPreviewSha?: string|null,
  * }} params
  * @returns {string[]} plan lines (no leading/trailing blank line)
  */
@@ -61,16 +72,28 @@ export function planForAction({
   pr = null,
   changeId = null,
   headSha = null,
+  integrationSha = null,
   endpoint = null,
   targets = {},
   context = "operator",
+  pinnedSha = null,
+  artifactDigest = null,
+  includedPrs = null,
+  rollbackTarget = null,
+  paywall = null,
+  refs = null,
+  bypassedPrs = null,
+  bypassedPreviewSha = null,
 }) {
+  void context; // retained param — no action currently branches on it (ship, the
+  // last one that did, is now ONE meaning; kept so a future action can opt in).
   const label = targetLabel({ pr, changeId });
   const lines = [`${titleFor(action)} plan:`];
   if (tenant) lines.push(`  tenant:    ${tenant}`);
   if (pr != null && `${pr}`.trim()) lines.push(`  PR:        #${pr}`);
   if (changeId) lines.push(`  change id: ${changeId}`);
   if (headSha) lines.push(`  head sha:  ${headSha}`);
+  if (integrationSha) lines.push(`  integration sha: ${integrationSha}`);
   if (endpoint) lines.push(`  endpoint:  POST ${endpoint}`);
 
   switch (action) {
@@ -82,21 +105,43 @@ export function planForAction({
       break;
     }
     case "accept": {
-      lines.push(`  effect:    merge ${label} into main.`);
+      // Accept now means QUEUE-INTEGRATE-INTO-PREVIEW (unit b08), NOT merge-to-main:
+      // the candidate lands in the protected `preview` aggregate (serialized merge →
+      // rebuild → combined-evidence gate), and the aggregate goes live only later via
+      // `tot ship`. So the plan states the integration, never a merge or a go-live.
+      const into = tenant ? `${tenant}'s preview aggregate` : "the preview aggregate";
+      lines.push(
+        `  effect:    queue ${label} for integration into ${into} — NO merge to main, NO go-live.`,
+      );
       break;
     }
     case "ship": {
-      const deployTargets = deployTargetsLine(targets);
-      if (context === "developer") {
-        // The candidate is still open in the developer's own checkout — ship
-        // is accept-then-deploy in one gated step.
-        lines.push(
-          `  effect:    merge ${label} into main, then deploy main → ${deployTargets}.`,
-        );
-      } else {
-        // Operator targeting a PR that's already merged — nothing left to
-        // merge, so ship is just the deploy half.
-        lines.push(`  effect:    deploy main → ${deployTargets}.`);
+      // ONE meaning (b10): publish the tenant's CURRENT GREEN AGGREGATE to live.
+      // No merge — b09's orchestrator ships the already-materialized, already-
+      // reviewed digest. State exactly WHAT that is: the pinned sha, the
+      // content-addressed artifact digest, every included PR, the rollback
+      // target, and the go-live paywall verdict — so the human reviews the
+      // real content of "green" before confirming.
+      lines.push(
+        `  effect:    publish the current green aggregate to live${targets.live ? ` (${targets.live})` : ""} — no merge.`,
+      );
+      if (pinnedSha) lines.push(`  pinned sha:      ${pinnedSha}`);
+      if (artifactDigest) lines.push(`  artifact digest: ${artifactDigest}`);
+      if (Array.isArray(includedPrs)) {
+        lines.push(`  included PRs (${includedPrs.length}):`);
+        for (const p of includedPrs) {
+          const prLabel = p && p.prNumber != null ? `#${p.prNumber}` : p?.changeId || "(no PR)";
+          const shortSha = p && p.headSha ? ` ${String(p.headSha).slice(0, 8)}` : "";
+          lines.push(`    - ${prLabel}${shortSha}`);
+        }
+      }
+      lines.push(
+        rollbackTarget
+          ? `  rollback to: ${rollbackTarget.aggregateSha} (receipt ${rollbackTarget.receiptId})`
+          : "  rollback to: (none — first-ever ship)",
+      );
+      if (paywall && paywall.allowed === false) {
+        lines.push(`  ⚠ paywall:   ${paywall.message || "go-live is blocked by the storefront subscription gate"}`);
       }
       break;
     }
@@ -104,6 +149,67 @@ export function planForAction({
       lines.push(`  effect:    evict ${label}'s preview environment + version (rebuildable).`);
       break;
     }
+    case "cleanup": {
+      // Branch GC (P1 items 9/10): delete ONLY the exact terminal refs a fresh
+      // server-side classification (candidate_list) marked eligible — never by
+      // age alone, never main/preview, never an orphan. State the exact set so
+      // the human confirms precisely what will be removed, not "some branches".
+      const list = Array.isArray(refs) ? refs : [];
+      lines.push(
+        `  effect:    delete ${list.length} terminal candidate branch(es) — never main/preview, ` +
+          "never by age alone, never a quarantined orphan.",
+      );
+      for (const r of list) {
+        const shortSha = r?.sha ? ` ${String(r.sha).slice(0, 8)}` : "";
+        lines.push(`    - ${r?.ref}${shortSha}${r?.reason ? `  — ${r.reason}` : ""}`);
+      }
+      break;
+    }
+    case "revert": {
+      // Revert (b21): REMOVE already-integrated content from the protected `preview`
+      // aggregate by creating a NEW auditable revert commit — never a force-reset,
+      // never a branch delete. The aggregate rebuilds and ships only when green
+      // again. State exactly that: preview-only, a new commit, NO touch to main.
+      const from = tenant ? `${tenant}'s preview aggregate` : "the preview aggregate";
+      const what = integrationSha ? `integration ${integrationSha}` : label;
+      lines.push(
+        `  effect:    revert ${what} out of ${from} — a NEW revert commit, NO force-reset, NO merge to main, NO go-live.`,
+      );
+      break;
+    }
+    case "hotfix": {
+      // Hotfix (b22): the EXPLICIT EXCEPTION lane. Release the reviewed fix from
+      // `main` to live, EXCLUDING the unshipped `preview` work — then automatically
+      // forward-integrate `main` into `preview` and re-validate. State exactly that,
+      // and — critically — list the unshipped preview work this deliberately BYPASSES,
+      // so the human confirms an unmistakable exception, not an ordinary ship.
+      lines.push(
+        `  effect:    OWNER HOTFIX — release ${label} from main to live${targets.live ? ` (${targets.live})` : ""}, ` +
+          `EXCLUDING the unshipped preview head, then forward-integrate main → preview + revalidate.`,
+      );
+      if (Array.isArray(bypassedPrs)) {
+        if (bypassedPrs.length === 0) {
+          lines.push("  bypasses:  (nothing — preview has no unshipped work)");
+        } else {
+          lines.push(`  ⚠ BYPASSES the unshipped preview work (${bypassedPrs.length}) — NOT included in this hotfix:`);
+          for (const p of bypassedPrs) {
+            const prLabel = p && p.prNumber != null ? `#${p.prNumber}` : p?.changeId || "(no PR)";
+            const shortSha = p && p.headSha ? ` ${String(p.headSha).slice(0, 8)}` : "";
+            lines.push(`    - ${prLabel}${shortSha}`);
+          }
+        }
+      }
+      if (bypassedPreviewSha) lines.push(`  preview head (bypassed): ${bypassedPreviewSha}`);
+      lines.push(
+        rollbackTarget
+          ? `  rollback to: ${rollbackTarget.aggregateSha} (receipt ${rollbackTarget.receiptId})`
+          : "  rollback to: (none — first-ever ship)",
+      );
+      if (paywall && paywall.allowed === false) {
+        lines.push(`  ⚠ paywall:   ${paywall.message || "go-live is blocked by the storefront subscription gate"}`);
+      }
+      break;
+    }
     default: {
       lines.push(`  effect:    ${action} ${label}.`);
       break;
@@ -112,22 +218,18 @@ export function planForAction({
   return lines;
 }
 
-/** "build" → "Build-on-demand", "accept" → "Accept", "ship" → "Ship", "retire" → "Retire". Pure. */
+/** "build" → "Build-on-demand", "accept" → "Accept", … "hotfix" → "Hotfix". Pure. */
 function titleFor(action) {
   if (action === "build") return "Build-on-demand";
   if (action === "accept") return "Accept";
   if (action === "ship") return "Ship";
   if (action === "retire") return "Retire";
+  if (action === "revert") return "Revert";
+  if (action === "cleanup") return "Cleanup";
+  if (action === "hotfix") return "Hotfix (owner-only exception lane)";
   return action ? action[0].toUpperCase() + action.slice(1) : "Operation";
 }
 
-/** Render "preview (<url>) + live (<url>)", degrading gracefully when a URL is unknown. Pure. */
-function deployTargetsLine(targets = {}) {
-  const preview = targets.preview ? `preview (${targets.preview})` : "preview";
-  const live = targets.live ? `live (${targets.live})` : "live";
-  return `${preview} + ${live}`;
-}
-
 /**
  * Print a plan and gate on an explicit confirm — the CLI half of the shared
  * affordance. Prints every line, a trailing blank line, then: