@tokenoftrust/cli 1.0.0

package/src/commands/start.mjs

@@ -0,0 +1,450 @@
+/**
+ * `tot start` — the zero-arg, value-first first run. One command from an invite
+ * to a running store in your browser, ending at the AI-wow prompt.
+ *
+ * It COMPOSES the other commands' cores in-process (no shelling out to `tot …`):
+ *
+ *   preflight   collectChecks()  (F — self-healing where it can be)
+ *   login       resolveSession()  (operator today; device-code is the B seam)
+ *              (A2 — run concurrently: neither gates the other; wait on the slower)
+ *      ↓
+ *   store       normalizeStores(client_list) → auto-pick if exactly one, else
+ *               use --tenant, else the remembered last tenant, else choose (A4)
+ *      ↓
+ *   checkout ─┬─ checkoutTenant() → ./<tenant>
+ *   runner   ─┘  prefetch the runner: the native renderer artifact by default
+ *               (F3 — no Docker prerequisite), or the Docker registry
+ *               credential on --docker / as the automatic fallback if the
+ *               native artifact can't be fetched (same fallback `tot dev`
+ *               uses — see dev.mjs#NativeArtifactUnavailableError)
+ *              (C1 — run concurrently with checkout: both just need the
+ *               session resolved above)
+ *      ↓
+ *   dev         spawnNativeDev() or spawnDevContainer() → wait for ready →
+ *               open the browser (C/D)
+ *      ↓
+ *   you're live crafted ending (elapsed time printed — A3), seeded with
+ *               IDEAS[0] (G3), THEN the optional "Connect Claude?" prompt: on
+ *               yes, `claude mcp add` AND drop straight into that seeded
+ *               prompt (G2) — the payoff, not a pointer to go write one.
+ *
+ * Value-first ordering (C): the running site + browser come BEFORE any mention of
+ * connecting the MCP; Claude is the supercharge offered after the aha, not a gate.
+ * ONE felt browser login (B2): `claude mcp add` only ever runs behind that final
+ * opt-in — the core loop above needs nothing but the cached `tot login` session.
+ * Every failure ends with the exact next command via the shared formatter (F).
+ *
+ * Dependency-free (node:readline/promises + the cores above).
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+import { detectContext } from "../context.mjs";
+import { createMcpClient } from "../mcp.mjs";
+import { resolveSession } from "../auth.mjs";
+import { CliError, fail, formatError, exitCodeFor } from "../errors.mjs";
+import { openBrowser, waitForServer } from "../open.mjs";
+import { defaultLastTenantPath, readLastTenant, writeLastTenant } from "../last-tenant.mjs";
+import { collectChecks } from "./doctor.mjs";
+import { normalizeStores, checkoutTenant } from "./checkout.mjs";
+import {
+  buildContainerPlan, spawnDevContainer, dockerAvailable, tryStartDocker,
+  resolveDevImage, isPrivateRegistryImage, ensureRegistryLogin,
+  ensureRendererArtifact, spawnNativeDev, deriveUrl, NativeArtifactUnavailableError,
+} from "./dev.mjs";
+import { IDEAS } from "./ideas.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+const CLAUDE_MCP_ARGS = ["mcp", "add", "--transport", "http", "tot", `${DEFAULT_MCP_URL}/mcp`];
+
+function parseArgs(argv) {
+  const a = {
+    mcp: null, identity: null, tenant: null, port: "4321",
+    noOpen: false, noConnect: false, yes: false, docker: false, help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--identity") a.identity = argv[++i];
+    else if (t === "--tenant") a.tenant = argv[++i];
+    else if (t === "--port") a.port = argv[++i];
+    else if (t === "--no-open") a.noOpen = true;
+    else if (t === "--no-connect") a.noConnect = true;
+    else if (t === "--yes" || t === "-y") a.yes = true;
+    else if (t === "--docker") a.docker = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+const USAGE = `tot start — go from invite to a running store in one command
+
+  tot start                 preflight → sign in → pick your store → check out →
+                            run it → open your browser → connect Claude
+Options:
+  --tenant <id>    use this store (skips auto-pick/prompt; remembered for next time)
+  --port <n>       host port for the dev server (default 4321)
+  --docker         use the Docker runner instead of the native runtime (F3
+                    default); also the automatic fallback if the native
+                    artifact can't be fetched
+  --no-open        don't auto-open the browser
+  --no-connect     skip the "Connect Claude for AI editing?" prompt
+  --yes, -y        assume yes for prompts (non-interactive)
+  --identity <who> force "operator" or "developer" auth (default: auto)
+  --mcp <url>      MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+
+On a multi-store identity, the tenant you pick (or pass via --tenant) is
+remembered in ~/.tot/ — the next bare \`tot start\` reuses it automatically.`;
+
+/**
+ * Decide what to do with the stores this identity can build on.
+ * Pure + exported so the auto-pick rule is unit-tested without any I/O.
+ * @param {Array<{id:string,name:string}>} stores
+ * @returns {{ kind: "none" } | { kind: "one", store: object } | { kind: "many", stores: object[] }}
+ */
+export function pickStore(stores) {
+  if (!Array.isArray(stores) || stores.length === 0) return { kind: "none" };
+  if (stores.length === 1) return { kind: "one", store: stores[0] };
+  return { kind: "many", stores };
+}
+
+/**
+ * Decide which tenant to use, given the identity's available stores, an
+ * explicit `--tenant` override, and a remembered "last tenant" from a prior
+ * run (A4). Pure + exported so the precedence is unit-tested without any I/O.
+ * Precedence: explicit > single store (pickStore) > remembered (if still one
+ * of the available stores) > ambiguous ("many" — caller must prompt).
+ * @param {Array<{id:string,name:string}>} stores
+ * @param {{ explicit?: string|null, lastTenant?: string|null }} [opts]
+ * @returns {{ kind: "none" } | { kind: "one", store: object }
+ *   | { kind: "explicit"|"remembered", tenant: string } | { kind: "many", stores: object[] }}
+ */
+export function pickTenant(stores, { explicit = null, lastTenant = null } = {}) {
+  if (explicit) return { kind: "explicit", tenant: explicit };
+  const pick = pickStore(stores);
+  if (pick.kind !== "many") return pick;
+  if (lastTenant && stores.some((s) => s.id === lastTenant)) {
+    return { kind: "remembered", tenant: lastTenant };
+  }
+  return pick;
+}
+
+/** @param {string[]} argv @param {any} ctx */
+export async function run(argv, ctx) {
+  const env = process.env;
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const startedAt = Date.now();
+  try {
+    // 1+2. preflight (F) and login (B) run CONCURRENTLY (A2) — the local machine
+    // checks (node/git/Docker) don't gate the network sign-in and vice versa, so
+    // gate on the slower of the two instead of paying their sum serially.
+    const baseUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+    const client = createMcpClient(baseUrl);
+    const [, session] = await Promise.all([
+      preflight(ctx, env),
+      loginStep(client, env, args),
+    ]);
+    console.log(`  ✓ signed in as ${session.identity}${session.appDomain ? ` (${session.appDomain})` : ""}`);
+
+    // 3. store — auto-pick, use --tenant, use the remembered one, or choose (A4).
+    const stores = normalizeStores(await client.callTool("client_list", {}));
+    const tenant = await resolveTenant(stores, args, env, baseUrl);
+
+    // 4. checkout → ./<tenant> (reuse an existing checkout on a re-run),
+    // OVERLAPPED (C1) with prefetching the runner: the native artifact by
+    // default (F3 — no Docker prerequisite), or the Docker registry
+    // credential on --docker / as the automatic native-unavailable fallback.
+    // Both are independent authenticated calls once login (above) has
+    // resolved, so there's no reason to pay for them serially.
+    const dir = resolve(process.cwd(), tenant);
+    const devArgs = {
+      image: null, port: String(args.port || "4321"), mcp: args.mcp,
+      noLogin: false, noOpen: args.noOpen, docker: args.docker,
+    };
+    const runtime = { useDocker: args.docker, runnerDir: null };
+    await Promise.all([
+      ensureCheckout(client, tenant, dir, env),
+      prefetchRuntime(client, devArgs, env, runtime),
+    ]);
+
+    // 5. dev — native by default (F3), Docker on --docker or the fallback
+    // above; wait for the server, open the browser (C/D).
+    const ctxDev = detectContext(dir);
+    let url, handle;
+    if (runtime.useDocker) {
+      const plan = buildContainerPlan(dir, devArgs, ctxDev);
+      url = plan.url;
+      console.log(`  → starting dev … ${url}`);
+      handle = await spawnDevContainer(plan, devArgs, { stdio: "piped" });
+    } else {
+      url = deriveUrl(ctxDev.config || {}, devArgs.port).url;
+      console.log(`  → starting dev … ${url}`);
+      handle = spawnNativeDev(runtime.runnerDir, dir, devArgs.port, { stdio: "piped" });
+    }
+
+    const up = await Promise.race([
+      waitForServer(url, { until: () => handle.exited }),
+      handle.done.then(() => "exited"),
+    ]);
+    if (up !== true) {
+      throw new CliError("the dev server didn't come up", {
+        next: `cd ${tenant} && tot dev   (to watch the runner logs)`,
+      });
+    }
+    if (!args.noOpen) {
+      openBrowser(url);
+      console.log("  ✓ opened your browser");
+    }
+
+    // 6. you're live (G) — end at the AI-wow, THEN offer the MCP (C). Print the
+    // elapsed time (A3) so the "instant" claim is measured, not just felt.
+    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt));
+    if (!args.noConnect) {
+      const yes = args.yes || (await promptYesNo("  Connect Claude for AI editing?", true));
+      if (yes) connectClaude();
+    }
+
+    // 7. hand the terminal to the running dev server until Ctrl-C.
+    console.log("\n  Streaming dev logs — edit + save to see reloads. Ctrl-C to stop.\n");
+    handle.child.stdout?.pipe(process.stdout);
+    handle.child.stderr?.pipe(process.stderr);
+    return handle.done;
+  } catch (e) {
+    console.error(formatError(e));
+    return exitCodeFor(e);
+  }
+}
+
+/**
+ * MCP init + session resolve — the "login" half of preflight (A2: runs
+ * concurrently with the local machine checks in preflight(), below).
+ */
+async function loginStep(client, env, args) {
+  try {
+    await client.initialize();
+  } catch (e) {
+    throw new CliError(`can't reach the Token of Trust MCP at ${client.mcpUrl} (${String(e?.message || e)})`, {
+      next: "check your network, then re-run — or point elsewhere with --mcp <url>",
+    });
+  }
+  return resolveSession(client, { env, prefer: args.identity || undefined });
+}
+
+/**
+ * Self-healing preflight (F): run the readiness checks; a blocking failure
+ * ends with the next command. Docker is informational-only here (F3: native
+ * is the default runtime, so Docker not running doesn't block `tot start`
+ * anymore) — its own readiness is handled lazily in prefetchDockerLogin(),
+ * only when the run actually needs it (--docker or the native fallback).
+ * Runs concurrently with loginStep (A2) via Promise.all in run(), so nothing
+ * here may assume login has happened.
+ */
+async function preflight(ctx, env) {
+  const checks = collectChecks(ctx, env);
+  const blocked = checks.find((c) => c.blocking && !c.pass);
+  if (blocked) {
+    throw new CliError(`${blocked.name} — ${blocked.detail}`, {
+      next: "install/fix the above, then re-run `tot start`",
+      exitCode: 2,
+    });
+  }
+  console.log("  ✓ preflight ok");
+}
+
+/**
+ * Prefetch the runner (C1) so it's overlapped with checkout instead of paid
+ * for serially afterward: the native renderer artifact by default (F3 — no
+ * Docker prerequisite), or the Docker registry pull credential on --docker.
+ * On a native fetch failure, falls back to Docker automatically — the same
+ * fallback `tot dev` uses (dev.mjs#runStandalone) — flipping
+ * `runtime.useDocker` so the caller's subsequent dev step picks it up.
+ */
+async function prefetchRuntime(client, devArgs, env, runtime) {
+  if (runtime.useDocker) {
+    await prefetchDockerLogin(client, devArgs, env);
+    return;
+  }
+  try {
+    runtime.runnerDir = await ensureRendererArtifact(devArgs, { client });
+  } catch (e) {
+    if (!(e instanceof NativeArtifactUnavailableError)) throw e;
+    console.log(`  ~ native runtime unavailable (${e.message}) — falling back to the Docker runner.`);
+    runtime.useDocker = true;
+    await prefetchDockerLogin(client, devArgs, env);
+  }
+}
+
+/**
+ * The Docker-path half of prefetchRuntime: registry login (reusing the
+ * already-authenticated client, C1) plus a best-effort Docker auto-start
+ * (self-healing — F) so buildContainerPlan doesn't have to hard-fail on a
+ * Docker Desktop that just needs a nudge.
+ */
+async function prefetchDockerLogin(client, devArgs, env) {
+  const devImage = resolveDevImage(devArgs, env);
+  if (isPrivateRegistryImage(devImage)) {
+    await ensureRegistryLogin(devImage, devArgs, { client });
+    devArgs.noLogin = true;
+  }
+  if (!dockerAvailable()) await tryStartDocker();
+}
+
+/**
+ * Resolve the tenant to work on from the (normalized) store list, args, and
+ * the remembered last tenant (A4) — then remember whatever was decided so the
+ * next bare `tot start` doesn't have to ask again.
+ */
+async function resolveTenant(stores, args, env, baseUrl) {
+  const lastTenantPath = defaultLastTenantPath(env);
+  const pick = pickTenant(stores, {
+    explicit: args.tenant || null,
+    lastTenant: readLastTenant(lastTenantPath, baseUrl),
+  });
+
+  let tenant;
+  if (pick.kind === "none") {
+    throw new CliError("no stores you can build on yet", {
+      next: "ask your Token of Trust contact for a store invite, then re-run",
+    });
+  } else if (pick.kind === "explicit") {
+    tenant = pick.tenant;
+    console.log(`  → your store: ${tenant} (--tenant)`);
+  } else if (pick.kind === "one") {
+    tenant = pick.store.id;
+    console.log(`  → your store: ${tenant} (auto-picked — you have one)`);
+  } else if (pick.kind === "remembered") {
+    tenant = pick.tenant;
+    console.log(`  → your store: ${tenant} (remembered from last run)`);
+  } else {
+    // Many stores, nothing remembered — choose. Non-interactive (no TTY /
+    // --yes without a name) can't guess.
+    if (!isInteractive() || args.yes) {
+      throw new CliError("you can build on several stores — pick one", {
+        next: `tot start --tenant <tenant>  (one of: ${pick.stores.map((s) => s.id).join(", ")})`,
+      });
+    }
+    console.log("  Which store do you want to work on?\n");
+    pick.stores.forEach((s, i) => console.log(`    ${i + 1}. ${s.id}${s.name ? `  — ${s.name}` : ""}`));
+    const idx = await promptChoice(pick.stores.length);
+    console.log("");
+    tenant = pick.stores[idx].id;
+  }
+
+  writeLastTenant(lastTenantPath, { mcpUrl: baseUrl, tenant });
+  return tenant;
+}
+
+/** Clone ./<tenant> unless a usable checkout is already there (re-run friendly). */
+async function ensureCheckout(client, tenant, dir, env) {
+  if (existsSync(dir)) {
+    const existing = detectContext(dir);
+    if (existing.mode === "checkout") {
+      console.log(`  ✓ reusing existing checkout ./${tenant}`);
+      return;
+    }
+    throw new CliError(`./${tenant} already exists and isn't a tot checkout`, {
+      next: `remove it (or run \`tot start\` from an empty directory)`,
+      exitCode: 2,
+    });
+  }
+  await checkoutTenant(client, { tenant, cloneDir: dir, redact: makeRedactor(env) });
+  console.log(`  ✓ checked out ./${tenant}`);
+}
+
+/**
+ * Format elapsed milliseconds as a short human string for the "you're live"
+ * ending (A3 — measure, don't just claim, "instant"). Pure + exported so it's
+ * unit-tested without any I/O.
+ * @param {number} ms
+ * @returns {string|null}
+ */
+export function formatElapsed(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return null;
+  return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+
+/** The crafted "you're live" ending — leads with the AI-wow (G), seeded with
+ * IDEAS[0] (G2/G3 — one prompt list shared with `tot ideas`, no drift). */
+function printLiveEnding(tenant, url, elapsed) {
+  console.log("");
+  console.log(`  ✨ You're live.${elapsed ? `  (${elapsed})` : ""}`);
+  console.log(`     ${url}`);
+  console.log("     Edit content/home.html + save → it reloads.");
+  console.log("");
+  console.log("  Now try, in Claude:");
+  console.log(`     "${IDEAS[0]}"`);
+  console.log("");
+  console.log("  More ideas: tot ideas");
+  console.log("");
+}
+
+/**
+ * Offer + wire Claude (G2): `claude mcp add`, then — the payoff, not just a
+ * pointer — drop the user straight into an interactive Claude session already
+ * seeded with IDEAS[0], so there's no blank slate to stare at.
+ */
+function connectClaude() {
+  const cmd = `claude ${CLAUDE_MCP_ARGS.join(" ")}`;
+  console.log(`\n  → ${cmd}`);
+  if (spawnSync("claude", ["--version"], { stdio: "ignore" }).status !== 0) {
+    console.log("  (install Claude Code, then run the command above to connect Claude.)");
+    return;
+  }
+  const r = spawnSync("claude", CLAUDE_MCP_ARGS, { stdio: "inherit" });
+  if (r.status !== 0) {
+    console.log("  (couldn't add it automatically — run the command above to connect Claude.)");
+    return;
+  }
+  console.log(`  ✓ Claude connected — dropping you into: "${IDEAS[0]}"\n`);
+  spawnSync("claude", [IDEAS[0]], { stdio: "inherit" });
+}
+
+// ── small prompt helpers (respect non-TTY so nothing hangs in CI) ────────────
+
+function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+async function promptYesNo(question, defaultYes) {
+  if (!isInteractive()) return defaultYes;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const ans = (await rl.question(`${question} ${defaultYes ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
+    if (!ans) return defaultYes;
+    return ans === "y" || ans === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+/** Prompt for a 1..n choice; returns a 0-based index (defaults to first). */
+async function promptChoice(n) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    for (;;) {
+      const ans = (await rl.question(`  Enter a number [1-${n}]: `)).trim();
+      if (!ans) return 0;
+      const k = Number(ans);
+      if (Number.isInteger(k) && k >= 1 && k <= n) return k - 1;
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+/** Redact operator secrets from any string before it can reach the terminal. */
+function makeRedactor(env) {
+  const secrets = [env.TOT_API_KEY, env.TOT_SECRET_KEY].filter(Boolean);
+  return (s) => {
+    let o = String(s);
+    for (const x of secrets) o = o.split(x).join("***");
+    return o;
+  };
+}