@tokenoftrust/cli 1.4.0-rc.2 → 1.4.0-rc.20

package/README.md

@@ -5,11 +5,12 @@ One command to go from a Token of Trust invite to a running store.
 ```sh
 npm i -g @tokenoftrust/cli
 
-tot checkout                 # list the stores you can build on
-tot checkout <tenant> --clone ./my-store
+tot clone                    # list the stores you can build on
+tot clone <tenant> my-store  # mirrors `git clone`; dir defaults to <tenant>
 cd my-store
 tot dev                      # run it locally with save→reload — no Docker needed
-tot submit                   # (coming) submit it for preview
+tot preview                  # bundle your edits into a compliance-reviewed preview
+tot ship                     # promote a reconciled preview live (diff + one confirm)
 ```
 
 **Prerequisites: Node.js and an invite. Nothing else.** `tot dev` downloads the
@@ -22,10 +23,12 @@ be fetched.)
 
 | Command | Status | What it does |
 | --- | --- | --- |
-| `tot checkout [<tenant>]` | **built** | Clone a store you're entitled to build on, with an authenticated remote configured. No arg → list your stores. |
-| `tot validate` | next | Lint your store before you submit. |
+| `tot clone [<tenant>] [<dir>]` | **built** | Clone a store you're entitled to build on (mirrors `git clone`), with an authenticated remote configured. Dir defaults to `<tenant>`. No arg → list your stores. |
+| `tot validate` | next | Lint your store before you preview. |
 | `tot dev` | **built** | Run your store locally with save→reload — NATIVELY (no Docker; falls back to it with `--docker` or automatically if the native artifact isn't available). |
-| `tot submit` | next | Submit your store for preview (pushes the preview ref, reports the reconcile/compliance verdict + preview URL). |
+| `tot preview` | **built** | Bundle your edits into a compliance-reviewed preview (validates, auto-commits the known content trees, pushes the preview ref, opens/updates a candidate PR, reports the reconcile/compliance verdict + preview URL). `tot submit` / `tot deploy` still work as teaching aliases for this same flow. |
+| `tot ship` | **built** | Promote a reconciled preview live: always shows a diff-vs-live and asks for one `[y/N]` confirm (no `--yes`, refuses outside a terminal); records an approval request if you're not authorised to ship yourself. |
+| `tot pr [list\|view\|close]` | **built** | See and manage the candidate PRs `tot preview` opens (`gh pr`-shaped). |
 | `tot doctor` | built | Check this machine is ready and show which context `tot` detected. |
 
 ## Context-aware
@@ -34,7 +37,7 @@ The same `tot` does the right thing wherever you run it (walks up like `git`):
 
 - **storefront monorepo** — a full platform checkout;
 - **tenant checkout** — a standalone `content/ public/ theme.json .tot/config.json` clone (tenant read from `.tot/config.json`);
-- **loose** — anywhere else; `tot checkout <tenant> --clone <dir>` gets you a checkout.
+- **loose** — anywhere else; `tot clone <tenant>` gets you a checkout.
 
 `tot doctor` prints the detected context.
 
@@ -42,8 +45,8 @@ The same `tot` does the right thing wherever you run it (walks up like `git`):
 
 `tot` talks to the Token of Trust MCP (default `https://mcp.tokenoftrust.com`, override with `--mcp` or `MCP_BASE_URL`). It is **single-plane**: the only identity is **you**, signed in against the MCP over OAuth.
 
-- Run `tot login` once — it opens your browser (or falls back to a device code on a headless box), you sign in as yourself, and the session is cached at `~/.tot/credentials.json` and refreshed silently. Every later command (`tot checkout`, `tot start`, `tot submit`, …) runs as you, with no re-auth. Entitlement is derived server-side from your ToT memberships.
-- Not signed in? On a terminal, `tot start` / `tot checkout` **offer to sign you in right there** and continue in-flow — no "run `tot login`, then re-run".
+- Run `tot login` once — it opens your browser (or falls back to a device code on a headless box), you sign in as yourself, and the session is cached at `~/.tot/credentials.json` and refreshed silently. Every later command (`tot clone`, `tot start`, `tot preview`, `tot ship`, …) runs as you, with no re-auth. Entitlement is derived server-side from your ToT memberships.
+- Not signed in? On a terminal, `tot start` / `tot clone` **offer to sign you in right there** and continue in-flow — no "run `tot login`, then re-run".
 - The old operator env-triple (`TOT_API_KEY` / `TOT_SECRET_KEY` / `TOT_APP_DOMAIN`) **no longer signs the CLI in** — tot-mcp went OAuth-first on 2026-07-23. If those vars are set, `tot` prints a one-line advisory and uses your `tot login` session anyway; it never reads them for auth.
 
 ### Optional: multiple identities at once (`TOT_PROFILE`)

package/bin/tot.mjs

@@ -8,11 +8,19 @@
  *   tot login                 sign in to Token of Trust (OAuth)          ← built (MCP OAuth PKCE loopback; caches ~/.tot/credentials.json)
  *   tot logout                sign out (clear the cached session)        ← built (deletes ~/.tot/credentials.json; local-only, no server revoke)
  *   tot whoami                who you're signed in as                    ← built
+ *   tot link                  link your identity to the ToT broker (resolve store scope)  ← built
  *   tot grants                capability/tier/expiry per store you can act on  ← built (introspection diagnostics)
- *   tot checkout [<tenant>]   clone a store you can build on            ← built
+ *   tot clone [<tenant>]      clone a store you can build on            ← built
  *   tot validate              lint your store before you submit         ← built
  *   tot dev                   run your store locally with save→reload   ← built (monorepo: host astro; standalone: runs the published runner image)
- *   tot submit                submit your store for preview             ← built (validate + push preview ref; MCP preview_status read-back)
+ *   tot preview               push your store to a reviewable preview   ← built (validate + push preview ref; MCP preview_status read-back). `submit`/`deploy` are teaching aliases.
+ *   tot ship                  publish the current green aggregate live  ← built (GET/POST /api/changes/ship → b09 orchestrator; exact plan + y/N confirm; waits for VERIFIED live truth)
+ *   tot accept / tot merge    queue a PR into the preview aggregate      ← built (b08: plan + y/N confirm → POST /api/changes/integrate = b07 queue enqueue; NO merge-to-main, NO go-live; refuses non-TTY without --yes)
+ *   tot sync                  fetch `preview` + merge it into your branch ← built (b16: the common accept-conflict recovery path; local-only, stops safely on conflict)
+ *   tot rollback [<version>]  instant re-point to a prior live version  ← built (u3 promotion_status/promotion_rollback seam; diff + y/N confirm; refuses non-TTY / ineligible)
+ *   tot pr                    list / view / close your candidate PRs    ← built (candidate_status/candidate_close; gh-pr-shaped)
+ *   tot branches              full branch-cleanup report (every branch, not just open PRs)  ← built (b14: candidate_list)
+ *   tot cleanup               owner-confirmed branch GC (deletes terminal branches only)     ← built (b14: candidate_list + candidate_delete; --dry-run classifies only)
  *   tot doctor                check this machine is ready
  *   tot ideas                 copy-paste AI prompts that reliably wow
  *   tot feedback              send a note to ToT + your recent CLI activity  ← built (activity-log.mjs → feedback_submit MCP tool)
@@ -24,7 +32,7 @@
  * from anywhere else. Every command receives the detected context.
  *
  * This package is `@tokenoftrust/cli` (bin `tot`). Its heaviest command, `tot dev`,
- * fetches the published storefront runner; `tot checkout/validate/submit` are
+ * fetches the published storefront runner; `tot clone/validate/submit` are
  * pure Node. Dependency-free by design so `npm i -g @tokenoftrust/cli` stays light.
  */
 import "../src/ensure-node.mjs"; // hard Node-version gate — must stay first (see the module doc)
@@ -32,9 +40,10 @@ import { readFileSync } from "node:fs";
 import { detectContext } from "../src/context.mjs";
 import { printError } from "../src/errors.mjs";
 import { recordActivity, redactArgs } from "../src/activity-log.mjs";
+import { emitActivity, capRendered } from "../src/activity.mjs";
 import { maybeNotifyUpdate } from "../src/update-check.mjs";
 
-const BUILD_ORDER = ["checkout", "validate", "dev", "submit"];
+const BUILD_ORDER = ["clone", "validate", "dev", "preview"];
 
 // CLI version (stamped into the activity log). Read from our own package.json; best-effort.
 const VERSION = (() => {
@@ -53,11 +62,23 @@ tot — Token of Trust developer CLI
   tot login                 sign in to Token of Trust
   tot logout                sign out (clear the cached session)
   tot whoami                show who you're signed in as
+  tot link                  link your identity so your stores resolve
   tot grants                capability/tier/expiry per store you can act on
-  tot checkout [<tenant>]   clone a store you can build on
+  tot clone [<tenant>]      clone a store you can build on
   tot validate              lint your store before you submit
   tot dev                   run your store locally with save→reload
-  tot submit                submit your store for preview
+  tot preview               push your store to a reviewable preview
+  tot ship                  publish the tenant's current green aggregate live (plan → confirm → ship)
+  tot accept / tot merge    queue a PR into the preview aggregate — operator verb, no go-live (plan → confirm → integrate)
+  tot sync                  fetch \`preview\` and merge it into your local branch (accept-conflict recovery)
+  tot rollback [<version>]  instant re-point to a prior live version (list → confirm → rollback)
+  tot revert --preview <PR|sha>  remove already-integrated content from the preview aggregate via a new revert commit — no force-reset (plan → confirm → revert)
+  tot hotfix --pr <N>       OWNER-ONLY exception: release an urgent fix from main to live, bypassing unshipped preview work (plan → confirm → release → auto forward-integrate)
+  tot retire                evict a candidate PR's preview to reclaim space — operator verb, rebuildable (plan → confirm → evict)
+  tot go-live               cut the apex domain over to the storefront (readiness → confirm → cutover)
+  tot pr                    list / view / close your candidate PRs
+  tot branches              full branch-cleanup report — every branch, any PR state, cleanup eligibility
+  tot cleanup               owner-confirmed branch GC (--dry-run to classify only; deletes terminal branches only)
   tot doctor                check this machine is ready
   tot ideas                 copy-paste AI prompts that reliably wow
   tot feedback "<msg>"      send feedback to Token of Trust (attaches recent activity)
@@ -109,6 +130,11 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  if (cmd === "link") {
+    const { run } = await import("../src/commands/link.mjs");
+    return run(rest, ctx);
+  }
+
   if (cmd === "doctor") {
     const { run } = await import("../src/commands/doctor.mjs");
     return run(rest, ctx);
@@ -124,8 +150,8 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
-  if (cmd === "checkout") {
-    const { run } = await import("../src/commands/checkout.mjs");
+  if (cmd === "clone") {
+    const { run } = await import("../src/commands/clone.mjs");
     return run(rest, ctx);
   }
 
@@ -139,8 +165,103 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
-  if (cmd === "submit") {
-    const { run } = await import("../src/commands/submit.mjs");
+  // dev → preview → ship. `preview` is the first-class verb; `submit`/`deploy`
+  // reach the SAME preview flow as teaching aliases (preview.mjs prints a one-line
+  // hint nudging the developer onto `tot preview` / `tot ship`).
+  if (cmd === "preview") {
+    const { run } = await import("../src/commands/preview.mjs");
+    return run(rest, ctx);
+  }
+
+  if (cmd === "submit" || cmd === "deploy") {
+    const { run } = await import("../src/commands/preview.mjs");
+    return run(rest, ctx, { alias: cmd });
+  }
+
+  if (cmd === "ship") {
+    const { run } = await import("../src/commands/ship.mjs");
+    return run(rest, ctx);
+  }
+
+  // `accept` queue-integrates a PR into the protected `preview` aggregate (b08) —
+  // NO merge-to-main, NO go-live; going live is `tot ship`, which publishes the
+  // whole current GREEN AGGREGATE (b10). Backed by POST /api/changes/integrate
+  // (b07's TenantIntegrationQueue.enqueue); see accept.mjs's header. `merge` is a
+  // first-class alias, not a teaching nudge: both dispatch straight to the same command.
+  if (cmd === "accept" || cmd === "merge") {
+    const { run } = await import("../src/commands/accept.mjs");
+    return run(rest, ctx);
+  }
+
+  // `sync` is the common accept-conflict recovery path (P1 item 12): fetches the
+  // protected `preview` branch and merges it into the developer's local branch so
+  // they can resolve locally, then re-`tot preview`. Purely local — no push, no
+  // MCP call, never touches the shared `preview`/`main` refs themselves. See
+  // sync.mjs's header for the full contract.
+  if (cmd === "sync") {
+    const { run } = await import("../src/commands/sync.mjs");
+    return run(rest, ctx);
+  }
+
+  if (cmd === "rollback") {
+    const { run } = await import("../src/commands/rollback.mjs");
+    return run(rest, ctx);
+  }
+
+  // `revert --preview <PR|integration-sha>` removes already-integrated content from
+  // the protected `preview` aggregate via a NEW auditable revert commit (b21) — NO
+  // force-reset, NO touch to main/live. Backed by POST /api/changes/revert (b07's
+  // TenantIntegrationQueue.enqueueRevert). To undo something already LIVE, that's
+  // `tot rollback`, not this. See revert.mjs's header.
+  if (cmd === "revert") {
+    const { run } = await import("../src/commands/revert.mjs");
+    return run(rest, ctx);
+  }
+
+  // `hotfix --pr <N>` is the OWNER-ONLY EXCEPTION lane (b22): release an urgent fix
+  // from `main` to live while `preview` still holds other unshipped work, EXCLUDING
+  // that unshipped preview head, then automatically forward-integrate main → preview
+  // and re-validate. It is DELIBERATELY a distinct verb — never a `--base main` flag
+  // on `tot ship` (which publishes the whole green preview aggregate). Backed by
+  // GET/POST /api/changes/hotfix → b22's HotfixOrchestrator. See hotfix.mjs's header.
+  if (cmd === "hotfix") {
+    const { run } = await import("../src/commands/hotfix.mjs");
+    return run(rest, ctx);
+  }
+
+  // `retire` evicts a candidate PR's hosted preview to reclaim space (unit U7) —
+  // a DISTINCT operator verb from `accept`/reject: retire touches no change
+  // lifecycle and is reversible-by-rebuild (`tot preview build`). See retire.mjs.
+  if (cmd === "retire") {
+    const { run } = await import("../src/commands/retire.mjs");
+    return run(rest, ctx);
+  }
+
+  if (cmd === "go-live") {
+    const { run } = await import("../src/commands/go-live.mjs");
+    return run(rest, ctx);
+  }
+
+  if (cmd === "pr") {
+    const { run } = await import("../src/commands/pr.mjs");
+    return run(rest, ctx);
+  }
+
+  // `branches` is the FULL branch-cleanup report (every branch, any PR state) —
+  // distinct from `tot pr list`, which only shows OPEN PRs (P1 item 9). Read-only;
+  // always safe to run, and the report `tot cleanup` reuses before deleting anything.
+  if (cmd === "branches") {
+    const { run } = await import("../src/commands/branches.mjs");
+    return run(rest, ctx);
+  }
+
+  // `cleanup` is owner-confirmed BRANCH GC (P1 items 9/10) — an irreversible git-ref
+  // delete, distinct from `tot retire`'s hosted-preview eviction (rebuildable, no
+  // branch touched). `--dry-run` classifies and prints; it never deletes. Age alone
+  // never makes a branch eligible; main/preview are always kept; orphans are
+  // quarantined, never auto-deleted. See cleanup.mjs's header.
+  if (cmd === "cleanup") {
+    const { run } = await import("../src/commands/cleanup.mjs");
     return run(rest, ctx);
   }
 
@@ -149,10 +270,21 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  // `checkout` was deliberately freed up: it's no longer a tot verb precisely so it
+  // can mean what it means in git. Point both ways rather than a bare "unknown".
+  if (cmd === "checkout") {
+    console.error(
+      "`tot checkout` isn't a tot command — `checkout` now means what it does in git.\n\n" +
+        "  • switch branches / restore files in your store:  git checkout <ref>\n" +
+        "  • clone a store you can build on:                 tot clone <tenant>\n",
+    );
+    return 2;
+  }
+
   if (BUILD_ORDER.includes(cmd)) {
     console.error(
       `\`tot ${cmd}\` isn't built yet.\n\n` +
-        `Build order: ${BUILD_ORDER.map((c) => (c === "checkout" ? `${c}✓` : c)).join(" → ")}.\n` +
+        `Build order: ${BUILD_ORDER.map((c) => (c === "clone" ? `${c}✓` : c)).join(" → ")}.\n` +
         `Inside a storefront checkout you can use the in-repo scripts today ` +
         `(e.g. \`pnpm tot ${cmd}\`).`,
     );
@@ -164,12 +296,39 @@ async function dispatch(cmd, rest, ctx) {
   return 2;
 }
 
+/**
+ * The safe `subcommand` value for a command's activity event. Only the fixed
+ * sub-dispatcher verbs (e.g. `app scaffold` / `app dev`) are surfaced — an
+ * arbitrary positional (a tenant name, a path, a code) is NEVER used, so the
+ * activity `subcommand` field can't carry PII even before redaction. Returns
+ * undefined for every command without a fixed subcommand vocabulary.
+ */
+function safeSubcommand(cmd, rest) {
+  if (cmd === "app") {
+    const sub = rest.find((t) => t && !t.startsWith("-"));
+    if (sub === "scaffold" || sub === "dev") return sub;
+  }
+  return undefined;
+}
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   const ctx = detectContext();
   const startedAt = Date.now();
+  const command = cmd || "(none)";
+  const subcommand = safeSubcommand(cmd, rest);
   let code = 0;
   let errMsg = null;
+
+  // D3: emit `cli.command.invoked` on start — best-effort, a SILENT no-op without a
+  // hosted-bridge credential (never a network call / never blocks). Fired without
+  // await so it adds no latency to the command; settled alongside the result below.
+  const invokedEmit = emitActivity({
+    action: "cli.command.invoked",
+    outcome: { status: "invoked" },
+    payload: { args: { command, ...(subcommand ? { subcommand } : {}), cliVersion: VERSION, node: process.version } },
+  });
+
   try {
     code = await dispatch(cmd, rest, ctx);
     return code;
@@ -177,17 +336,35 @@ async function main() {
     errMsg = e?.message || String(e);
     throw e;
   } finally {
+    const exitCode = errMsg ? 1 : (code ?? 0);
+    const durationMs = Date.now() - startedAt;
     // Best-effort activity breadcrumb (never throws, never blocks). `feedback`'s own
     // free-text message is omitted — it's user-typed and belongs only in the report.
     recordActivity({
       ts: new Date().toISOString(),
       v: VERSION,
-      cmd: cmd || "(none)",
+      cmd: command,
       args: cmd === "feedback" ? ["«omitted»"] : redactArgs(rest),
-      code: errMsg ? 1 : (code ?? 0),
-      ms: Date.now() - startedAt,
+      code: exitCode,
+      ms: durationMs,
       ...(errMsg ? { err: String(errMsg).slice(0, 200) } : {}),
     });
+    // D3: emit `cli.command.result` (exit code + duration + a bounded/redacted
+    // rendered field). The house-style error text is capped + run through the JS
+    // redaction mirror; per the D0 catalog the `cli.*` rendered lane is empty-
+    // allowlisted, so it's DROPPED by design (the safe default for a high-volume
+    // action) — the emit path still exercises the mirror. Bounded-await here (with
+    // the invoked emit) so a live bridge flushes before the process exits; a no-op
+    // when there's no credential.
+    const resultEmit = emitActivity({
+      action: "cli.command.result",
+      outcome: { status: errMsg ? "failed" : "succeeded", durationMs },
+      payload: {
+        args: { command, ...(subcommand ? { subcommand } : {}), cliVersion: VERSION, exitCode, durationMs },
+        ...(errMsg ? { rendered: { output: capRendered(errMsg) } } : {}),
+      },
+    });
+    await Promise.allSettled([invokedEmit, resultEmit]);
     // Nudge if a newer/unsupported version exists (drawn from cache — instant),
     // and kick a detached registry refresh if stale. Never throws, never blocks.
     maybeNotifyUpdate(VERSION);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.4.0-rc.2",
-  "description": "Token of Trust developer CLI — check out a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
+  "version": "1.4.0-rc.20",
+  "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",
   "homepage": "https://www.tokenoftrust.com",