@tokenoftrust/cli 1.3.4 → 1.4.0-rc.1

package/src/commands/submit.mjs

@@ -4,13 +4,21 @@
  * From inside a tenant checkout:
  *   1. validate locally and refuse on errors (fail fast before anything leaves the machine),
  *   2. push your committed work to the tenant repo's `preview` ref (triggers reconcile),
+ *   2b. open/update a PR-BACKED CANDIDATE for the same committed diff (g1b's
+ *       `candidate_open`, unit c1 — the local-dev-loop half of the "PR-Backed Hosted
+ *       Review Loop" milestone, symmetric with the hosted s6 draft-as-PR path), and
+ *       print the resulting changeId/PR number/URL,
  *   3. report back — reconcile result + compliance verdict + the preview URL — from the MCP.
  *
- * This is submit-for-PREVIEW, not ship-to-live (`change_accept` / a future `tot ship`
- * is the separate ship gate). Step 3 calls the MCP `preview_status` read-back:
- * given the commit just pushed it returns { status, reconcile, compliance, previewUrl } and we poll it
- * while reconcile is pending. If that tool isn't present (older MCP) the command still
- * validates + pushes and reports "reconcile pending" — degrading visibly, never a crash.
+ * This is submit-for-PREVIEW, not ship-to-live (`change_accept`/`candidate_accept` /
+ * a future `tot ship` is the separate ship gate — this command is submit-only, never
+ * accept/reject). Step 2b is best-effort: `candidate_open` failing (older MCP,
+ * version-control not configured, preview-access capability) is reported and
+ * swallowed — it never blocks the preview push that already landed. Step 3 calls
+ * the MCP `preview_status` read-back: given the commit just pushed it returns
+ * { status, reconcile, compliance, previewUrl } and we poll it while reconcile is
+ * pending. If that tool isn't present (older MCP) the command still validates +
+ * pushes and reports "reconcile pending" — degrading visibly, never a crash.
  *
  * Polling (E2): every call carries `waitMs` so a preview_status-aware MCP long-polls
  * (blocks up to waitMs, waking immediately on arrival) instead of us sleeping blind
@@ -30,6 +38,7 @@
  * Dependency-free (global fetch + `git`).
  */
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
@@ -104,9 +113,9 @@ export function buildChangeSummary({ message, summary, headSubject = "", statLin
   return { title, body, autoTitle: !(message && message.trim()) };
 }
 
-/** Print the change summary block. Push-only: this is what a human relays to the
- *  approver, or the agent carries into change_open — the CLI does not open the
- *  change record itself. */
+/** Print the change summary block — the SAME title/body carried into `candidate_open`
+ *  (below) as the PR title/description, so what the approver reads in the PR matches
+ *  what's printed here. */
 function printChangeSummary({ title, body, autoTitle }) {
   console.log(`\n  Change summary (for the approver / the change record):`);
   console.log(`    ${title}`);
@@ -114,6 +123,160 @@ function printChangeSummary({ title, body, autoTitle }) {
   if (autoTitle) console.log(`  (auto-generated from git — pass -m "…" / --summary "…" to refine)`);
 }
 
+// ─── PR-backed candidate (g1b candidate_open, unit c1) ──────────────────────────
+
+/**
+ * Parse `git diff/show --name-status` output into `{ status, path, from? }`
+ * entries — `status` is the single letter (A/M/D/R/C…); a rename/copy line
+ * (`R100\t<old>\t<new>`) carries both `from` (the old path) and `path` (the new
+ * one). Pure — unit-tested without git.
+ * @param {string} text
+ * @returns {{status:string, path:string, from?:string}[]}
+ */
+export function parseNameStatus(text) {
+  return text
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const parts = line.split("\t");
+      const status = parts[0]?.[0] || "";
+      if ((status === "R" || status === "C") && parts.length >= 3) {
+        return { status, from: parts[1], path: parts[2] };
+      }
+      return { status, path: parts[1] };
+    })
+    .filter((e) => e.path);
+}
+
+/**
+ * Build the g1b `candidate_open` FileChange[] patch from parsed name-status
+ * entries — one entry per changed path, `delete:true` for removals (and a
+ * rename's old path). Content is read from the committed HEAD blob via
+ * `readBlob` (injected — never the working tree, so the patch matches exactly
+ * what was pushed). Binary content (doesn't round-trip as clean utf8, or
+ * contains a NUL) is sent base64; everything else goes as plain utf8 text.
+ * @param {{status:string, path:string, from?:string}[]} entries
+ * @param {(path: string) => Buffer} readBlob
+ * @returns {Array<{path: string, content?: string, contentEncoding?: "base64", delete?: true}>}
+ */
+export function buildFilePatch(entries, readBlob) {
+  const patch = [];
+  for (const e of entries) {
+    if (e.status === "R") patch.push({ path: e.from, delete: true });
+    if (e.status === "D") {
+      patch.push({ path: e.path, delete: true });
+      continue;
+    }
+    const buf = readBlob(e.path);
+    const asUtf8 = buf.toString("utf8");
+    const isCleanUtf8 = !asUtf8.includes("") && Buffer.from(asUtf8, "utf8").equals(buf);
+    patch.push(
+      isCleanUtf8
+        ? { path: e.path, content: asUtf8 }
+        : { path: e.path, content: buf.toString("base64"), contentEncoding: "base64" },
+    );
+  }
+  return patch;
+}
+
+/**
+ * Derive the g1b forge repo name (`"<tenant>-<tag>"`, e.g. `"acme.com-main"`)
+ * from the checkout's authenticated origin remote — the SAME name
+ * `tenant_checkout` minted it as, so no separate lookup or stored tag is
+ * needed. Returns null when the remote URL can't be parsed (candidate_open is
+ * then skipped, reported, never crashed). Pure — unit-tested.
+ * @param {string} remoteUrl
+ * @returns {string|null}
+ */
+export function repoNameFromRemote(remoteUrl) {
+  try {
+    const last = new URL(remoteUrl).pathname.split("/").filter(Boolean).pop();
+    return last ? last.replace(/\.git$/, "") : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A STABLE per-developer-per-tenant candidate handle — so repeat `tot submit`
+ * runs update the SAME PR instead of opening a new one each time
+ * (`candidate_open` is idempotent on `changeId`). No local state file needed:
+ * it's a deterministic hash of the tenant + the acting identity, recomputed
+ * fresh every run. Two different developers submitting to the same tenant get
+ * two different (non-colliding) candidates. Pure — unit-tested.
+ * @param {string} tenant
+ * @param {string} actorKey
+ * @returns {string}
+ */
+export function deriveChangeId(tenant, actorKey) {
+  const hash = createHash("sha256").update(`${tenant}|${actorKey}`).digest("hex").slice(0, 16);
+  return `local-${hash}`;
+}
+
+/** The stable identity key behind `deriveChangeId` — the signed-in developer's
+ *  email, falling back to the token, then a generic label. Single-plane: the only
+ *  identity `tot` carries is the developer's own OAuth session. */
+export function actorKeyFor(session) {
+  return session?.email || session?.token || "developer";
+}
+
+/**
+ * Open/update the PR-backed candidate for this submit (g1b `candidate_open`,
+ * unit c1 — the local-dev-loop half of the "PR-Backed Hosted Review Loop"
+ * milestone, symmetric with the hosted s6 draft-as-PR path). Builds the patch
+ * from the SAME name-status diff `buildChangeSummary` reports on, reuses its
+ * title/body as the PR title/description, and prints the resulting
+ * changeId/PR number/URL. Best-effort: any failure (no repo could be derived,
+ * older MCP, version control not configured, preview-access capability, …) is
+ * reported and swallowed — it never blocks the preview push that already
+ * landed or the reconcile/compliance read-back that follows.
+ * @param {ReturnType<import("../mcp.mjs").createMcpClient>} client
+ * @param {{ repo: string|null, changeId: string, changeSummary: {title:string, body:string[]},
+ *   patchEntries: {status:string, path:string, from?:string}[], readBlob: (path:string)=>Buffer }} opts
+ */
+export async function submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob }) {
+  if (!repo) {
+    console.log(`  ~ couldn't derive the forge repo from the checkout's remote — skipping the PR-backed candidate.`);
+    return null;
+  }
+  try {
+    const patch = buildFilePatch(patchEntries, readBlob);
+    if (patch.length === 0) {
+      console.log(`  ~ no file changes to open a PR-backed candidate for.`);
+      return null;
+    }
+    const result = await client.callTool("candidate_open", {
+      repo,
+      changeId,
+      // Defensively bounded to candidate_open's own schema limits (title<=200,
+      // body<=4000) so an over-long commit subject / summary degrades to a
+      // truncated PR title/body instead of an entirely-avoidable tool refusal.
+      title: changeSummary.title.slice(0, 200),
+      body: changeSummary.body.length ? changeSummary.body.join("\n").slice(0, 4000) : undefined,
+      patch,
+    });
+    reportCandidate(result, changeId);
+    return result;
+  } catch (e) {
+    console.log(`  ~ couldn't open/update the PR-backed candidate: ${String(e?.message || e)}`);
+    console.log(`    (best-effort — your push is still in; this doesn't block reconcile.)`);
+    return null;
+  }
+}
+
+/** Print the candidate_open result: the PR the approver reviews, or the MCP's own
+ *  refusal message when it couldn't open/update one. */
+function reportCandidate(result, changeId) {
+  if (result && typeof result.prNumber === "number") {
+    console.log(`\n  ✓ candidate ${result.changeId || changeId} — PR #${result.prNumber} (${result.state || "open"})`);
+    if (result.url) console.log(`    ${result.url}`);
+    return;
+  }
+  const msg = result?.message || (result?.raw && String(result.raw)) || JSON.stringify(result ?? null);
+  console.log(`  ~ PR-backed candidate not opened: ${msg}`);
+}
+
 /** @param {string[]} argv @param {any} ctx */
 export async function run(argv, ctx) {
   const env = process.env;
@@ -162,9 +325,10 @@ export async function run(argv, ctx) {
   // Build the "what changed" summary the approver is greeted with — BEFORE the
   // push, because `git push` fast-forwards the local origin/<ref> tracking ref and
   // would zero out the "vs what's live in preview" diff. Explicit -m/--summary win;
-  // otherwise it's generated from git so the change record is never blank. Push-only:
-  // we surface it (the agent carries it into change_open) — the CLI never opens the
-  // change record itself.
+  // otherwise it's generated from git so the change record is never blank. This
+  // same diff (name-status, so candidate_open also knows adds/deletes/renames)
+  // doubles as the source of the PR-backed candidate's file patch (step 2b, below)
+  // — one git read, two consumers, so the PR always matches what's printed here.
   const gitSafe = (cargs) => {
     try {
       return git(cargs);
@@ -179,8 +343,9 @@ export async function run(argv, ctx) {
     : gitSafe(["rev-parse", "--verify", "--quiet", "HEAD~1"]).trim()
       ? "HEAD~1"
       : "";
-  const nameCmd = base ? ["diff", "--name-only", `${base}..HEAD`] : ["show", "--name-only", "--format=", "HEAD"];
-  const files = gitSafe(nameCmd).split("\n").map((s) => s.trim()).filter(Boolean);
+  const statusCmd = base ? ["diff", "--name-status", `${base}..HEAD`] : ["show", "--name-status", "--format=", "HEAD"];
+  const patchEntries = parseNameStatus(gitSafe(statusCmd));
+  const files = patchEntries.map((e) => e.path);
   const statLine = base ? gitSafe(["diff", "--shortstat", `${base}..HEAD`]).trim() : "";
   const changeSummary = buildChangeSummary({ message: args.message, summary: args.summary, headSubject, statLine, files });
 
@@ -200,17 +365,30 @@ export async function run(argv, ctx) {
   console.log(`\n+ submitted ${short} to ${args.ref}.`);
   printChangeSummary(changeSummary);
 
-  // 3. report reconcile + compliance + preview URL from the MCP (graceful seam).
+  // 2b + 3. open/update the PR-backed candidate, then report reconcile +
+  // compliance + preview URL from the MCP (both graceful seams, same session).
   const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
   const client = createMcpClient(baseUrl);
   let progress = null;
   try {
     // Attach auth before the first server call (developer bearer pre-initialize,
     // operator credential_validate post-initialize) — see establishSession.
-    await establishSession(client, { env, prefer: args.identity || undefined });
-    // Set the active tenant so preview_status reads the right scope (it keys on
-    // the session's tenant + the commit — no tenant arg of its own).
+    const session = await establishSession(client, { env, prefer: args.identity || undefined });
+    // Set the active tenant so preview_status/candidate_open read the right scope
+    // (both key on the session's bound tenant/app — no tenant arg of their own).
     await client.callTool("client_switch", { tenant });
+
+    // 2b. PR-backed candidate (g1b candidate_open, unit c1) — best-effort: a
+    // failure here (older MCP, VC not configured, preview-access capability) is
+    // reported and swallowed, never blocking the preview push that already landed.
+    await submitCandidate(client, {
+      repo: repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim()),
+      changeId: deriveChangeId(tenant, actorKeyFor(session)),
+      changeSummary,
+      patchEntries,
+      readBlob: (path) => execFileSync("git", ["-C", workspace, "show", `HEAD:${path}`], { stdio: ["ignore", "pipe", "pipe"] }),
+    });
+
     let status;
     if (args.noWait) {
       status = normalizePreviewStatus(await client.callTool("preview_status", { commit }));

package/src/commands/whoami.mjs

@@ -2,15 +2,14 @@
  * `tot whoami` — who is `tot` signed in as, and what can they touch.
  *
  * Reads the cached session (~/.tot/credentials.json). If a live token is present
- * it best-effort asks the MCP for the stores this identity may act on (proving the
+ * it best-effort asks the MCP for the stores this developer may act on (proving the
  * token still works), degrading cleanly to the cached status if the MCP is
- * unreachable or the identity isn't entitled yet. Operator credentials in the env
- * are reported too, since they take precedence for tool calls.
+ * unreachable or the developer isn't entitled yet.
  *
  * Dependency-free.
  */
-import { defaultCredentialsPath, readCredentials, isExpired } from "../token-store.mjs";
-import { hasOperatorCreds, establishSession } from "../auth.mjs";
+import { defaultCredentialsPath, readCredentials, isExpired, activeProfile } from "../token-store.mjs";
+import { establishSession } from "../auth.mjs";
 import { createMcpClient } from "../mcp.mjs";
 import { normalizeStores, storeListError } from "./checkout.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
@@ -35,15 +34,13 @@ export async function run(argv, _ctx) {
   const creds = readCredentials(defaultCredentialsPath(env));
   const status = sessionStatus(creds);
 
-  if (hasOperatorCreds(env)) {
-    console.log(`operator credentials set in this shell (TOT_APP_DOMAIN=${env.TOT_APP_DOMAIN}).`);
-    console.log("  these take precedence for `tot` tool calls.");
-  }
+  const profile = activeProfile(env);
+  if (profile) console.log(`profile: ${profile}  (TOT_PROFILE — this terminal's own identity)`);
 
   if (!status.signedIn) {
     console.log("developer: not signed in.");
-    if (!hasOperatorCreds(env)) console.log("  → next: tot login");
-    return hasOperatorCreds(env) ? 0 : 1;
+    console.log("  → next: tot login");
+    return 1;
   }
 
   const when = status.expiresAt ? new Date(status.expiresAt).toISOString() : "unknown";
@@ -58,7 +55,7 @@ export async function run(argv, _ctx) {
     // Developer bearer must be attached BEFORE initialize so the server binds this
     // identity at handshake time — otherwise client_list resolves anonymously and
     // (misleadingly) reports no stores (establishSession orders this correctly).
-    await establishSession(client, { env, prefer: "developer" });
+    await establishSession(client, { env });
     const listResp = await client.callTool("client_list", {});
     // Update-awareness Layer 2: an authed response may carry a version-support
     // policy (wire contract: `cliPolicy`). Safe no-op when absent.

package/src/mcp.mjs

@@ -93,8 +93,8 @@ export function createMcpClient(baseUrl, opts = {}) {
   let rpcId = 0;
   let sessionId = null;
   // The developer OAuth bearer (set at login-resolve time via setToken, or up
-  // front via opts.token). Absent for the operator path, which authenticates by
-  // credential_validate + the Mcp-Session-Id below.
+  // front via opts.token) — the only identity `tot` carries. Anonymous calls
+  // (e.g. the pre-login handshake) simply omit it.
   let bearer = typeof opts.token === "string" ? opts.token : null;
 
   /** Attach (or clear) the developer bearer for subsequent calls. */

package/src/prompt.mjs

@@ -0,0 +1,32 @@
+/**
+ * Tiny terminal-prompt helpers, shared across commands. Every prompt respects a
+ * non-TTY (CI, piped stdin) by returning the default instead of hanging — the one
+ * rule that keeps `tot` safe to run non-interactively.
+ *
+ * Dependency-free (node:readline/promises).
+ */
+import { createInterface } from "node:readline/promises";
+
+/** True only when BOTH stdin and stdout are a TTY — safe to prompt. */
+export function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+/**
+ * Ask a yes/no question. Returns `defaultYes` immediately on a non-TTY so nothing
+ * ever blocks in CI. Enter (empty answer) takes the default.
+ * @param {string} question
+ * @param {boolean} defaultYes
+ * @returns {Promise<boolean>}
+ */
+export async function promptYesNo(question, defaultYes) {
+  if (!isInteractive()) return defaultYes;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const ans = (await rl.question(`${question} ${defaultYes ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
+    if (!ans) return defaultYes;
+    return ans === "y" || ans === "yes";
+  } finally {
+    rl.close();
+  }
+}

package/src/token-store.mjs

@@ -29,17 +29,60 @@
  * Dependency-free (node:fs/os/path).
  *
  * `TOT_HOME` overrides the home dir (used by tests to point at a temp dir).
+ *
+ * PROFILES (`TOT_PROFILE`) — OPTIONAL, for parallel work. Almost every developer
+ * leaves this UNSET and uses the single default `credentials.json` — that path is
+ * unchanged and is the norm. It exists only when you want MORE THAN ONE identity
+ * live at once (a staff `@tokenoftrust.com` sign-in and a plain developer one, or
+ * many parallel test identities): export a profile per shell and each gets its OWN
+ * credential file under the same `~/.tot` (the renderer cache, last-tenant, etc.
+ * stay shared — only the identity splits). The value is an OPAQUE label — any
+ * string works, so `export TOT_PROFILE=$(uuidgen)` per terminal/test is fine:
+ *   - a clean short token (`staff`, `dev`, `test-7`) is used verbatim for a
+ *     readable `credentials.<profile>.json`;
+ *   - any other value (symbols, uppercase, long) is HASHED to a stable, safe
+ *     `credentials.h<hash>.json` — so an arbitrary opaque id can never collide
+ *     with another or escape `~/.tot`, while `tot whoami` still shows what you set.
  */
 import {
   readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, existsSync, rmSync,
 } from "node:fs";
 import { homedir } from "node:os";
+import { createHash } from "node:crypto";
 import { join, dirname } from "node:path";
 
-/** Absolute path to the credential file for this environment. */
+/** A short token safe to drop straight into a filename (readable profiles). */
+const CLEAN_PROFILE_RE = /^[a-z0-9_-]{1,64}$/;
+
+/**
+ * The active profile's DISPLAY label — the raw `TOT_PROFILE`, trimmed — or null
+ * when unset. This is what `tot whoami` shows; it is NOT the filename (see
+ * profileSlug, which makes any value filesystem-safe).
+ */
+export function activeProfile(env = process.env) {
+  return String(env.TOT_PROFILE || "").trim() || null;
+}
+
+/**
+ * The active profile's safe filename token, or null for the default session. A
+ * clean short label passes through verbatim (readable files); ANY other opaque
+ * value is hashed — collision-resistant and incapable of a `/` or `..` path
+ * escape, so `TOT_PROFILE` can be a literally arbitrary identifier. Hashing the
+ * RAW value (not a stripped form) keeps distinct tokens distinct.
+ */
+export function profileSlug(env = process.env) {
+  const raw = String(env.TOT_PROFILE || "").trim();
+  if (!raw) return null;
+  const lower = raw.toLowerCase();
+  if (CLEAN_PROFILE_RE.test(lower)) return lower;
+  return `h${createHash("sha256").update(raw).digest("hex").slice(0, 16)}`;
+}
+
+/** Absolute path to the credential file for this environment (+ TOT_PROFILE). */
 export function defaultCredentialsPath(env = process.env) {
   const home = env.TOT_HOME || homedir();
-  return join(home, ".tot", "credentials.json");
+  const slug = profileSlug(env);
+  return join(home, ".tot", slug ? `credentials.${slug}.json` : "credentials.json");
 }
 
 /**

package/src/validate.mjs

@@ -184,7 +184,12 @@ function validateScriptsDoc(doc, file, config) {
   return out;
 }
 
-const SUPPORTED_BLOCK_CONTRACTS = new Set(["block-palette@1", "block-palette@2", "block-palette@3"]);
+const SUPPORTED_BLOCK_CONTRACTS = new Set([
+  "block-palette@1",
+  "block-palette@2",
+  "block-palette@3",
+  "block-palette@4",
+]);
 const KNOWN_BLOCKS = new Set([
   "hero",
   "promo_tiles",
@@ -192,6 +197,7 @@ const KNOWN_BLOCKS = new Set([
   "featured_products",
   "editorial",
   "newsletter",
+  "membership_band",
   "marketing_hero",
   "trust_bar",
   "split_compare",
@@ -209,6 +215,7 @@ const REQUIRED_BLOCK_PROPS = {
   featured_collections: ["handles"],
   editorial: ["title"],
   newsletter: ["title"],
+  membership_band: ["tiers"],
   marketing_hero: ["headline"],
   trust_bar: ["items"],
   split_compare: ["title", "before", "after"],