@tokenoftrust/cli 1.3.4-rc.3 → 1.3.4-rc.5

package/bin/tot.cjs

@@ -40,21 +40,49 @@ if (!meets) {
       "  → next: install Node " + RECOMMENDED_NODE + " (LTS) — nvm: `nvm install " + RECOMMENDED_NODE +
       " && nvm use " + RECOMMENDED_NODE + "`, or https://nodejs.org/ — then re-run the same command.\n"
   );
-  process.exit(1);
-}
+  // Beacon the hosted cockpit that this machine dead-ended on the Node floor, then
+  // exit. This is THE headline obstacle: an invited dev whose `tot login` (the
+  // pasted setup command) can't even run because their Node is too old. We're
+  // pre-login, pre-ESM, maybe pre-`fetch` — so the beacon reads the bridge
+  // credential straight from the pasted flags and posts over require("https").
+  // Best-effort and time-boxed: the ✗ message is already printed; we only linger
+  // (≤ the beacon's own timeout) to deliver telemetry before exit(1).
+  beaconNodeTooOld(nodeVersion, function () { process.exit(1); });
+} else {
+  // Supported Node from here on. Hand off to the ESM CLI; pathToFileURL keeps
+  // the import specifier correct on Windows drive-letter paths too.
+  var path = require("path");
+  var pathToFileURL = require("url").pathToFileURL;
+  var entry = pathToFileURL(path.join(__dirname, "tot.mjs")).href;
 
-// Supported Node from here on. Hand off to the ESM CLI; pathToFileURL keeps
-// the import specifier correct on Windows drive-letter paths too.
-var path = require("path");
-var pathToFileURL = require("url").pathToFileURL;
-var entry = pathToFileURL(path.join(__dirname, "tot.mjs")).href;
+  // new Function with a CONSTANT body ("return import(u)") — nothing is ever
+  // interpolated into the code string; the entry URL travels as an argument. This
+  // indirection exists only so pre-import() parsers never see the import syntax.
+  new Function("u", "return import(u)")(entry).catch(function (e) {
+    // tot.mjs formats + exits on its own errors; landing here means the CLI
+    // itself failed to LOAD on a supported Node — a packaging bug, worth the detail.
+    process.stderr.write("✗ tot failed to start: " + ((e && e.message) || e) + "\n");
+    process.exit(1);
+  });
+}
 
-// new Function with a CONSTANT body ("return import(u)") — nothing is ever
-// interpolated into the code string; the entry URL travels as an argument. This
-// indirection exists only so pre-import() parsers never see the import syntax.
-new Function("u", "return import(u)")(entry).catch(function (e) {
-  // tot.mjs formats + exits on its own errors; landing here means the CLI
-  // itself failed to LOAD on a supported Node — a packaging bug, worth the detail.
-  process.stderr.write("✗ tot failed to start: " + ((e && e.message) || e) + "\n");
-  process.exit(1);
-});
+// Fire the node-too-old obstacle beacon, then always call `done` (exactly once,
+// bounded by the beacon's timeout). Isolated + fully guarded: any hiccup —
+// missing flags, an old Node that can't require a .cjs, a network stall — just
+// falls through to `done`, so the exit path is never blocked or altered. The
+// heavy lifting lives in the shared ES5 helper so the wire shape can't drift.
+function beaconNodeTooOld(have, done) {
+  try {
+    var mod = require("../src/obstacle-beacon.cjs");
+    var act = mod.parseActivityArgs(process.argv);
+    if (!act.url || !act.token) { done(); return; }
+    var cliVersion;
+    try { cliVersion = require("../package.json").version; } catch (e) {}
+    mod.beacon(
+      { url: act.url, token: act.token, kind: "node-too-old", have: have, need: MIN_NODE, cliVersion: cliVersion },
+      done
+    );
+  } catch (e) {
+    done();
+  }
+}

package/bin/tot.mjs

@@ -15,6 +15,7 @@
  *   tot doctor                check this machine is ready
  *   tot ideas                 copy-paste AI prompts that reliably wow
  *   tot feedback              send a note to ToT + your recent CLI activity  ← built (activity-log.mjs → feedback_submit MCP tool)
+ *   tot app scaffold/dev      build + locally exercise a Private App        ← built (offline; see src/commands/app/)
  *   tot help                  this help
  *
  * Context-aware (see src/context.mjs): the same `tot` does the right thing from
@@ -58,6 +59,8 @@ tot — Token of Trust developer CLI
   tot doctor                check this machine is ready
   tot ideas                 copy-paste AI prompts that reliably wow
   tot feedback "<msg>"      send feedback to Token of Trust (attaches recent activity)
+  tot app scaffold <name>   scaffold a Storefront Private App
+  tot app dev ...           local, offline Private App webhook/manifest/JWT harness
   tot help                  show this help
   tot --version             print the CLI version
 
@@ -134,6 +137,11 @@ async function dispatch(cmd, rest, ctx) {
     return run(rest, ctx);
   }
 
+  if (cmd === "app") {
+    const { run } = await import("../src/commands/app/index.mjs");
+    return run(rest, ctx);
+  }
+
   if (BUILD_ORDER.includes(cmd)) {
     console.error(
       `\`tot ${cmd}\` isn't built yet.\n\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.3.4-rc.3",
+  "version": "1.3.4-rc.5",
   "description": "Token of Trust developer CLI — check out a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",
@@ -25,6 +25,7 @@
   "files": [
     "bin",
     "src",
+    "template",
     "README.md",
     "LICENSE"
   ],

package/src/app-scaffold.mjs

@@ -0,0 +1,84 @@
+/**
+ * Private App scaffolding — `tot app scaffold <name>` (PrivateApps epic D6
+ * Chunk C). Mirrors `sample.mjs`'s `scaffoldSample`: materialize a bundled
+ * template onto disk, idempotently, fully offline. No login, no MCP, no
+ * network — a developer building a Storefront Private App gets a runnable
+ * skeleton before they've registered anything with Token of Trust.
+ *
+ * The scaffolded tree also gets its own copy of `src/vendor/private-apps-devkit.mjs`
+ * (as `lib/private-apps-devkit.mjs`) so the stub `server.js` can verify webhook
+ * signatures with zero runtime dependencies — see that file's module doc for
+ * why this is a vendored copy rather than a package.json dependency.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url)); // packages/cli/src
+
+/** Absolute path to the bundled private-app template (ships via package.json `files`). */
+export function appTemplateDir() {
+  return resolve(here, "..", "template", "private-app");
+}
+
+/** Absolute path to the vendored devkit copied into every scaffolded app. */
+export function vendoredDevkitPath() {
+  return resolve(here, "vendor", "private-apps-devkit.mjs");
+}
+
+/** A directory carries a scaffolded app if it has a `tot-app.json` manifest. */
+export function isAppScaffold(dir) {
+  return existsSync(join(dir, "tot-app.json"));
+}
+
+/** A directory is "empty enough" to scaffold into if it's absent or has no entries. */
+function isEmptyDir(dir) {
+  if (!existsSync(dir)) return true;
+  try {
+    return readdirSync(dir).length === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Materialize a Private App skeleton at `destDir`: copy the bundled template
+ * (`tot-app.json`, `fixtures/`, `README.md`, `Dockerfile`, `.env.example`,
+ * `server.js`) in, then drop this package's vendored devkit at `lib/`.
+ * Idempotent — re-running against an already-scaffolded directory is a no-op
+ * that returns it. Refuses to clobber a non-scaffold, non-empty directory.
+ *
+ * @param {string} destDir
+ * @param {{ force?: boolean, log?: (m: string) => void }} [opts]
+ * @returns {{ dir: string, created: boolean }}
+ */
+export function scaffoldApp(destDir, { force = false, log = () => {} } = {}) {
+  const dir = resolve(destDir);
+
+  if (isAppScaffold(dir) && !force) {
+    log(`  ✓ reusing existing app scaffold ${dir}`);
+    return { dir, created: false };
+  }
+  if (!force && !isEmptyDir(dir)) {
+    const err = new Error(
+      `${dir} isn't empty and isn't an app scaffold — scaffold into an empty directory (or pass a new name)`,
+    );
+    err.code = "ENOTEMPTY_APP";
+    throw err;
+  }
+
+  const template = appTemplateDir();
+  if (!existsSync(template)) {
+    const err = new Error("the private-app template isn't available in this release yet — it's coming soon.");
+    err.code = "TEMPLATE_UNAVAILABLE";
+    throw err;
+  }
+
+  mkdirSync(dir, { recursive: true });
+  cpSync(template, dir, { recursive: true });
+  mkdirSync(join(dir, "lib"), { recursive: true });
+  cpSync(vendoredDevkitPath(), join(dir, "lib", "private-apps-devkit.mjs"));
+
+  log(`  ✓ scaffolded a private app → ${dir}`);
+  return { dir, created: true };
+}

package/src/banner.mjs

@@ -0,0 +1,46 @@
+/**
+ * Shared, dependency-free milestone banners — the emphasized, rule-delimited
+ * blocks for the first-run "look back at your Developer Cockpit" moments:
+ * "You're live" (start.mjs) and the first save→reload beat (dev-logs.mjs).
+ *
+ * Deliberately NO figlet/ASCII-art dependency — a horizontal rule frames the
+ * block so the moment reads as a distinct milestone (not another log line),
+ * while staying consistent with printSampleBanner/printDevBanner's indented,
+ * business voice — just louder. Node built-ins only (URL).
+ */
+
+/** The product name every terminal milestone points the developer back to. */
+export const DEVELOPER_COCKPIT = "Developer Cockpit";
+
+const RULE = "━".repeat(56);
+
+/**
+ * Render an emphasized milestone banner as a single string (leading + trailing
+ * blank line included). Each line is indented two spaces and framed by a heavy
+ * horizontal rule top and bottom — no side borders, so emoji/Unicode content
+ * never mis-aligns a right edge. Pure + exported so it's unit-tested.
+ * @param {string[]} lines content lines (already free of the two-space indent)
+ * @returns {string}
+ */
+export function milestoneBanner(lines) {
+  const body = (lines || []).map((l) => `  ${l}`).join("\n");
+  return `\n  ${RULE}\n${body}\n  ${RULE}\n`;
+}
+
+/**
+ * Derive the hosted Developer Cockpit URL (`<origin>/cockpit`) from the cached
+ * activity-bridge URL (creds.activityUrl / TOT_DEV_ACTIVITY_URL). Returns null
+ * when there's no bridge URL (a bare `tot login`, an older session, or the
+ * zero-login `--sample` path) so callers cleanly omit the cockpit line.
+ * Pure + exported so it's unit-tested.
+ * @param {string|null|undefined} activityUrl
+ * @returns {string|null}
+ */
+export function cockpitUrlFrom(activityUrl) {
+  if (!activityUrl) return null;
+  try {
+    return new URL("/cockpit", String(activityUrl)).toString();
+  } catch {
+    return null;
+  }
+}

package/src/commands/app/dev.mjs

@@ -0,0 +1,268 @@
+/**
+ * `tot app dev` — the local Private App harness (PrivateApps epic D6 Chunk D).
+ * Everything here is OFFLINE: no network beyond the localhost URL you point
+ * it at, no MCP, no real ToT credentials. It generates and reuses its own
+ * throwaway RS256 keypair per app directory (`.tot/dev-keys.json`) so signing
+ * and verifying webhook deliveries — and minting widget-launch JWTs — works
+ * before you've registered anything with Token of Trust.
+ *
+ *   tot app dev validate [<manifest>]     lint tot-app.json against the contract
+ *   tot app dev emit <topic>              sign a fixture CloudEvent and POST it
+ *   tot app dev verify --url ... --body ...   verify a captured webhook delivery
+ *   tot app dev mint                      mint a dev widget-launch JWT
+ *
+ * Uses this package's vendored copy of `@tokenoftrust/private-apps-devkit`
+ * (../../vendor/private-apps-devkit.mjs — see that file for why it's vendored
+ * rather than a dependency) for every crypto operation, so a scaffolded app's
+ * own `server.js` (which imports the SAME functions from its copy at
+ * `lib/private-apps-devkit.mjs`) verifies exactly what this harness signs.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fail } from "../../errors.mjs";
+import {
+  signWebhookRequest,
+  verifyWebhookSignature,
+  mintJwt,
+  generateDevRs256KeyPair,
+  validateManifest,
+} from "../../vendor/private-apps-devkit.mjs";
+
+const USAGE = `tot app dev — run your Private App's webhook loop locally, offline
+
+  tot app dev validate [<manifest>]        lint tot-app.json (default ./tot-app.json)
+  tot app dev emit <topic> [--url <url>]   sign a fixtures/<topic>.cloudevent.json and POST it
+    [--fixture <path>] [--app <dir>]
+  tot app dev verify --url <url> --body <file>   verify a captured webhook delivery
+    --content-digest <v> --signature-input <v> --signature <v> [--key <jwk-file>]
+  tot app dev mint [--claims <json>] [--exp <secs>] [--app <dir>]   mint a dev widget-launch JWT
+
+All subcommands accept --app <dir> (default: cwd) to point at a scaffolded app.`;
+
+export function makeRequestId() {
+  return `req_${randHex(6)}`;
+}
+export function makeTraceparent() {
+  return `00-${randHex(16)}-${randHex(8)}-01`;
+}
+function randHex(bytes) {
+  return Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString("hex");
+}
+
+/** Load or create the app's throwaway RS256 keypair at `<appDir>/.tot/dev-keys.json`. */
+export async function ensureDevKeys(appDir, { kid } = {}) {
+  const keysPath = join(appDir, ".tot", "dev-keys.json");
+  const alg = { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" };
+
+  if (existsSync(keysPath)) {
+    const stored = JSON.parse(readFileSync(keysPath, "utf8"));
+    const privateKey = await crypto.subtle.importKey("jwk", stored.privateKeyJwk, alg, true, ["sign"]);
+    const publicKey = await crypto.subtle.importKey("jwk", stored.publicKeyJwk, alg, true, ["verify"]);
+    return { ...stored, privateKey, publicKey, keysPath };
+  }
+
+  const { publicKey, privateKey } = await generateDevRs256KeyPair();
+  const publicKeyJwk = await crypto.subtle.exportKey("jwk", publicKey);
+  const privateKeyJwk = await crypto.subtle.exportKey("jwk", privateKey);
+  const record = { kid: kid || "dev-key-1", publicKeyJwk, privateKeyJwk };
+  mkdirSync(dirname(keysPath), { recursive: true });
+  writeFileSync(keysPath, JSON.stringify(record, null, 2) + "\n");
+  return { ...record, privateKey, publicKey, keysPath };
+}
+
+/** The manifest's declared signatureKeyId, if any — used as the kid for freshly-generated keys. */
+export function manifestKeyId(appDir) {
+  try {
+    const manifest = JSON.parse(readFileSync(join(appDir, "tot-app.json"), "utf8"));
+    return manifest?.webhooks?.signatureKeyId || null;
+  } catch {
+    return null;
+  }
+}
+
+function readInput(pathOrDash) {
+  if (pathOrDash === "-") {
+    return readFileSync(0, "utf8"); // stdin
+  }
+  return readFileSync(resolve(pathOrDash), "utf8");
+}
+
+// ── validate ─────────────────────────────────────────────────────────────
+
+function runValidate(argv, { appDir }) {
+  const manifestPath = resolve(argv[0] || join(appDir, "tot-app.json"));
+  if (!existsSync(manifestPath)) {
+    console.error(fail(`no manifest at ${manifestPath}`, "tot app scaffold <name>, or pass a path"));
+    return 2;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (e) {
+    console.error(fail(`${manifestPath} is not valid JSON: ${e.message}`));
+    return 1;
+  }
+  const result = validateManifest(parsed);
+  if (result.ok) {
+    console.log(`✔ ${manifestPath} is a valid tot-app.json (contract v${result.manifest.contractVersion})`);
+    return 0;
+  }
+  console.log(`✖ ${manifestPath} — ${result.errors.length} error(s):`);
+  for (const e of result.errors) console.log(`  - ${e}`);
+  return 1;
+}
+
+// ── emit ─────────────────────────────────────────────────────────────────
+
+export function parseEmitArgs(argv) {
+  const a = { topic: null, url: "http://localhost:8787/webhooks", fixture: null };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--url") a.url = argv[++i];
+    else if (t === "--fixture") a.fixture = argv[++i];
+    else if (!t.startsWith("--") && !a.topic) a.topic = t;
+  }
+  return a;
+}
+
+async function runEmit(argv, { appDir }) {
+  const args = parseEmitArgs(argv);
+  if (!args.topic) {
+    console.error(fail("tot app dev emit needs a topic", "tot app dev emit order.created"));
+    return 2;
+  }
+  const fixturePath = resolve(args.fixture || join(appDir, "fixtures", `${args.topic}.cloudevent.json`));
+  if (!existsSync(fixturePath)) {
+    console.error(fail(`no fixture at ${fixturePath}`, "pass --fixture <path>, or add one under fixtures/"));
+    return 2;
+  }
+  const body = readFileSync(fixturePath, "utf8");
+
+  const keys = await ensureDevKeys(appDir, { kid: manifestKeyId(appDir) });
+  const { headers } = await signWebhookRequest({ method: "POST", url: args.url, body, key: keys.privateKey, kid: keys.kid });
+
+  const requestId = makeRequestId();
+  const traceparent = makeTraceparent();
+  console.log(`→ POST ${args.url}  (topic: ${args.topic}, keyid: ${keys.kid})`);
+  console.log(`  tot-request-id: ${requestId}`);
+  console.log(`  traceparent:    ${traceparent}`);
+
+  let response;
+  try {
+    response = await fetch(args.url, {
+      method: "POST",
+      headers: { ...headers, "content-type": "application/json", "tot-request-id": requestId, traceparent },
+      body,
+    });
+  } catch (e) {
+    console.error(fail(`could not reach ${args.url}: ${e.message}`, "start your receiver first (e.g. `node server.js`)"));
+    return 1;
+  }
+  const text = await response.text();
+  console.log(`← ${response.status} ${text}`);
+  return response.ok ? 0 : 1;
+}
+
+// ── verify ───────────────────────────────────────────────────────────────
+
+export function parseVerifyArgs(argv) {
+  const a = { method: "POST", url: null, body: null, contentDigest: null, signatureInput: null, signature: null, key: null };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--method") a.method = argv[++i];
+    else if (t === "--url") a.url = argv[++i];
+    else if (t === "--body") a.body = argv[++i];
+    else if (t === "--content-digest") a.contentDigest = argv[++i];
+    else if (t === "--signature-input") a.signatureInput = argv[++i];
+    else if (t === "--signature") a.signature = argv[++i];
+    else if (t === "--key") a.key = argv[++i];
+  }
+  return a;
+}
+
+async function runVerify(argv, { appDir }) {
+  const args = parseVerifyArgs(argv);
+  if (!args.url || !args.body || !args.contentDigest || !args.signatureInput || !args.signature) {
+    console.error(
+      fail(
+        "tot app dev verify needs --url --body --content-digest --signature-input --signature",
+        "tot app dev verify --help",
+      ),
+    );
+    return 2;
+  }
+  const body = readInput(args.body);
+  const keyJwk = args.key
+    ? JSON.parse(readInput(args.key)).publicKeyJwk ?? JSON.parse(readInput(args.key))
+    : JSON.parse(readFileSync(join(appDir, ".tot", "dev-keys.json"), "utf8")).publicKeyJwk;
+  const publicKey = await crypto.subtle.importKey("jwk", keyJwk, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, true, [
+    "verify",
+  ]);
+
+  const result = await verifyWebhookSignature({
+    method: args.method,
+    url: args.url,
+    body,
+    headers: { "content-digest": args.contentDigest, "signature-input": args.signatureInput, signature: args.signature },
+    publicKey,
+  });
+
+  if (result.ok) {
+    console.log(`✔ signature verified (keyid: ${result.keyid}, created: ${result.created})`);
+    return 0;
+  }
+  console.log(`✖ signature verification failed: ${result.code} — ${result.reason}`);
+  return 1;
+}
+
+// ── mint ─────────────────────────────────────────────────────────────────
+
+export function parseMintArgs(argv) {
+  const a = { claims: null, exp: 300 };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--claims") a.claims = argv[++i];
+    else if (t === "--exp") a.exp = Number(argv[++i]);
+  }
+  return a;
+}
+
+async function runMint(argv, { appDir }) {
+  const args = parseMintArgs(argv);
+  const claims = args.claims ? JSON.parse(args.claims) : { scope: "widgets:launch", tenant: "example", env: "dev" };
+  const keys = await ensureDevKeys(appDir, { kid: manifestKeyId(appDir) });
+  const expiresAt = Math.floor(Date.now() / 1000) + args.exp;
+  const token = await mintJwt({ claims, privateKey: keys.privateKey, kid: keys.kid, expiresAt });
+
+  console.log(token);
+  console.log(`\n(dev-only — signed with the throwaway key at ${keys.keysPath}, kid: ${keys.kid}, expires in ${args.exp}s)`);
+  return 0;
+}
+
+// ── dispatch ─────────────────────────────────────────────────────────────
+
+export function parseTopArgs(argv) {
+  const appIdx = argv.indexOf("--app");
+  const appDir = appIdx >= 0 ? resolve(argv[appIdx + 1]) : resolve(process.cwd());
+  const rest = appIdx >= 0 ? [...argv.slice(0, appIdx), ...argv.slice(appIdx + 2)] : argv;
+  return { appDir, rest };
+}
+
+/** @param {string[]} argv */
+export async function run(argv) {
+  const [sub, ...subArgv] = argv;
+  if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+    console.log(USAGE);
+    return sub ? 0 : 2;
+  }
+
+  const { appDir, rest } = parseTopArgs(subArgv);
+
+  if (sub === "validate") return runValidate(rest, { appDir });
+  if (sub === "emit") return runEmit(rest, { appDir });
+  if (sub === "verify") return runVerify(rest, { appDir });
+  if (sub === "mint") return runMint(rest, { appDir });
+
+  console.error(fail(`unknown \`tot app dev\` subcommand: ${sub}`, "tot app dev --help"));
+  return 2;
+}

package/src/commands/app/index.mjs

@@ -0,0 +1,35 @@
+/**
+ * `tot app` — the Storefront Private App developer subcommand group
+ * (PrivateApps epic D6 Chunks C+D): scaffold a new app, then exercise its
+ * webhook/manifest/widget-launch loop entirely offline.
+ *
+ *   tot app scaffold <name>   materialize a runnable Private App skeleton
+ *   tot app dev ...           local, offline webhook/manifest/JWT harness
+ */
+import { fail } from "../../errors.mjs";
+
+const USAGE = `tot app — build a Storefront Private App
+
+  tot app scaffold <name>   scaffold a runnable Private App skeleton
+  tot app dev ...           local, offline webhook/manifest/JWT harness (see \`tot app dev --help\`)`;
+
+/** @param {string[]} argv @param {any} ctx */
+export async function run(argv, ctx) {
+  const [sub, ...rest] = argv;
+  if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+    console.log(USAGE);
+    return sub ? 0 : 2;
+  }
+
+  if (sub === "scaffold") {
+    const { run: runScaffold } = await import("./scaffold.mjs");
+    return runScaffold(rest, ctx);
+  }
+  if (sub === "dev") {
+    const { run: runDev } = await import("./dev.mjs");
+    return runDev(rest, ctx);
+  }
+
+  console.error(fail(`unknown \`tot app\` subcommand: ${sub}`, "tot app --help"));
+  return 2;
+}

package/src/commands/app/scaffold.mjs

@@ -0,0 +1,57 @@
+/**
+ * `tot app scaffold <name>` — materialize a runnable Storefront Private App
+ * skeleton on disk (PrivateApps epic D6 Chunk C). See ../../app-scaffold.mjs
+ * for the offline, idempotent copy logic this wraps.
+ *
+ *   tot app scaffold <name>          scaffold ./<name>
+ *   tot app scaffold <name> --force  overwrite a non-empty, non-scaffold dir
+ *
+ * Exit 0 = scaffolded (or already scaffolded); 2 = usage / refused.
+ */
+import { resolve } from "node:path";
+import { scaffoldApp } from "../../app-scaffold.mjs";
+import { fail } from "../../errors.mjs";
+
+function parseArgs(argv) {
+  const a = { name: null, force: false, help: false };
+  for (const t of argv) {
+    if (t === "--force") a.force = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+    else if (!t.startsWith("--") && !a.name) a.name = t;
+  }
+  return a;
+}
+
+const USAGE = `tot app scaffold <name> — scaffold a Storefront Private App
+
+  tot app scaffold <name>          scaffold ./<name>
+  tot app scaffold <name> --force  overwrite a non-empty, non-scaffold directory`;
+
+/** @param {string[]} argv */
+export function run(argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (!args.name) {
+    console.error(fail("tot app scaffold needs a directory name", "tot app scaffold <name>"));
+    return 2;
+  }
+
+  try {
+    const { dir, created } = scaffoldApp(resolve(process.cwd(), args.name), {
+      force: args.force,
+      log: (m) => console.log(m),
+    });
+    console.log(
+      created
+        ? `\nNext:\n  cd ${args.name}\n  tot app dev validate\n  tot app dev --help\n`
+        : `\n${dir} is already scaffolded.\n`,
+    );
+    return 0;
+  } catch (e) {
+    console.error(fail(e.message));
+    return 2;
+  }
+}

package/src/commands/checkout.mjs

@@ -24,6 +24,7 @@ import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { writeNvmrc } from "../sample.mjs";
+import { emitObstacle } from "../obstacle.mjs";
 
 const execFileP = promisify(execFile);
 
@@ -202,6 +203,10 @@ async function cloneRepo(gitRemote, dir, redact) {
   try {
     await git(["clone", gitRemote, dir]);
   } catch (e) {
+    // Beacon the cockpit before we surface the error — covers this path for both
+    // `tot checkout` and `tot start` (which clones through here). Awaited so the
+    // packet lands before the process prints + exits; swallowed either way.
+    await emitObstacle("clone-failed");
     throw new CliError(`clone failed: ${redact(String(e.stderr || e.message || e))}`, {
       next: `check the target dir is empty and you can reach the remote, then re-run`,
     });