@tokenoftrust/cli 1.4.0-rc.11 → 1.4.0-rc.13

package/src/commands/submit.mjs

@@ -3,7 +3,9 @@
  *
  * 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),
+ *   2. push your committed work to YOUR OWN isolated candidate ref — `candidate/<changeId>`
+ *      (b03 — no shared `preview` ref is ever force-pushed; an explicit `--ref` can still
+ *      target a literal ref name for back-compat) — which 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
@@ -57,10 +59,25 @@ import {
 } from "../candidate-state.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
-const DEFAULT_REF = "preview";
+
+// The git ref prefix an isolated candidate push lands under (b03 — stop
+// force-pushing the SHARED `preview` ref). ONE constant so a rename is trivial —
+// provisionally coordinated with the MCP-side candidate_open resolution (b02/b04),
+// which already names its PR-backed branch `candidate/<changeId>` (see
+// submitCandidate, below): the raw git push here and the PR-backed candidate it
+// opens always target the SAME branch, never two.
+export const CANDIDATE_REF_PREFIX = "candidate/";
+
+/** The isolated git ref a candidate's preview push lands under. Pure. */
+export function candidateRefFor(changeId) {
+  return `${CANDIDATE_REF_PREFIX}${changeId}`;
+}
 
 export function parseArgs(argv) {
-  const a = { mcp: null, identity: null, ref: DEFAULT_REF, skipValidate: false, noWait: false, watch: false, noOpen: false, noCommit: false, message: null, summary: null, new: false, help: false };
+  // `ref: null` — an explicit `--ref` always wins; otherwise the push target is
+  // derived per-run as YOUR OWN isolated candidate ref (resolvePushRef, below),
+  // never a fixed shared default.
+  const a = { mcp: null, identity: null, ref: null, skipValidate: false, noWait: false, watch: false, noOpen: false, noCommit: false, message: null, summary: null, new: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
     if (t === "--mcp") a.mcp = argv[++i];
@@ -93,7 +110,7 @@ export function renderUsage(verb = "preview") {
   tot ${verb} --watch            stay attached through reconcile + compliance + accept (long-poll)
   tot ${verb} --skip-validate    push without the local lint (not recommended)
   tot ${verb} --no-commit        don't auto-commit a dirty tree — preview only what's already committed
-  tot ${verb} --ref <name>       push ref (default: ${DEFAULT_REF})
+  tot ${verb} --ref <name>       push ref (default: your own isolated candidate ref — see \`tot pr\`)
   tot ${verb} -m "<title>"       one-line summary of what changed (the approver sees this)
   tot ${verb} --summary "<text>" longer description to accompany the title
   tot ${verb} --no-wait          push and exit without polling for the reconcile result
@@ -513,6 +530,44 @@ export function actorKeyFor(session) {
   return session?.email || session?.token || "developer";
 }
 
+/**
+ * Which candidate this submit lands on (gh-pr-like) — decided UP FRONT, before any
+ * network call, because it also determines the isolated git ref we push to
+ * (resolvePushRef, below): a re-submit updates the SAME candidate/ref by default;
+ * `--new` forks a fresh one.
+ *   --new     → fork a FRESH candidate id;
+ *   otherwise → the remembered active candidate (from a prior --new / terminal
+ *               roll), else the STABLE per-dev-per-tenant(-per-branch) default.
+ * `persist` reports whether the choice diverges from the stable default, so the
+ * caller knows whether to remember it as the new active pointer. `mint` is
+ * injected (defaults to mintFreshChangeId) so this is pure/deterministic in tests.
+ * Pure — unit-tested.
+ * @param {{ tenant: string, actorKey: string, branch?: string|null, active?: string|null,
+ *   isNew?: boolean, mint?: (baseId: string) => string }} opts
+ * @returns {{ changeId: string, stableId: string, persist: boolean }}
+ */
+export function chooseChangeId({ tenant, actorKey, branch = null, active = null, isNew = false, mint = mintFreshChangeId }) {
+  const stableId = deriveChangeId(tenant, actorKey, branch);
+  const changeId = isNew ? mint(stableId) : (active || stableId);
+  const persist = isNew || (!!active && active !== stableId);
+  return { changeId, stableId, persist };
+}
+
+/**
+ * The ref `tot preview`/`tot submit` pushes to (b03 — stop force-pushing the
+ * SHARED `preview` ref). An explicit `--ref` always wins — the escape hatch /
+ * back-compat path (e.g. `--ref preview` reproduces the old shared-ref push for
+ * any tooling that still reads it by that literal name); otherwise it's YOUR OWN
+ * isolated candidate ref, so two developers — or the same developer on two
+ * branches — never force-push over each other or each other's preview. Pure —
+ * unit-tested.
+ * @param {{ ref?: string|null, changeId: string }} opts
+ * @returns {string}
+ */
+export function resolvePushRef({ ref, changeId }) {
+  return ref || candidateRefFor(changeId);
+}
+
 /**
  * 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"
@@ -663,6 +718,9 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   // 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.
+  // Parameterized on `ref` (b03 — isolated candidate refs): the diff base is YOUR
+  // candidate ref's own tracking ref, not a shared one, so the summary always reads
+  // "vs your own last push" once the push ref is known (computed just below).
   const gitSafe = (cargs) => {
     try {
       return git(cargs);
@@ -670,18 +728,21 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       return "";
     }
   };
-  const headSubject = gitSafe(["log", "-1", "--format=%s"]).trim();
-  const trackingRef = `refs/remotes/origin/${args.ref}`;
-  const base = gitSafe(["rev-parse", "--verify", "--quiet", trackingRef]).trim()
-    ? trackingRef
-    : gitSafe(["rev-parse", "--verify", "--quiet", "HEAD~1"]).trim()
-      ? "HEAD~1"
-      : "";
-  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 });
+  function buildSummaryAndPatch(ref) {
+    const headSubject = gitSafe(["log", "-1", "--format=%s"]).trim();
+    const trackingRef = `refs/remotes/origin/${ref}`;
+    const base = gitSafe(["rev-parse", "--verify", "--quiet", trackingRef]).trim()
+      ? trackingRef
+      : gitSafe(["rev-parse", "--verify", "--quiet", "HEAD~1"]).trim()
+        ? "HEAD~1"
+        : "";
+    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 });
+    return { changeSummary, patchEntries };
+  }
 
   // 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
@@ -690,6 +751,15 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
   const client = createMcpClient(baseUrl);
   const repo = repoNameFromRemote(gitSafe(["remote", "get-url", "origin"]).trim());
 
+  // Branch-bound (u4) + the isolated candidate ref (b03): resolved BEFORE the push,
+  // since the push target itself depends on it — so the raw git push and the
+  // PR-backed candidate (step 2b, below) always land on the SAME branch. `active`/
+  // `statePath` are local filesystem reads (candidate-state.mjs) — no session
+  // needed — so they're available even on the no-session fallback path below.
+  const branch = currentBranch(gitSafe);
+  const statePath = defaultCandidateStatePath(env);
+  const active = repo ? readActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch }) : null;
+
   let session;
   try {
     session = await establishSession(client, { env, prefer: args.identity || undefined });
@@ -697,10 +767,15 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // 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)`);
+    // still lands if that embedded token is live. actorKeyFor(null) degrades to the
+    // generic "developer" key — still isolated PER BRANCH (never the shared ref),
+    // just not per-developer until sign-in succeeds.
+    const { changeId } = chooseChangeId({ tenant, actorKey: actorKeyFor(null), branch, active, isNew: args.new });
+    const ref = resolvePushRef({ ref: args.ref, changeId });
+    const { changeSummary } = buildSummaryAndPatch(ref);
+    console.error(`~ pushing ${short} → ${ref} (origin)`);
     try {
-      const out = git(["push", "-f", "origin", `HEAD:refs/heads/${args.ref}`]);
+      const out = git(["push", "-f", "origin", `HEAD:refs/heads/${ref}`]);
       if (out.trim()) console.error(redactUrl(out.trim()));
     } catch (pushErr) {
       console.error(
@@ -711,7 +786,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
       );
       return 1;
     }
-    console.log(`\n+ submitted ${short} to ${args.ref}.`);
+    console.log(`\n+ submitted ${short} to ${ref}.`);
     printChangeSummary(changeSummary);
     if (e instanceof AuthUnavailableError) {
       console.log(`  (sign in to see the reconcile/compliance/preview result — ${e.hint || "developer sign-in pending"})`);
@@ -722,6 +797,15 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     return 0;
   }
 
+  // Which candidate (and therefore which isolated ref, b03) this submit targets —
+  // decided now, with a real session, so the SAME id backs both the raw git push
+  // (right below) and the PR-backed candidate (step 2b): the two never point at
+  // different branches. See chooseChangeId's doc for the --new / active-pointer
+  // rules.
+  let { changeId, stableId, persist } = chooseChangeId({ tenant, actorKey: actorKeyFor(session), branch, active, isNew: args.new });
+  const ref = resolvePushRef({ ref: args.ref, changeId });
+  const { changeSummary, patchEntries } = buildSummaryAndPatch(ref);
+
   // 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
@@ -741,9 +825,9 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     }
   };
 
-  console.error(`~ pushing ${short} → ${args.ref} (origin, fresh credential)`);
+  console.error(`~ pushing ${short} → ${ref} (origin, fresh credential)`);
   try {
-    const { out } = await pushPreviewRef(git, mintRemote, { ref: args.ref });
+    const { out } = await pushPreviewRef(git, mintRemote, { ref });
     if (out && out.trim()) console.error(redactUrl(out.trim()));
   } catch (e) {
     console.error(
@@ -754,7 +838,7 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     );
     return 1;
   }
-  console.log(`\n+ submitted ${short} to ${args.ref}.`);
+  console.log(`\n+ submitted ${short} to ${ref}.`);
   printChangeSummary(changeSummary);
 
   // 2b + 3. open/update the PR-backed candidate, then report reconcile +
@@ -768,25 +852,11 @@ export async function run(argv, ctx, { verb = "preview" } = {}) {
     // 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.
-    //
-    // Which candidate this submit lands on (gh-pr-like):
-    //   --new           → fork a FRESH candidate and remember it as active;
-    //   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. (`repo` was derived above.)
+    // `changeId`/`stableId`/`persist` were already decided above (they picked the
+    // push ref too); 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. (`repo` was derived
+    // above.)
     const readBlob = (path) => execFileSync("git", ["-C", workspace, "show", `HEAD:${path}`], { stdio: ["ignore", "pipe", "pipe"] });
-    const statePath = defaultCandidateStatePath(env);
-    // 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.
-    let persist = args.new || (!!active && active !== stableId);
 
     let candidate = await submitCandidate(client, { repo, changeId, changeSummary, patchEntries, readBlob });
 
@@ -923,6 +993,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).
@@ -956,10 +1058,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