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

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