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

package/src/commands/submit.mjs

@@ -42,6 +42,7 @@ import { createHash } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
+import { checkoutTenant } from "./clone.mjs";
 import { validateTenant, ERROR } from "../validate.mjs";
 import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
@@ -52,6 +53,7 @@ import {
   writeActiveChangeId,
   mintFreshChangeId,
   isTerminalCandidateState,
+  isDefaultBranch,
 } from "../candidate-state.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -345,22 +347,165 @@ export function repoNameFromRemote(remoteUrl) {
   }
 }
 
+// ─── fresh-forge-credential push (decision B — the invited-dev 401 dead-end) ─────
+
+/**
+ * Split an authenticated forge remote URL (basic-auth `user:token@host`, as the
+ * MCP mints it via `tenant_checkout`) into its tokenless public URL + the embedded
+ * credential, so the token can be handed to git EPHEMERALLY for one push instead of
+ * being persisted in `.git/config`. Returns null when the URL won't parse or carries
+ * no token — the caller then falls back to the checkout's existing remote. Pure —
+ * unit-tested.
+ * @param {string} remoteUrl
+ * @returns {{ publicUrl: string, username: string, token: string }|null}
+ */
+export function splitAuthedRemote(remoteUrl) {
+  try {
+    const u = new URL(String(remoteUrl));
+    const token = u.password ? decodeURIComponent(u.password) : "";
+    if (!token) return null;
+    const username = u.username ? decodeURIComponent(u.username) : "";
+    return { publicUrl: `${u.protocol}//${u.host}${u.pathname}`, username, token };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The `http.extraheader` value that hands a basic-auth credential to a SINGLE git
+ * invocation (base64 of `user:token`) — so a freshly-minted forge token
+ * authenticates one push without ever being written to `.git/config`. Pure —
+ * unit-tested.
+ * @param {string} username
+ * @param {string} token
+ * @returns {string}
+ */
+export function basicAuthExtraHeader(username, token) {
+  const b64 = Buffer.from(`${username}:${token}`, "utf8").toString("base64");
+  return `Authorization: Basic ${b64}`;
+}
+
+/**
+ * Recognise a forge auth failure (expired / invalid push token) in a failed git
+ * push's stderr, so `tot preview` can re-mint a fresh credential and retry once
+ * rather than dead-ending on a stale token (the belt-and-suspenders half of
+ * decision B). Pure — unit-tested.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isForgeAuthError(text) {
+  return /\b40[13]\b|failed to authenticate|authentication failed|invalid credentials|access denied/i.test(
+    String(text || ""),
+  );
+}
+
 /**
- * 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
+ * Derive the checkout's forge tag from its repo name (`"<tenant>-<tag>"`), so a
+ * re-mint targets the SAME repo the checkout points at. Defaults to "main" when the
+ * repo is bare (`"<tenant>"`, post-8425) or the `<tenant>-` prefix doesn't match, so
+ * the mint degrades to the clone default rather than a wrong tag. Pure —
+ * unit-tested.
+ * @param {string|null} repoName
+ * @param {string} tenant
+ * @returns {string}
+ */
+export function tagFromRepoName(repoName, tenant) {
+  const r = String(repoName || "");
+  const prefix = `${tenant}-`;
+  return r.startsWith(prefix) && r.length > prefix.length ? r.slice(prefix.length) : "main";
+}
+
+/**
+ * Push the preview ref (decision B): mint a FRESH, short-lived forge credential
+ * right before the push and hand it to git EPHEMERALLY (via `http.extraheader` on
+ * a per-invocation `-c` — never written to `.git/config`), re-minting once on an
+ * auth failure. The push credential the MCP baked into `.git/config` at clone time
+ * expires within hours; reusing that stale embedded token is the invited-dev
+ * "`tot preview` → Gitea 401 dead-end". We push over the named `origin` remote with
+ * its URL overridden to the tokenless public URL for this one invocation, so the
+ * remote-tracking ref still updates while no long-lived secret lands on disk.
+ *
+ * When the mint is unavailable (older MCP, transient failure — `mintRemote` returns
+ * null) or the minted URL carries no parseable token, it falls back to pushing over
+ * the checkout's EXISTING remote (pre-B behavior) — no regression.
+ *
+ * @param {(cargs:string[])=>string} git  throwing git runner (execFileSync-backed)
+ * @param {() => Promise<string|null>} mintRemote  mints a fresh authed gitRemote (null when unavailable)
+ * @param {{ ref: string }} opts
+ * @returns {Promise<{ out: string }>}  resolves on a successful push; throws (git's error) otherwise
+ */
+export async function pushPreviewRef(git, mintRemote, { ref } = {}) {
+  const attempt = (remote) => {
+    const cred = splitAuthedRemote(remote);
+    if (!cred) {
+      // No fresh credential to hand over — push over the checkout's existing remote.
+      return git(["push", "-f", "origin", `HEAD:refs/heads/${ref}`]);
+    }
+    // Ephemeral auth: override the remote URL to the tokenless public URL and supply
+    // the credential as a one-shot Authorization header, with any OS credential
+    // helper disabled — none of this touches `.git/config`.
+    return git([
+      "-c", `remote.origin.url=${cred.publicUrl}`,
+      "-c", `http.extraheader=${basicAuthExtraHeader(cred.username, cred.token)}`,
+      "-c", "credential.helper=",
+      "push", "-f", "origin", `HEAD:refs/heads/${ref}`,
+    ]);
+  };
+
+  const remote = await mintRemote();
+  try {
+    return { out: attempt(remote) };
+  } catch (e) {
+    if (!isForgeAuthError(e?.stderr || e?.message || e)) throw e;
+    // Belt-and-suspenders: an auth failure re-mints a fresh credential and retries once.
+    return { out: attempt(await mintRemote()) };
+  }
+}
+
+/**
+ * A STABLE per-developer-per-tenant(-per-branch) 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.
+ * it's a deterministic hash of the tenant + the acting identity (+ the git branch
+ * on a non-default branch), recomputed fresh every run. Two different developers
+ * submitting to the same tenant get two different (non-colliding) candidates; so
+ * do the SAME developer on two different feature branches (u4 — branch-bound
+ * candidates), so `git checkout` acts as the PR switcher.
+ *
+ * ZERO MIGRATION: on the DEFAULT branch (main/master, or an unresolvable branch)
+ * the hash material is `tenant|actorKey` — byte-identical to the pre-u4 id — so an
+ * existing dev's current candidate keeps working untouched. A non-default branch
+ * folds the branch into the material (`tenant|actorKey|branch`) for its own id.
+ * Pure — unit-tested.
  * @param {string} tenant
  * @param {string} actorKey
+ * @param {string|null} [branch]  current git branch; default/null ⇒ today's id
  * @returns {string}
  */
-export function deriveChangeId(tenant, actorKey) {
-  const hash = createHash("sha256").update(`${tenant}|${actorKey}`).digest("hex").slice(0, 16);
+export function deriveChangeId(tenant, actorKey, branch = null) {
+  const material = isDefaultBranch(branch) ? `${tenant}|${actorKey}` : `${tenant}|${actorKey}|${branch}`;
+  const hash = createHash("sha256").update(material).digest("hex").slice(0, 16);
   return `local-${hash}`;
 }
 
+/**
+ * The current git branch in `workspace`, or null when it can't be resolved (a
+ * detached HEAD reports "HEAD", and any git failure is swallowed) — null is read
+ * by `isDefaultBranch` as the default branch, so an unresolvable branch keeps
+ * today's (branch-less) candidate rather than minting a spurious namespace. `git`
+ * is injected (a `(args:string[])=>string` runner) so it's testable. Best-effort.
+ * @param {(args:string[]) => string} git
+ * @returns {string|null}
+ */
+export function currentBranch(git) {
+  try {
+    const b = git(["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    return b && b !== "HEAD" ? b : null;
+  } catch {
+    return null;
+  }
+}
+
 /** 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. */
@@ -538,10 +683,68 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   const statLine = base ? gitSafe(["diff", "--shortstat", `${base}..HEAD`]).trim() : "";
   const changeSummary = buildChangeSummary({ message: args.message, summary: args.summary, headSubject, statLine, files });
 
-  console.error(`~ pushing ${short} → ${args.ref} (origin)`);
+  // The MCP session is needed BOTH to mint a fresh forge push credential (decision
+  // B — right below) and for the candidate/preview read-back after, so establish it
+  // ONCE, up front, and reuse it for the whole flow.
+  const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  const client = createMcpClient(baseUrl);
+  const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
+
+  let session;
+  try {
+    session = await establishSession(client, { env, prefer: args.identity || undefined });
+  } catch (e) {
+    // Not signed in / MCP unreachable — we can't mint a fresh credential, so fall
+    // back to pushing over the checkout's EXISTING embedded remote (pre-B behavior:
+    // no worse than before) and skip the read-back that needs a session. The push
+    // still lands if that embedded token is live.
+    console.error(`~ pushing ${short} → ${args.ref} (origin)`);
+    try {
+      const out = git(["push", "-f", "origin", `HEAD:refs/heads/${args.ref}`]);
+      if (out.trim()) console.error(redactUrl(out.trim()));
+    } catch (pushErr) {
+      console.error(
+        fail(
+          `push failed: ${redactUrl(String(pushErr.stderr || pushErr.message || pushErr))}`,
+          "check your commit and that the checkout's remote is reachable, then re-run",
+        ),
+      );
+      return 1;
+    }
+    console.log(`\n+ submitted ${short} to ${args.ref}.`);
+    printChangeSummary(changeSummary);
+    if (e instanceof AuthUnavailableError) {
+      console.log(`  (sign in to see the reconcile/compliance/preview result — ${e.hint || "developer sign-in pending"})`);
+    } else {
+      console.log(`  (couldn't reach Token of Trust for the result read-back: ${String(e?.message || e)})`);
+    }
+    console.log(`  Your push is in; the preview updates once reconcile completes.`);
+    return 0;
+  }
+
+  // 2. push the preview ref with a FRESHLY-MINTED, short-lived forge credential
+  //    (decision B). The token baked into `.git/config` at clone time expires within
+  //    hours, so we re-mint right before the push and hand it to git ephemerally
+  //    (never persisted to `.git/config`), re-minting once on an auth failure.
+  //    `checkoutTenant(cloneDir:null)` mints without re-cloning AND client_switch()es,
+  //    binding the tenant scope the candidate/preview read-back below reads.
+  const tag = tagFromRepoName(repo, tenant);
+  const mintRemote = async () => {
+    try {
+      const res = await checkoutTenant(client, { tenant, tag, cloneDir: null, redact: redactUrl });
+      return res.gitRemote || null;
+    } catch (e) {
+      console.error(
+        `~ couldn't mint a fresh push credential (${redactUrl(String(e?.message || e))}) — using the checkout's remote`,
+      );
+      return null;
+    }
+  };
+
+  console.error(`~ pushing ${short} → ${args.ref} (origin, fresh credential)`);
   try {
-    const out = git(["push", "-f", "origin", `HEAD:refs/heads/${args.ref}`]);
-    if (out.trim()) console.error(redactUrl(out.trim()));
+    const { out } = await pushPreviewRef(git, mintRemote, { ref: args.ref });
+    if (out && out.trim()) console.error(redactUrl(out.trim()));
   } catch (e) {
     console.error(
       fail(
@@ -555,16 +758,11 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   printChangeSummary(changeSummary);
 
   // 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);
+  // compliance + preview URL from the MCP — reusing the session established above.
   let progress = null;
   try {
-    // Attach auth before the first server call (developer bearer pre-initialize,
-    // operator credential_validate post-initialize) — see establishSession.
-    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).
+    // Bind the active tenant so preview_status/candidate_open read the right scope
+    // (idempotent — checkoutTenant already switched when the fresh mint succeeded).
     await client.callTool("client_switch", { tenant });
 
     // 2b. PR-backed candidate (g1b candidate_open, unit c1) — best-effort: a
@@ -576,12 +774,15 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     //   otherwise       → the remembered active candidate (from a prior --new /
     //                     roll), else the STABLE per-dev-per-tenant default.
     // If the chosen candidate turns out to be merged/closed, roll to a fresh one
-    // so a re-submit is never wedged on a dead PR.
-    const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
+    // so a re-submit is never wedged on a dead PR. (`repo` was derived above.)
     const readBlob = (path) => execFileSync("git", ["-C", workspace, "show", `HEAD:${path}`], { stdio: ["ignore", "pipe", "pipe"] });
     const statePath = defaultCandidateStatePath(env);
-    const stableId = deriveChangeId(tenant, actorKeyFor(session));
-    const active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo }) : null;
+    // Branch-bound (u4): the candidate handle + active-pointer namespace fold in the
+    // current git branch on a non-default branch, so a feature branch gets its OWN
+    // candidate; the default branch keeps today's exact id (zero migration).
+    const branch = currentBranch(gitSafe);
+    const stableId = deriveChangeId(tenant, actorKeyFor(session), branch);
+    const active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch }) : null;
     let changeId = args.new ? mintFreshChangeId(stableId) : (active || stableId);
     // Persist when we diverge from the stable default (a --new fork, or a
     // previously-remembered active pointer) so the next plain submit follows it.
@@ -601,7 +802,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // never let a state-write failure break the submit).
     if (persist && repo && candidate && !isTerminalCandidateState(candidate.state)) {
       try {
-        writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, changeId });
+        writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch, changeId });
       } catch { /* best-effort local hint — a miss just re-derives the stable id */ }
     }
 
@@ -722,6 +923,38 @@ function reportComplianceCheck(c) {
   if (c.hint) console.log(`        → fix: ${c.hint}`);
 }
 
+/**
+ * Build the printed lines for the headline "share this with your reviewer" block —
+ * the whole point of U14: on a successful preview, the SHAREABLE deep link
+ * (`https://storefront.tokenoftrust.store/preview/<tenant>/pr/<N>`, built server-side
+ * by the reconcile report and threaded through as `previewUrl`) is what a developer
+ * hands to a teammate, NOT the internal Gitea PR url `reportCandidate` prints earlier
+ * in the flow (step 2b) — that one stays as-is, secondary, for the developer's own
+ * reference. Labeled prominently + paired with an honest auth caveat: the share
+ * target is a TEAMMATE WITH STORE ACCESS (member/staff of the tenant), never a
+ * public/anonymous link.
+ *
+ * Degrades gracefully when `previewUrl` isn't (yet) on the status result — an older
+ * MCP, or a reconcile that hasn't finished minting it — with a note instead of a
+ * crash or a silent blank. Pure — unit-tested.
+ * @param {{ previewUrl?: string|null, status?: string }|null} s
+ * @param {string} tenant
+ * @returns {string[]}
+ */
+export function formatShareableUrlBlock(s, tenant) {
+  if (s?.previewUrl) {
+    return [
+      `\n  ✓ Preview ready — share this with your reviewer:`,
+      `      ${s.previewUrl}`,
+      `    ℹ your reviewer needs store access (a member/staff of ${tenant}) to view it — it's not a public link.`,
+    ];
+  }
+  if (s?.status === "reconciled") {
+    return [`\n  ~ reconciled, but no shareable preview URL yet — it'll show up here once available.`];
+  }
+  return [];
+}
+
 /**
  * Print the reconcile/compliance/preview result and, on a clean reconcile with a
  * preview URL, open it in the browser (unless opts.open === false).
@@ -755,10 +988,8 @@ function reportStatus(s, tenant, { open = true } = {}) {
   } else if (s.status === "reconciled") {
     console.log(`\n  ~ not yet shipped — a reviewer still needs to run change_accept.`);
   }
-  if (s.previewUrl) {
-    console.log(`\n  Preview: ${s.previewUrl}`);
-    if (open && s.status === "reconciled" && openBrowser(s.previewUrl)) {
-      console.log("  (opened in your browser)");
-    }
+  for (const line of formatShareableUrlBlock(s, tenant)) console.log(line);
+  if (s.previewUrl && open && s.status === "reconciled" && openBrowser(s.previewUrl)) {
+    console.log("  (opened in your browser)");
   }
 }

package/src/plan.mjs

@@ -0,0 +1,160 @@
+/**
+ * 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
+ * here, and `AdminPublishTab.astro`'s confirm dialog, which renders the same
+ * shape of plan text server-side/inline).
+ *
+ * `planForAction` is PURE (no I/O, no prompt) so it's trivially unit-tested
+ * and reusable anywhere a plan needs to be rendered (CLI stdout, an admin
+ * confirm() dialog, a future dry-run flag). `printPlanAndConfirm` is the CLI
+ * 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.
+ *
+ * Dependency-free (no imports besides the sibling `prompt.mjs`).
+ */
+import { isInteractive, promptYesNo } from "./prompt.mjs";
+
+/**
+ * A human-readable label for the thing an action targets: "PR #N" when a PR
+ * number is known, else the change id, else a neutral fallback. Pure.
+ * @param {{ pr?: number|string|null, changeId?: string|null }} p
+ * @returns {string}
+ */
+function targetLabel({ pr, changeId }) {
+  if (pr != null && `${pr}`.trim()) return `PR #${pr}`;
+  if (changeId) return changeId;
+  return "this change";
+}
+
+/**
+ * Build the EXACT plan for a mutating operator verb — structured lines ready
+ * to print verbatim (CLI) or join for a confirm() dialog (admin). Pure: no
+ * console output, no network, no prompting.
+ *
+ * @param {{
+ *   action: "build"|"accept"|"ship"|"retire",
+ *   tenant: string,
+ *   pr?: number|string|null,
+ *   changeId?: string|null,
+ *   headSha?: string|null,
+ *   endpoint?: string|null,
+ *   targets?: { preview?: string|null, live?: string|null },
+ *   context?: "developer"|"operator",
+ * }} params
+ * @returns {string[]} plan lines (no leading/trailing blank line)
+ */
+export function planForAction({
+  action,
+  tenant,
+  pr = null,
+  changeId = null,
+  headSha = null,
+  endpoint = null,
+  targets = {},
+  context = "operator",
+}) {
+  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 (endpoint) lines.push(`  endpoint:  POST ${endpoint}`);
+
+  switch (action) {
+    case "build": {
+      lines.push(
+        `  effect:    materialize ${label}'s candidate preview — NO merge, NO go-live, NO channel flip.`,
+      );
+      if (targets.preview) lines.push(`  viewable:  ${targets.preview}`);
+      break;
+    }
+    case "accept": {
+      lines.push(`  effect:    merge ${label} into main.`);
+      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}.`);
+      }
+      break;
+    }
+    case "retire": {
+      lines.push(`  effect:    evict ${label}'s preview environment + version (rebuildable).`);
+      break;
+    }
+    default: {
+      lines.push(`  effect:    ${action} ${label}.`);
+      break;
+    }
+  }
+  return lines;
+}
+
+/** "build" → "Build-on-demand", "accept" → "Accept", "ship" → "Ship", "retire" → "Retire". 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";
+  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:
+ *
+ *   - `yes: true` → confirmed immediately, no prompt (the verb's `--yes`).
+ *   - a non-TTY (CI, piped) → refuses without prompting (never silently acts).
+ *   - otherwise → asks `question` via `promptYesNo` (default NO unless the
+ *     caller opts in with `defaultYes`).
+ *
+ * Returns a reason alongside the boolean so the caller can render its own
+ * house-style refusal/abort message (verbs differ: "nothing was built" vs
+ * "nothing shipped" etc.) — this helper only owns the plan + the gate.
+ *
+ * @param {string[]} planLines
+ * @param {{ yes?: boolean, question?: string, defaultYes?: boolean }} [opts]
+ * @returns {Promise<{ confirmed: boolean, reason: "yes-flag"|"confirmed"|"declined"|"non-tty" }>}
+ */
+export async function printPlanAndConfirm(planLines, { yes = false, question = "Proceed?", defaultYes = false } = {}) {
+  for (const line of planLines) console.log(line);
+  console.log("");
+
+  if (yes) return { confirmed: true, reason: "yes-flag" };
+
+  if (!isInteractive()) {
+    return { confirmed: false, reason: "non-tty" };
+  }
+
+  const ok = await promptYesNo(question, defaultYes);
+  return { confirmed: ok, reason: ok ? "confirmed" : "declined" };
+}

package/src/sample.mjs

@@ -26,7 +26,7 @@
  * Dependency-free (node:fs + node:path only).
  */
 import {
-  cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync,
+  appendFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -41,6 +41,11 @@ const here = dirname(fileURLToPath(import.meta.url)); // packages/cli/src
  * version-manager shell hooks land on a supported Node just by cd-ing into
  * their store, and a plain `nvm use` works with no argument. Best-effort:
  * never fails the checkout.
+ *
+ * When `dir` is a git working copy (true for `tot clone`, not for the
+ * non-git sample scaffold), the dropped file is also excluded LOCALLY
+ * (`.git/info/exclude`) so it doesn't leave a fresh `tot clone` dirty —
+ * `git status` right after cloning must read clean. See `excludeLocally`.
  * @param {string} dir @param {NodeJS.ProcessEnv} [env]
  */
 export function writeNvmrc(dir, env = process.env) {
@@ -48,11 +53,32 @@ export function writeNvmrc(dir, env = process.env) {
     const p = join(dir, ".nvmrc");
     if (existsSync(p)) return; // the store repo's own pin wins
     writeFileSync(p, pickNvmrcVersion(env) + "\n");
+    excludeLocally(dir, ".nvmrc");
   } catch {
     /* a missing .nvmrc never blocks the loop */
   }
 }
 
+/**
+ * Add `pattern` to `<dir>/.git/info/exclude` — a LOCAL-only ignore list that
+ * never touches the repo's own committed `.gitignore` (so we don't mutate a
+ * tenant's tracked files just to keep our own convenience drop-in out of
+ * their way). No-op when `dir` isn't a git working copy, or `pattern` is
+ * already excluded (a repeat `tot clone` into the same dir, or the repo's
+ * own `.gitignore` already covering it — appending again would just be
+ * redundant, not wrong). Best-effort: never throws past its caller's `try`.
+ * @param {string} dir @param {string} pattern
+ */
+function excludeLocally(dir, pattern) {
+  const gitDir = join(dir, ".git");
+  if (!existsSync(gitDir) || !statSync(gitDir).isDirectory()) return; // no .git, or a submodule-style .git FILE — skip
+  const excludePath = join(gitDir, "info", "exclude");
+  const existing = existsSync(excludePath) ? readFileSync(excludePath, "utf8") : "";
+  if (existing.split("\n").some((l) => l.trim() === pattern)) return; // already excluded
+  mkdirSync(join(gitDir, "info"), { recursive: true });
+  appendFileSync(excludePath, (existing && !existing.endsWith("\n") ? "\n" : "") + pattern + "\n");
+}
+
 /**
  * The version `.nvmrc` should pin: the NEWEST Node the developer ALREADY has
  * installed under nvm that meets the floor — so `nvm use` succeeds with zero