@tokenoftrust/cli 1.4.0-rc.0 → 1.4.0-rc.10

package/src/commands/pr.mjs

@@ -0,0 +1,200 @@
+/**
+ * `tot pr` — see and manage the candidate PRs `tot submit` opens, mirroring
+ * `gh pr`.
+ *
+ *   tot pr [list]        list your OPEN candidate PRs for this store
+ *   tot pr view <N|id>   show one candidate (by PR number or changeId)
+ *   tot pr close <N|id>  close (reject) a candidate without merging
+ *
+ * A candidate PR is the reviewable unit `tot submit` creates. By default a
+ * re-submit UPDATES your open candidate; `tot submit --new` forks another. This
+ * command fills the gap the raw submit loop left — a first-party way to list your
+ * open candidates and to close one (candidate close was otherwise gated to
+ * version-control apps only).
+ *
+ * Runs from inside a tenant checkout (it derives the forge repo from the
+ * checkout's origin remote, exactly as `tot submit` does) and reads over the MCP
+ * `candidate_status` / `candidate_close` tools. Dependency-free (global fetch +
+ * `git`).
+ */
+import { execFileSync } from "node:child_process";
+import { createMcpClient } from "../mcp.mjs";
+import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { fail } from "../errors.mjs";
+import { repoNameFromRemote } from "./submit.mjs";
+import {
+  defaultCandidateStatePath,
+  readActiveChangeId,
+  clearActiveChangeId,
+} from "../candidate-state.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+const SUBCOMMANDS = ["list", "view", "close"];
+
+const USAGE = `tot pr — see and manage your candidate PRs
+
+  tot pr [list]              list your open candidate PRs for this store
+  tot pr view <N|id>         show one candidate PR (by PR number or changeId)
+  tot pr close <N|id>        close (reject) a candidate PR without merging
+  tot pr close <N|id> --reason "<why>"   record why it was closed (audit note)
+  tot pr --mcp <url>         MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+
+  A candidate PR is what \`tot submit\` opens for review. A re-submit updates your
+  open one by default; \`tot submit --new\` forks another. Use these to see and
+  manage them.`;
+
+/** Parse `tot pr` argv into { sub, target, reason, mcp, identity, help }. Pure. */
+export function parsePrArgs(argv) {
+  const a = { sub: null, target: null, reason: null, mcp: null, identity: null, help: false };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--reason") a.reason = argv[++i];
+    else if (t === "--help" || t === "-h") a.help = true;
+    else positional.push(t);
+  }
+  a.sub = positional[0] || "list";
+  a.target = positional[1] ?? null;
+  return a;
+}
+
+/** Normalize the `candidate_status` list response to a flat candidate array. Pure. */
+export function extractCandidates(result) {
+  if (Array.isArray(result)) return result;
+  if (result && Array.isArray(result.candidates)) return result.candidates;
+  if (result && Array.isArray(result.environments)) return result.environments;
+  if (result && typeof result.changeId === "string") return [result];
+  return [];
+}
+
+/** Find a candidate by PR number (all-digits target) or exact changeId. Pure. */
+export function matchCandidate(candidates, target) {
+  if (target == null) return null;
+  if (/^\d+$/.test(target)) {
+    const n = Number(target);
+    return candidates.find((c) => c.prNumber === n) ?? null;
+  }
+  return candidates.find((c) => c.changeId === target) ?? null;
+}
+
+/** One-line candidate summary for `tot pr list`. */
+function line(c) {
+  const pr = typeof c.prNumber === "number" ? `#${c.prNumber}` : "#—";
+  const url = c.url ? `  ${c.url}` : "";
+  return `  PR ${pr}  ${c.changeId}  [${c.state ?? "?"}]${url}`;
+}
+
+/** @param {string[]} argv @param {any} ctx */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parsePrArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (!SUBCOMMANDS.includes(args.sub)) {
+    console.error(fail(`unknown subcommand: \`tot pr ${args.sub}\``, "tot pr list | view <N> | close <N>"));
+    return 2;
+  }
+  if (ctx.mode !== "checkout") {
+    console.error(
+      fail("`tot pr` runs from inside a tenant checkout", "tot clone <tenant> <dir>   (then `cd` in and re-run)"),
+    );
+    return 2;
+  }
+  if ((args.sub === "view" || args.sub === "close") && !args.target) {
+    console.error(fail(`\`tot pr ${args.sub}\` needs a PR number or changeId`, `tot pr ${args.sub} <N>`));
+    return 2;
+  }
+
+  const workspace = ctx.workspacePath;
+  const tenant = ctx.tenant;
+  const gitSafe = (cargs) => {
+    try {
+      return execFileSync("git", ["-C", workspace, ...cargs], { stdio: ["ignore", "pipe", "pipe"] }).toString();
+    } catch {
+      return "";
+    }
+  };
+  const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
+  if (!repo) {
+    console.error(
+      fail("couldn't derive the forge repo from this checkout's remote", "run this from a `tot clone`d store"),
+    );
+    return 1;
+  }
+
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const statePath = defaultCandidateStatePath(env);
+  const scope = { mcpUrl: baseUrl, repo };
+  const client = createMcpClient(baseUrl);
+  try {
+    const session = await establishSession(client, { env, prefer: args.identity || undefined });
+    void session;
+    // Bind the active tenant so candidate_status/close read the right scope.
+    await client.callTool("client_switch", { tenant });
+
+    const candidates = extractCandidates(await client.callTool("candidate_status", { repo }));
+
+    if (args.sub === "list") {
+      if (!candidates.length) {
+        console.log(`No open candidate PRs for ${repo}. Run \`tot submit\` to open one.`);
+        return 0;
+      }
+      const active = readActiveChangeId(statePath, scope);
+      console.log(`Open candidate PRs for ${repo}:`);
+      for (const c of candidates) {
+        console.log(line(c) + (active && c.changeId === active ? "  ← active" : ""));
+      }
+      return 0;
+    }
+
+    const match = matchCandidate(candidates, args.target);
+    if (!match) {
+      console.error(fail(`no open candidate matches "${args.target}"`, "tot pr list   (to see your open candidates)"));
+      return 1;
+    }
+
+    if (args.sub === "view") {
+      const active = readActiveChangeId(statePath, scope);
+      console.log(`PR ${typeof match.prNumber === "number" ? `#${match.prNumber}` : "#—"} — ${match.changeId}${match.changeId === active ? "  (active)" : ""}`);
+      console.log(`  state:            ${match.state ?? "?"}`);
+      if (match.branch) console.log(`  branch:           ${match.branch}`);
+      if (match.headSha) console.log(`  head:             ${match.headSha}`);
+      if (match.baseSha) console.log(`  base:             ${match.baseSha}`);
+      console.log(`  mergeable (forge): ${match.mergeable ?? "?"}`);
+      if (match.url) console.log(`  ${match.url}`);
+      return 0;
+    }
+
+    // close
+    await client.callTool("candidate_close", {
+      repo,
+      changeId: match.changeId,
+      ...(args.reason ? { reason: args.reason } : {}),
+    });
+    console.log(`✓ closed candidate ${match.changeId}${typeof match.prNumber === "number" ? ` (PR #${match.prNumber})` : ""}.`);
+    // If we just closed the remembered active candidate, forget it so the next
+    // plain `tot submit` starts a fresh one rather than resurrecting this handle.
+    if (readActiveChangeId(statePath, scope) === match.changeId) {
+      try {
+        clearActiveChangeId(statePath, scope);
+      } catch { /* best-effort */ }
+    }
+    return 0;
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      console.error(fail("sign in to manage candidate PRs", e.hint || "run `tot login`, then re-run"));
+      return 1;
+    }
+    console.error(
+      fail(
+        `couldn't reach the candidate service: ${String(e?.message || e)}`,
+        "check your connection and that you're signed in, then re-run",
+      ),
+    );
+    return 1;
+  }
+}

package/src/commands/preview.mjs

@@ -0,0 +1,71 @@
+/**
+ * `tot preview` — submit your store for PREVIEW (the deliberate, gated step).
+ *
+ * This is the first-class verb for the dev → preview → ship loop:
+ *
+ *   tot dev        run your store locally with save→reload
+ *   tot preview    push it to a reviewable preview (validate → reconcile → compliance)  ← you are here
+ *   tot ship       promote a reconciled preview live                                     ← unit u3
+ *
+ * The whole preview flow (validate, push the preview ref, open/update the PR-backed
+ * candidate, stream the reconcile/compliance/preview result) lives in submit.mjs — this
+ * module is a thin wrapper that runs that SAME flow and, on success, teaches the next
+ * verb (`tot ship`). Keeping the flow in one place means `tot preview` and its teaching
+ * aliases (`tot submit` / `tot deploy`, below) share exactly one implementation — every
+ * submit flag works identically through preview, with no chance of drift.
+ *
+ * TEACHING ALIASES: `tot submit` and `tot deploy` are the same preview flow. They run it
+ * unchanged and then print a one-line hint teaching the rename (and `tot ship`), so a
+ * developer who reaches for the old verb is nudged onto the new model without losing a
+ * step. Pass `{ alias }` (the verb the developer typed) to get that hint.
+ *
+ * Dependency-free (delegates to submit.mjs, which uses global fetch + `git`).
+ */
+import { run as runPreviewFlow, parseArgs, renderUsage } from "./submit.mjs";
+
+/** The ship hint printed after a successful `tot preview` — teaches the next verb.
+ *  Pure — unit-tested. */
+export const shipHint = () =>
+  "\n  → next: once this preview reconciles cleanly, `tot ship` promotes it live.";
+
+/** The teaching hint printed when the preview flow is reached via an old verb
+ *  (`tot submit` / `tot deploy`). Names the rename AND the ship verb in one line.
+ *  Pure — unit-tested. */
+export const aliasHint = (alias) =>
+  `\n  ℹ \`tot ${alias}\` is now \`tot preview\` — and \`tot ship\` promotes it live.`;
+
+/** The hint to print after the flow returns, or null when there's nothing to teach
+ *  (the flow failed). An alias gets the rename+ship hint; the first-class verb gets
+ *  the ship hint; a non-zero exit teaches nothing (the push didn't land). Pure. */
+export function postRunHint(code, alias) {
+  if (code !== 0) return null;
+  return alias ? aliasHint(alias) : shipHint();
+}
+
+/**
+ * @param {string[]} argv
+ * @param {any} ctx
+ * @param {{ alias?: string|null }} [opts] — `alias` is the old verb the developer typed
+ *   (`"submit"` / `"deploy"`) when this flow is reached as a teaching alias; null/omitted
+ *   for the first-class `tot preview`.
+ */
+export async function run(argv, ctx, { alias = null } = {}) {
+  const verb = alias || "preview";
+  const args = parseArgs(argv);
+
+  // Handle --help here so we can brand the usage with the typed verb and, for an
+  // alias, teach the rename — without also printing the post-success ship hint.
+  if (args.help) {
+    console.log(renderUsage(verb));
+    if (alias) console.log(aliasHint(alias));
+    return 0;
+  }
+
+  const code = await runPreviewFlow(argv, ctx, { verb });
+
+  // Teach the next step only on a successful preview (the push landed). An alias
+  // gets the rename+ship hint; the first-class verb just gets the ship hint.
+  const hint = postRunHint(code, alias);
+  if (hint) console.log(hint);
+  return code;
+}

package/src/commands/ship.mjs

@@ -0,0 +1,53 @@
+/**
+ * `tot ship` — promote a reconciled PREVIEW live (the ship gate).
+ *
+ * This is the second half of the dev → preview → ship loop:
+ *
+ *   tot dev        run your store locally with save→reload
+ *   tot preview    push it to a reviewable preview (validate → reconcile → compliance)
+ *   tot ship       promote a reconciled preview live                                     ← you are here
+ *
+ * STATUS: STUB — the command is registered and named so the loop reads end-to-end,
+ * but the real ship logic (resolve the current candidate/change for this checkout,
+ * show the diff about to go live, confirm, then `change_accept` / `candidate_accept`
+ * via the MCP, and report the shipped result) lands in a later unit.
+ *
+ * TODO(u3): implement the real ship flow. Symmetric with submit.mjs's preview flow —
+ * it should reuse the same candidate handle (deriveChangeId / the active-candidate
+ * state in candidate-state.mjs) so `tot ship` promotes the exact preview `tot preview`
+ * last pushed, gate on a clean reconcile, and diff-confirm before accepting.
+ *
+ * Until then this prints a clear "not yet wired" message pointing at the reviewer
+ * path that ships a change today, and exits non-zero so nothing mistakes it for a
+ * completed ship. Additive + non-breaking: it performs no action.
+ *
+ * Dependency-free.
+ */
+import { fail } from "../errors.mjs";
+
+const USAGE = `tot ship — promote a reconciled preview live
+
+  tot ship        (coming soon) promote the preview you last pushed with \`tot preview\`
+
+  Ship the preview live once it has reconciled cleanly. This is the deliberate
+  step AFTER \`tot preview\` — preview makes it reviewable; ship makes it live.`;
+
+/**
+ * @param {string[]} argv
+ * @param {any} _ctx
+ */
+export async function run(argv, _ctx) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  console.error(
+    fail(
+      "`tot ship` isn't wired up yet",
+      "push your work for review with `tot preview`; a reviewer accepts it to ship it live " +
+        "(change_accept / `tot pr`). Self-serve `tot ship` is coming soon.",
+    ),
+  );
+  return 2;
+}

package/src/commands/start.mjs

@@ -57,8 +57,9 @@ import { CliError, fail, formatError, exitCodeFor } from "../errors.mjs";
 import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
 import { defaultLastTenantPath, readLastTenant, writeLastTenant } from "../last-tenant.mjs";
+import { readCredentials, defaultCredentialsPath } from "../token-store.mjs";
 import { collectChecks } from "./doctor.mjs";
-import { normalizeStores, storeListError, checkoutTenant } from "./checkout.mjs";
+import { normalizeStores, storeListError, checkoutTenant, noStoresGuidance } from "./clone.mjs";
 import {
   buildContainerPlan, spawnDevContainer, dockerAvailable, tryStartDocker,
   resolveDevImage, isPrivateRegistryImage, ensureRegistryLogin,
@@ -161,6 +162,24 @@ export function decideStartMode({ sampleFlag, hasSession }) {
   return hasSession ? "authed" : "sample";
 }
 
+/**
+ * The MCP base URL the cached session was minted on — what `tot login` stored in the
+ * credentials file (honoring TOT_PROFILE via defaultCredentialsPath). Lets `tot start`
+ * (and callers) FOLLOW wherever the developer signed in rather than defaulting to prod,
+ * which would look up a session on the wrong MCP and report "not signed in". Returns
+ * null when there's no cached session or it can't be read (falls through to the default).
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string|null}
+ */
+export function cachedMcpUrl(env) {
+  try {
+    const creds = readCredentials(defaultCredentialsPath(env));
+    return creds && typeof creds.mcpUrl === "string" && creds.mcpUrl ? creds.mcpUrl : null;
+  } catch {
+    return null;
+  }
+}
+
 /** @param {string[]} argv @param {any} ctx */
 export async function run(argv, ctx) {
   const env = process.env;
@@ -178,7 +197,11 @@ export async function run(argv, ctx) {
   }
 
   try {
-    const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+    // Resolve the MCP: an explicit flag / env wins, then the MCP the cached session was
+    // minted on (what `tot login` stored — so `start` FOLLOWS wherever you signed in
+    // instead of defaulting to prod and reporting "not signed in"), then the prod default.
+    const baseUrl =
+      args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || cachedMcpUrl(env) || DEFAULT_MCP_URL;
     const client = createMcpClient(baseUrl);
 
     // Resolve a session, tolerating a no-session / no-network condition so we can
@@ -223,6 +246,7 @@ export async function run(argv, ctx) {
       tenant = await resolveTenant(stores, args, env, baseUrl, {
         session,
         listErr: storeListError(listResp),
+        list: listResp,
       });
     } catch (e) {
       stopEarlyHeartbeat();
@@ -537,7 +561,7 @@ function mcpOrigin(baseUrl) {
  * (surface the reason — likely an auth/entitlement problem) from a genuinely empty
  * result (invite may still be propagating, or you need one). Points at `tot whoami`.
  */
-function noStoresError({ session, baseUrl, listErr }) {
+function noStoresError({ session, baseUrl, listErr, list = null }) {
   const who = describeIdentity(session);
   const origin = mcpOrigin(baseUrl);
   if (listErr) {
@@ -546,14 +570,10 @@ function noStoresError({ session, baseUrl, listErr }) {
       { next: "run `tot whoami` to check your session, or `tot login` again — then re-run `tot start`" },
     );
   }
-  return new CliError(
-    `signed in as ${who} via ${origin}, but you have no stores to build on yet`,
-    {
-      next:
-        "if you were just invited, it may still be propagating — try again in a minute; " +
-        "otherwise ask your Token of Trust contact for a store invite (see `tot whoami`)",
-    },
-  );
+  // Status-aware (card c2): an UNLINKED identity is pointed at `tot link`, not the
+  // misleading "ask for a store invite" copy; the genuine zero-grants case keeps it.
+  const g = noStoresGuidance(list);
+  return new CliError(`signed in as ${who} via ${origin}, but ${g.headline}`, { next: g.next });
 }
 
 /**
@@ -561,7 +581,7 @@ function noStoresError({ session, baseUrl, listErr }) {
  * the remembered last tenant (A4) — then remember whatever was decided so the
  * next bare `tot start` doesn't have to ask again.
  */
-async function resolveTenant(stores, args, env, baseUrl, { session = null, listErr = null } = {}) {
+async function resolveTenant(stores, args, env, baseUrl, { session = null, listErr = null, list = null } = {}) {
   const lastTenantPath = defaultLastTenantPath(env);
   const pick = pickTenant(stores, {
     explicit: args.tenant || null,
@@ -570,7 +590,7 @@ async function resolveTenant(stores, args, env, baseUrl, { session = null, listE
 
   let tenant;
   if (pick.kind === "none") {
-    throw noStoresError({ session, baseUrl, listErr });
+    throw noStoresError({ session, baseUrl, listErr, list });
   } else if (pick.kind === "explicit") {
     tenant = pick.tenant;
     console.log(`  → your store: ${tenant} (--tenant)`);
@@ -613,7 +633,7 @@ async function ensureCheckout(client, tenant, dir, env) {
       console.log(`  ✓ reusing existing checkout ./${tenant}`);
       return;
     }
-    throw new CliError(`./${tenant} already exists and isn't a tot checkout`, {
+    throw new CliError(`./${tenant} already exists and isn't a store checkout`, {
       next: `remove it (or run \`tot start\` from an empty directory)`,
       exitCode: 2,
     });