@tokenoftrust/cli 1.4.0 → 1.4.1

package/src/commands/revert.mjs

@@ -0,0 +1,322 @@
+/**
+ * `tot revert --preview <PR|integration-sha>` (unit b21) — OPERATOR verb: REMOVE
+ * already-integrated content from the protected `preview` AGGREGATE by creating a
+ * NEW auditable revert commit, then rebuilding the aggregate. It is the explicit,
+ * safe answer to "several candidates are accepted, but one must be removed"
+ * (branch-lifecycle contract): NEVER a force-reset, NEVER a branch delete — a revert
+ * is a new commit on `preview`, and the shared preview moves only when the rebuilt
+ * aggregate is green again. Full history is preserved.
+ *
+ * DISTINCT from `tot ship`: revert is NOT go-live. It touches NO `main` and NO live
+ * channel; it only rewinds the SHARED preview aggregate. The verb is `--preview`-only
+ * by construction — there is no `--main` revert. To undo something already LIVE, use
+ * `tot rollback` (a live re-point), not this.
+ *
+ * TARGET — `--preview <target>` names EITHER a PR number (`42` or `#42`) OR an exact
+ * `preview` integration SHA. A numeric target is sent as `prNumber`; anything else as
+ * `integrationSha`. The server resolves either to the exact integration commit to
+ * undo (unit b21's resolver, inside the tenant-serialized queue lock), and REFUSES a
+ * target that was never integrated or has already been reverted.
+ *
+ * TRANSPORT — `POST /api/changes/revert` (the ONE call site of b07's
+ * `TenantIntegrationQueue.enqueueRevert`). Like `tot accept` / `tot ship`, the CLI
+ * reaches it with the OPERATOR-SECRET Bearer transport (`resolveOperatorSecret` +
+ * `X-Tot-Owner` + `x-tot-capability`). The response is the honest terminal aggregate
+ * state — `queueState` / `runState` / `pointerMoved` / `aggregateSha` /
+ * `revertedSha` / `statusMessage` — rendered VERBATIM, never a bare "reverted".
+ *
+ * HUMAN GATE — rewinding the shared preview is a decision a human makes, so this
+ * ALWAYS states the EXACT plan (a NEW revert commit, NO force-reset, NO touch to
+ * main/live) and requires an explicit confirm. `--yes` is an explicit affirmative; a
+ * non-TTY without `--yes` is refused (mirrors `tot accept` / `tot ship`).
+ *
+ * Dependency-free (global fetch + the shared plan module).
+ */
+import { fail } from "../errors.mjs";
+import { planForAction, printPlanAndConfirm } from "../plan.mjs";
+// Reuse `tot ship`'s operator-secret precedence verbatim so accept + ship + revert
+// speak ONE operator-auth contract.
+import { resolveOperatorSecret } from "./ship.mjs";
+
+const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
+
+const USAGE = `tot revert — remove already-integrated content from the preview aggregate (auditable)
+
+  tot revert --preview <PR|integration-sha> --tenant <t>
+
+  Creates a NEW auditable revert commit on the tenant's protected \`preview\`
+  aggregate that undoes one prior integration, then rebuilds the aggregate and
+  runs combined evidence. The shared preview advances only when it is GREEN
+  again. A revert is NEVER a force-reset and NEVER deletes commits — full history
+  is preserved. It does NOT touch main and does NOT go live.
+
+  <PR|integration-sha> is EITHER a PR number (e.g. 42 or #42) OR an exact preview
+  integration SHA. A target that was never integrated, or has already been
+  reverted, is refused before any change is made.
+
+  Rewinding the shared preview is a human decision: this ALWAYS prints the exact
+  plan and asks for an explicit confirm. A non-TTY without --yes is refused.
+
+Options:
+  --preview <PR|sha>     REQUIRED. The PR number or integration SHA to revert.
+  --tenant <appDomain>   Target tenant (e.g. tokenoftrust.com). Defaults to the
+                         current checkout's tenant when run inside one.
+  --message <msg>        Optional revert-commit message.
+  --url <origin>         storefront origin (default: env TOT_STOREFRONT_URL)
+  --secret <s>           operator secret (prefer the env vars below)
+  --yes, -y              Skip the interactive confirm (still an explicit human
+                         affirmative — there is no default-yes).
+  --help, -h             Show this help.
+
+  To undo something already LIVE, use \`tot rollback\` — not \`tot revert\`.
+
+  Operator secret (from env, first found): PREVIEW_RECONCILE_SECRET,
+  GRANTS_ADMIN_SECRET, TOT_OPERATOR_SECRET (or pass --secret).`;
+
+/** Parse `tot revert` argv. Pure — unit-testable. */
+export function parseRevertArgs(argv) {
+  const a = {
+    preview: null,
+    tenant: null,
+    message: null,
+    url: null,
+    secret: null,
+    yes: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--preview") a.preview = argv[++i];
+    else if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--message" || t === "-m") a.message = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--secret") a.secret = argv[++i];
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+/**
+ * Classify a `--preview` target into `{ prNumber }` or `{ integrationSha }`. A bare
+ * integer (optionally `#`-prefixed) is a PR number; anything else (a hex-ish SHA) is
+ * an integration SHA. Pure — unit-tested.
+ * @param {string|null} raw
+ * @returns {{ prNumber:number|null, integrationSha:string|null }}
+ */
+export function classifyRevertTarget(raw) {
+  const t = (raw || "").trim().replace(/^#/, "");
+  if (!t) return { prNumber: null, integrationSha: null };
+  if (/^\d+$/.test(t)) return { prNumber: Number(t), integrationSha: null };
+  return { prNumber: null, integrationSha: t };
+}
+
+/**
+ * Normalise a `POST /api/changes/revert` body to the honest terminal aggregate
+ * fields this verb renders. Reads defensively so a plausible field rename degrades
+ * rather than crashes. Pure — unit-tested.
+ * @param {any} data
+ */
+export function normalizeRevertResponse(data) {
+  const o = data && typeof data === "object" ? data : {};
+  return {
+    ok: o.ok === true,
+    queueState: typeof o.queueState === "string" ? o.queueState : null,
+    runState: typeof o.runState === "string" ? o.runState : null,
+    pointerMoved: o.pointerMoved === true,
+    aggregateSha: typeof o.aggregateSha === "string" ? o.aggregateSha : null,
+    revertedSha: typeof o.revertedSha === "string" ? o.revertedSha : null,
+    statusMessage: typeof o.statusMessage === "string" ? o.statusMessage : null,
+    reason: typeof o.reason === "string" ? o.reason : null,
+    changeId: typeof o.changeId === "string" ? o.changeId : null,
+    error: typeof o.error === "string" ? o.error : null,
+    raw: data,
+  };
+}
+
+/**
+ * Render the terminal aggregate status in house style — the honest queue/run state,
+ * NEVER a bare "reverted". Pure given its inputs; returns the process exit code.
+ * @param {ReturnType<typeof normalizeRevertResponse>} result
+ * @param {{ tenant:string, label:string }} ctx
+ * @returns {number}
+ */
+export function reportReverted(result, { tenant, label }) {
+  const state = `${result.queueState ?? "?"}/${result.runState ?? "—"}`;
+  if (result.ok) {
+    console.log(`\n  ✓ reverted ${label} out of ${tenant}'s preview aggregate — it is GREEN.`);
+    console.log(`  aggregate: ${state}${result.aggregateSha ? `  (${result.aggregateSha})` : ""}`);
+    if (result.revertedSha) console.log(`  reverted integration commit: ${result.revertedSha}`);
+    if (result.pointerMoved) console.log("  the shared preview pointer moved to the reverted aggregate.");
+    console.log("  → next: review the aggregate preview, then `tot ship` to publish it live.");
+    return 0;
+  }
+  // Honest non-green: the revert did NOT land in the shippable aggregate.
+  console.log(`\n  ✗ ${label} was NOT reverted out of ${tenant}'s preview aggregate.`);
+  console.log(`  aggregate: ${state}${result.reason ? `  (${result.reason})` : ""}`);
+  if (result.statusMessage) console.log(`  why: ${result.statusMessage}`);
+  if (result.reason === "target_not_found" || result.reason === "already_reverted") {
+    console.log(`  → check the target: \`tot ship\` shows the aggregate's included PRs.`);
+  } else {
+    console.log("  → the aggregate is unchanged (last green preserved); fix forward or retry.");
+  }
+  return 1;
+}
+
+/**
+ * The revert flow after args are parsed: state the exact plan, confirm, then POST
+ * `/api/changes/revert` (operator-secret transport) and render the honest terminal
+ * aggregate status. `fetch`/`confirmPlan` injected so it is unit-tested with no
+ * network/TTY.
+ *
+ * @param {{ tenant:string, prNumber:number|null, integrationSha:string|null,
+ *   message:string|null, secret:string, storefrontUrl?:string|null, yes?:boolean }} params
+ * @param {{ fetch?:typeof fetch, confirmPlan?:typeof printPlanAndConfirm }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runRevert(
+  { tenant, prNumber, integrationSha, message = null, secret, storefrontUrl = null, yes = false },
+  deps = {},
+) {
+  const fetchImpl = deps.fetch || globalThis.fetch;
+  const confirmPlan = deps.confirmPlan || printPlanAndConfirm;
+  const base = (storefrontUrl || DEFAULT_STOREFRONT_URL).trim().replace(/\/+$/, "");
+  const label = prNumber != null ? `PR #${prNumber}` : `integration ${integrationSha}`;
+
+  // 1. State the EXACT plan (shared U10 affordance) — a NEW revert commit on
+  //    preview, NO force-reset, NO touch to main/live — and gate on a confirm.
+  const planLines = planForAction({
+    action: "revert",
+    tenant,
+    pr: prNumber,
+    integrationSha,
+  });
+  const { confirmed, reason } = await confirmPlan(planLines, {
+    yes,
+    question: `Revert ${label} out of ${tenant}'s preview aggregate (a new revert commit)?`,
+  });
+  if (!confirmed) {
+    if (reason === "non-tty") {
+      console.error(
+        fail(
+          "refusing to revert without confirmation on a non-TTY.",
+          "re-run with --yes (an explicit human affirmative), or from an interactive terminal.",
+        ),
+      );
+      return 2;
+    }
+    console.log("Aborted — nothing was reverted.");
+    return 1;
+  }
+
+  // 2. Operator-secret transport — the CLI holds no storefront cookie.
+  if (!secret) {
+    console.error(
+      fail(
+        "reverting the preview aggregate is an OPERATOR action — it needs an operator secret",
+        "set PREVIEW_RECONCILE_SECRET (or GRANTS_ADMIN_SECRET / TOT_OPERATOR_SECRET), or pass --secret",
+      ),
+    );
+    return 2;
+  }
+  const authHeaders = {
+    "content-type": "application/json",
+    authorization: `Bearer ${secret}`,
+    "x-tot-owner": tenant,
+    "x-tot-capability": "ship-on-behalf",
+  };
+  const requestBody = {
+    repo: tenant,
+    ...(prNumber != null ? { prNumber } : {}),
+    ...(integrationSha ? { integrationSha } : {}),
+    ...(message ? { message } : {}),
+  };
+
+  // 3. POST the honest revert path (b07 queue enqueueRevert) and render terminal state.
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/changes/revert`, {
+      method: "POST",
+      headers: authHeaders,
+      body: JSON.stringify(requestBody),
+    });
+  } catch (e) {
+    console.error(
+      fail(`couldn't reach the revert endpoint at ${base}: ${String(e?.message || e)}`, "check --url / your network, then re-run"),
+    );
+    return 1;
+  }
+
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
+    /* non-JSON / empty body */
+  }
+  const result = normalizeRevertResponse(data);
+
+  // A pre-flight error (auth, unknown tenant, bad body) is an HTTP 4xx with
+  // `{ error }` and no queue verdict — surface it distinctly from a red run.
+  if (!res.ok && result.queueState == null) {
+    const msg = result.error || `HTTP ${res.status}`;
+    console.error(
+      fail(
+        `the revert request was refused: ${msg}`,
+        res.status === 401 || res.status === 403
+          ? "check the operator secret and that it's authorised for this tenant"
+          : "check --tenant / --url / --preview, then re-run",
+      ),
+    );
+    return 1;
+  }
+
+  return reportReverted(result, { tenant, label });
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseRevertArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const tenant = (args.tenant || ctx?.tenant || "").trim();
+  if (!tenant) {
+    console.error(
+      fail(
+        "no target tenant.",
+        "pass --tenant <appDomain> (e.g. --tenant tokenoftrust.com), or run inside a store checkout.",
+      ),
+    );
+    return 2;
+  }
+
+  const { prNumber, integrationSha } = classifyRevertTarget(args.preview);
+  if (prNumber == null && !integrationSha) {
+    console.error(
+      fail(
+        "no revert target.",
+        "pass --preview <PR|integration-sha> (a PR number like 42, or an exact preview integration SHA).",
+      ),
+    );
+    return 2;
+  }
+
+  const storefrontUrl =
+    args.url || env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL;
+
+  return await runRevert({
+    tenant,
+    prNumber,
+    integrationSha,
+    message: (args.message || "").trim() || null,
+    secret: resolveOperatorSecret(args.secret, env),
+    storefrontUrl,
+    yes: args.yes,
+  });
+}

package/src/commands/ship.mjs

@@ -47,6 +47,7 @@ import { fail } from "../errors.mjs";
 import { planForAction, printPlanAndConfirm } from "../plan.mjs";
 import { startProgress } from "../progress.mjs";
 import { openBrowser } from "../open.mjs";
+import { emitActivity } from "../activity.mjs";
 
 const DEFAULT_STOREFRONT_URL = "https://storefront.tokenoftrust.store";
 
@@ -149,9 +150,10 @@ export function normalizeChangesQueue(data) {
 
 // ─── Shared with `tot accept` (`accept.mjs`) ─────────────────────────────────────
 //
-// `tot accept` merges a PR into main over the MCP `change_accept`/`change_status`
-// tools — a DISTINCT operator verb from ship (no deploy). It imports these two
-// normalisers straight from here rather than re-implementing them.
+// `tot accept` queues a PR's integration into the protected `preview` aggregate
+// (NOT a merge to main — see accept.mjs's header) — a DISTINCT operator verb from
+// ship (no deploy). It imports these two normalisers straight from here rather
+// than re-implementing them.
 
 /**
  * Normalise a `change_accept` / `change_status` result to { shipped, state,
@@ -413,7 +415,25 @@ export async function runShip({ tenant, secret, storefrontUrl = null, yes = fals
   const shipData = await readJsonSafe(shipRes);
   progress?.stop();
 
-  return reportShipResult(normalizeShipResult(shipData), { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
+  const shipResult = normalizeShipResult(shipData);
+  // D3: emit the ship publish lifecycle event — `tot ship` does no LOCAL git op
+  // (it's HTTP-orchestrated), so this marks the outcome of the publish step
+  // itself, distinct from the outer command's invoked/result pair. Fire-and-
+  // forget best-effort: a silent no-op without a hosted-bridge credential, never
+  // awaited, never throws, never alters the ship. `errorClass` stays low-
+  // cardinality (the orchestrator's own terminal state/reason, never free text).
+  const shipped = shipResult.state === "shipped";
+  void emitActivity({
+    action: "cli.command.result",
+    outcome: {
+      status: shipped ? "succeeded" : "failed",
+      ...(shipped ? {} : { errorClass: `ship_${shipResult.state}` }),
+    },
+    scope: { tenantId: tenant },
+    payload: { args: { command: "ship", subcommand: "ship.publish" } },
+  });
+
+  return reportShipResult(shipResult, { tenant, liveUrl, noOpen, openUrl: deps.openUrl });
 }
 
 /**

package/src/commands/start.mjs

@@ -67,7 +67,7 @@ import {
   activityBridgeEnv, NativeArtifactUnavailableError,
 } from "./dev.mjs";
 import { scaffoldSample, isSampleCheckout, sampleConfig, SAMPLE_DIR_NAME } from "../sample.mjs";
-import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
+import { startHeartbeatFromEnv, resolveEditor } from "../dev-heartbeat.mjs";
 import { streamDevLogs } from "../dev-logs.mjs";
 import { milestoneBanner, cockpitUrlFrom, DEVELOPER_COCKPIT } from "../banner.mjs";
 import { IDEAS } from "./ideas.mjs";
@@ -318,7 +318,7 @@ export async function run(argv, ctx) {
     // (A3) so the "instant" claim is measured. The "Connect Claude" step is
     // intentionally removed for now — a blocking prompt here meant Ctrl-C'ing it
     // tore down the dev server; revisit AI-connect as a non-blocking step later.
-    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt), cockpitUrl);
+    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt), cockpitUrl, dir);
 
     // 7. hand the terminal to the running dev server until Ctrl-C.
     console.log("\n  Watching your store — edit content/home.html + save. Ctrl-C to stop.\n");
@@ -693,11 +693,34 @@ function printCheckoutLanding(dir, cockpitUrl = null) {
   console.log(`     content/home.html — you'll see it reflected in ${where}.`);
 }
 
+/**
+ * OS/editor-aware suggestions for opening the checkout, shown once at the
+ * "you're live" moment. $VISUAL/$EDITOR (same signal the cockpit's "open this
+ * file" hint uses — see dev-heartbeat.mjs#resolveEditor) wins when set;
+ * otherwise a short per-platform shortlist of common editor launch commands.
+ * Deliberately NOT probed against PATH — a spawnSync per candidate would add
+ * real latency to the crafted "aha" ending for the common case (nothing set),
+ * so this is a labeled suggestion list, not a detection result.
+ */
+function editorOpenLines(dir, { platform = process.platform, env = process.env } = {}) {
+  const configured = resolveEditor(env);
+  if (configured) return [`${configured} ${dir}`];
+  if (platform === "darwin") {
+    return [`code ${dir}      (VS Code, if installed)`, `cursor ${dir}    (Cursor, if installed)`, `open ${dir}      (Finder)`];
+  }
+  if (platform === "win32") {
+    return [`code ${dir}      (VS Code, if installed)`, `explorer ${dir}  (File Explorer)`];
+  }
+  return [`code ${dir}      (VS Code, if installed)`, `cursor ${dir}    (Cursor, if installed)`, `xdg-open ${dir}  (file manager)`];
+}
+
 /** The crafted "you're live" ending — a PROMINENT milestone banner (u2) that,
  * when we hold a Developer Cockpit URL, explicitly sends the developer BACK to
- * their cockpit as the next place to look; then the AI-wow (G), seeded with
- * IDEAS[0] (G2/G3 — one prompt list shared with `tot ideas`, no drift). */
-function printLiveEnding(tenant, url, elapsed, cockpitUrl = null) {
+ * their cockpit as the next place to look. Then: an OS-suited "open this in
+ * an editor" suggestion, and the four-pane layout tip (this terminal, cockpit,
+ * local preview, editor) so a build problem, a reload, and the code are never
+ * more than a glance apart. */
+function printLiveEnding(tenant, url, elapsed, cockpitUrl = null, dir = null) {
   const lines = [
     `✨  You're live.${elapsed ? `  (${elapsed})` : ""}`,
     `    ${url}`,
@@ -711,10 +734,19 @@ function printLiveEnding(tenant, url, elapsed, cockpitUrl = null) {
   console.log(milestoneBanner(lines));
   console.log("  " + versionStamp("native"));
   console.log("");
-  console.log("  Now try, in Claude:");
-  console.log(`     "${IDEAS[0]}"`);
+  if (dir) {
+    console.log("  Open your project in an editor (an AI coding agent like Claude works too —");
+    console.log("  same idea, different hands on the keyboard):");
+    for (const line of editorOpenLines(dir)) console.log(`     ${line}`);
+    console.log("");
+  }
+  console.log("  Keep THIS terminal open — it's your live build/status feed, the fastest way to");
+  console.log("  see a problem the moment it happens. Need the command line for something else?");
+  console.log("  Open a NEW terminal window rather than closing this one.");
   console.log("");
-  console.log("  More ideas: tot ideas");
+  console.log("  Best view: arrange this terminal, your Developer Cockpit, the local preview,");
+  console.log("  and your editor so you can see all four at once — site, cockpit, build status,");
+  console.log("  and code, together.");
   console.log("");
 }