@tokenoftrust/cli 1.4.0-rc.9 → 1.4.1

package/src/plan.mjs

@@ -0,0 +1,262 @@
+/**
+ * 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 is queued/integrated/deployed, which
+ * deploy targets (preview / live) are touched, and their URLs — and get an
+ * explicit confirm before acting. (`accept` now queue-integrates a PR into the
+ * `preview` aggregate — unit b08 — rather than merging it to main.) 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 has ONE meaning (unit b10 — supersedes the retired context-dependent
+ * ship, decision `ship-context-dependent-semantics`): it publishes the
+ * tenant's CURRENT GREEN AGGREGATE — the batch of PRs that integrated
+ * cleanly — to live. No merge, no PR/candidate targeting, no developer-vs-
+ * operator branching. The plan states the pinned aggregate sha, its
+ * content-addressed artifact digest, every included PR, the rollback target,
+ * and the go-live paywall verdict, so the human reviews EXACTLY what "green"
+ * means before confirming.
+ *
+ * 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"|"revert"|"cleanup"|"hotfix",
+ *   tenant: string,
+ *   pr?: number|string|null,
+ *   changeId?: string|null,
+ *   headSha?: string|null,
+ *   integrationSha?: string|null,
+ *   endpoint?: string|null,
+ *   targets?: { preview?: string|null, live?: string|null },
+ *   context?: "developer"|"operator",
+ *   pinnedSha?: string|null,
+ *   artifactDigest?: string|null,
+ *   includedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>,
+ *   rollbackTarget?: { receiptId: string, aggregateSha: string } | null,
+ *   paywall?: { allowed: boolean, message?: string|null } | null,
+ *   refs?: Array<{ ref: string, sha?: string|null, reason?: string|null }>,
+ *   bypassedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>,
+ *   bypassedPreviewSha?: string|null,
+ * }} params
+ * @returns {string[]} plan lines (no leading/trailing blank line)
+ */
+export function planForAction({
+  action,
+  tenant,
+  pr = null,
+  changeId = null,
+  headSha = null,
+  integrationSha = null,
+  endpoint = null,
+  targets = {},
+  context = "operator",
+  pinnedSha = null,
+  artifactDigest = null,
+  includedPrs = null,
+  rollbackTarget = null,
+  paywall = null,
+  refs = null,
+  bypassedPrs = null,
+  bypassedPreviewSha = null,
+}) {
+  void context; // retained param — no action currently branches on it (ship, the
+  // last one that did, is now ONE meaning; kept so a future action can opt in).
+  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 (integrationSha) lines.push(`  integration sha: ${integrationSha}`);
+  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": {
+      // Accept now means QUEUE-INTEGRATE-INTO-PREVIEW (unit b08), NOT merge-to-main:
+      // the candidate lands in the protected `preview` aggregate (serialized merge →
+      // rebuild → combined-evidence gate), and the aggregate goes live only later via
+      // `tot ship`. So the plan states the integration, never a merge or a go-live.
+      const into = tenant ? `${tenant}'s preview aggregate` : "the preview aggregate";
+      lines.push(
+        `  effect:    queue ${label} for integration into ${into} — NO merge to main, NO go-live.`,
+      );
+      break;
+    }
+    case "ship": {
+      // ONE meaning (b10): publish the tenant's CURRENT GREEN AGGREGATE to live.
+      // No merge — b09's orchestrator ships the already-materialized, already-
+      // reviewed digest. State exactly WHAT that is: the pinned sha, the
+      // content-addressed artifact digest, every included PR, the rollback
+      // target, and the go-live paywall verdict — so the human reviews the
+      // real content of "green" before confirming.
+      lines.push(
+        `  effect:    publish the current green aggregate to live${targets.live ? ` (${targets.live})` : ""} — no merge.`,
+      );
+      if (pinnedSha) lines.push(`  pinned sha:      ${pinnedSha}`);
+      if (artifactDigest) lines.push(`  artifact digest: ${artifactDigest}`);
+      if (Array.isArray(includedPrs)) {
+        lines.push(`  included PRs (${includedPrs.length}):`);
+        for (const p of includedPrs) {
+          const prLabel = p && p.prNumber != null ? `#${p.prNumber}` : p?.changeId || "(no PR)";
+          const shortSha = p && p.headSha ? ` ${String(p.headSha).slice(0, 8)}` : "";
+          lines.push(`    - ${prLabel}${shortSha}`);
+        }
+      }
+      lines.push(
+        rollbackTarget
+          ? `  rollback to: ${rollbackTarget.aggregateSha} (receipt ${rollbackTarget.receiptId})`
+          : "  rollback to: (none — first-ever ship)",
+      );
+      if (paywall && paywall.allowed === false) {
+        lines.push(`  ⚠ paywall:   ${paywall.message || "go-live is blocked by the storefront subscription gate"}`);
+      }
+      break;
+    }
+    case "retire": {
+      lines.push(`  effect:    evict ${label}'s preview environment + version (rebuildable).`);
+      break;
+    }
+    case "cleanup": {
+      // Branch GC (P1 items 9/10): delete ONLY the exact terminal refs a fresh
+      // server-side classification (candidate_list) marked eligible — never by
+      // age alone, never main/preview, never an orphan. State the exact set so
+      // the human confirms precisely what will be removed, not "some branches".
+      const list = Array.isArray(refs) ? refs : [];
+      lines.push(
+        `  effect:    delete ${list.length} terminal candidate branch(es) — never main/preview, ` +
+          "never by age alone, never a quarantined orphan.",
+      );
+      for (const r of list) {
+        const shortSha = r?.sha ? ` ${String(r.sha).slice(0, 8)}` : "";
+        lines.push(`    - ${r?.ref}${shortSha}${r?.reason ? `  — ${r.reason}` : ""}`);
+      }
+      break;
+    }
+    case "revert": {
+      // Revert (b21): REMOVE already-integrated content from the protected `preview`
+      // aggregate by creating a NEW auditable revert commit — never a force-reset,
+      // never a branch delete. The aggregate rebuilds and ships only when green
+      // again. State exactly that: preview-only, a new commit, NO touch to main.
+      const from = tenant ? `${tenant}'s preview aggregate` : "the preview aggregate";
+      const what = integrationSha ? `integration ${integrationSha}` : label;
+      lines.push(
+        `  effect:    revert ${what} out of ${from} — a NEW revert commit, NO force-reset, NO merge to main, NO go-live.`,
+      );
+      break;
+    }
+    case "hotfix": {
+      // Hotfix (b22): the EXPLICIT EXCEPTION lane. Release the reviewed fix from
+      // `main` to live, EXCLUDING the unshipped `preview` work — then automatically
+      // forward-integrate `main` into `preview` and re-validate. State exactly that,
+      // and — critically — list the unshipped preview work this deliberately BYPASSES,
+      // so the human confirms an unmistakable exception, not an ordinary ship.
+      lines.push(
+        `  effect:    OWNER HOTFIX — release ${label} from main to live${targets.live ? ` (${targets.live})` : ""}, ` +
+          `EXCLUDING the unshipped preview head, then forward-integrate main → preview + revalidate.`,
+      );
+      if (Array.isArray(bypassedPrs)) {
+        if (bypassedPrs.length === 0) {
+          lines.push("  bypasses:  (nothing — preview has no unshipped work)");
+        } else {
+          lines.push(`  ⚠ BYPASSES the unshipped preview work (${bypassedPrs.length}) — NOT included in this hotfix:`);
+          for (const p of bypassedPrs) {
+            const prLabel = p && p.prNumber != null ? `#${p.prNumber}` : p?.changeId || "(no PR)";
+            const shortSha = p && p.headSha ? ` ${String(p.headSha).slice(0, 8)}` : "";
+            lines.push(`    - ${prLabel}${shortSha}`);
+          }
+        }
+      }
+      if (bypassedPreviewSha) lines.push(`  preview head (bypassed): ${bypassedPreviewSha}`);
+      lines.push(
+        rollbackTarget
+          ? `  rollback to: ${rollbackTarget.aggregateSha} (receipt ${rollbackTarget.receiptId})`
+          : "  rollback to: (none — first-ever ship)",
+      );
+      if (paywall && paywall.allowed === false) {
+        lines.push(`  ⚠ paywall:   ${paywall.message || "go-live is blocked by the storefront subscription gate"}`);
+      }
+      break;
+    }
+    default: {
+      lines.push(`  effect:    ${action} ${label}.`);
+      break;
+    }
+  }
+  return lines;
+}
+
+/** "build" → "Build-on-demand", "accept" → "Accept", … "hotfix" → "Hotfix". 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";
+  if (action === "revert") return "Revert";
+  if (action === "cleanup") return "Cleanup";
+  if (action === "hotfix") return "Hotfix (owner-only exception lane)";
+  return action ? action[0].toUpperCase() + action.slice(1) : "Operation";
+}
+
+/**
+ * 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

package/src/validate.mjs

@@ -27,6 +27,38 @@ function mk(level, rule, file, message, fix) {
   return { level, rule, file, message, fix };
 }
 
+// --- git conflict markers ----------------------------------------------------
+// A half-resolved merge/rebase can commit literal conflict markers into content
+// (the incident: `<<<<<<<`/`=======`/`>>>>>>>` in content/home.html slipped past
+// preview as "validated"). These are the default and diff3 marker lines, anchored
+// at line start and exactly 7 chars with a trailing boundary — precise enough that
+// real content never matches. `=======` / `|||||||` ALONE are NOT flagged (a lone
+// `=======` is a common markdown/prose horizontal rule); only the START (`<<<<<<<`)
+// and END (`>>>>>>>`) markers trigger — either one is a near-certain conflict, so
+// we err false-negative-averse and flag on either.
+const CONFLICT_START = /^<{7}(?=[ \t]|$)/;
+const CONFLICT_END = /^>{7}(?=[ \t]|$)/;
+
+/**
+ * Line numbers (1-based) of git conflict markers in `content`. Empty ⇒ none.
+ * Pure — exported for focused testing.
+ * @param {string} content
+ * @returns {number[]}
+ */
+export function detectConflictMarkers(content) {
+  if (typeof content !== "string" || (!content.includes("<<<<<<<") && !content.includes(">>>>>>>"))) return [];
+  const lines = content.split(/\r?\n/);
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (CONFLICT_START.test(lines[i]) || CONFLICT_END.test(lines[i])) hits.push(i + 1);
+  }
+  return hits;
+}
+
+// Text artifacts a conflict marker can hide in (images/fonts live in public/, not scanned).
+const CONFLICT_SCAN_EXT = new Set([".html", ".htm", ".json", ".md", ".txt", ".css", ".js", ".mjs", ".svg", ".xml"]);
+const hasScanExt = (p) => CONFLICT_SCAN_EXT.has((p.match(/\.[^./\\]+$/) || [""])[0].toLowerCase());
+
 // --- canonical `.tot/config.json` shape (the #24/#25 regression guard) --------
 const KNOWN_KINDS = new Set(["file", "tree"]);
 const REQUIRED_WORKSPACES = ["content/", "public/", "theme.json"];
@@ -539,6 +571,26 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  // 5. git conflict markers — advisory (never blocks), but LOUD: a half-resolved
+  // merge/rebase must not slip past as "validated". Scans text artifacts under
+  // content/ plus the root config files.
+  const conflictScanFiles = [
+    ...walk(contentDir, hasScanExt),
+    ...["theme.json", "capabilities.json", "scripts.json", join(".tot", "config.json")]
+      .map((f) => join(tenantDir, f))
+      .filter((p) => existsSync(p)),
+  ];
+  for (const p of conflictScanFiles) {
+    const lines = detectConflictMarkers(readFileSync(p, "utf8"));
+    if (lines.length) {
+      findings.push(
+        mk(WARN, "git-conflict-markers", rel(p),
+          `git conflict markers at line(s) ${lines.join(", ")} — looks like an unfinished merge/rebase (the page would still build/serve broken)`,
+          "resolve the conflict and remove the <<<<<<< / ======= / >>>>>>> lines before submitting"),
+      );
+    }
+  }
+
   const ok = !findings.some((f) => f.level === ERROR);
   return { ok, findings };
 }