@tokenoftrust/cli 1.0.0

package/src/commands/dev.mjs

@@ -0,0 +1,564 @@
+/**
+ * `tot dev` — run your store locally with save→reload.
+ *
+ * The runtime splits by context:
+ *
+ *   monorepo — the storefront runner IS present in the tree, so `tot dev`
+ *              delegates to the proven scripts/tot-dev.mjs (astro dev + Vite HMR,
+ *              monorepo or --workspace graft mode). Fast host loop for platform devs.
+ *
+ *   checkout — a standalone tenant checkout has no runner. `tot dev` DOWNLOADS the
+ *              published, moat-free RUNNER ARTIFACT (a plain tarball — the exact
+ *              same tree Docker used to bake into the image, see
+ *              scripts/build/build-runner.mjs) and runs it NATIVELY: no Docker, no
+ *              container. Cached once per version under ~/.tot/cache/renderer/, so
+ *              only the first run pays the download+install cost. The runner's own
+ *              scripts/tot-dev.mjs grafts the checkout in and boots astro dev
+ *              --host at http://localhost:<port>/<appDomain>/, with real (not
+ *              polled) file-watch HMR. Nothing is published; product data renders
+ *              from local fixtures. Docker remains available as a fallback
+ *              (--docker, or automatically if the native artifact can't be
+ *              fetched) — see runContainer below.
+ *
+ * IP note: the artifact is the pruned runner (control plane physically absent),
+ * vended by a short-lived signed URL (`dev_renderer_artifact`) gated on the same
+ * developer entitlement as the Docker pull token — no hand-provisioned AWS creds
+ * either way.
+ */
+import { spawn, spawnSync, execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, createWriteStream } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { createMcpClient } from "../mcp.mjs";
+import { resolveSession } from "../auth.mjs";
+import { CliError, fail, formatError } from "../errors.mjs";
+import { openBrowser, waitForServer } from "../open.mjs";
+
+/** The published moat-free runner image (--docker fallback). Override with --image / TOT_DEV_IMAGE. */
+const DEFAULT_DEV_IMAGE =
+  "242086487598.dkr.ecr.us-east-1.amazonaws.com/tot-dev:latest";
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+/** Where downloaded+installed renderer-artifact versions are cached, one dir per version. */
+const RENDERER_CACHE_ROOT = join(homedir(), ".tot", "cache", "renderer");
+
+export function parseArgs(argv) {
+  const a = {
+    workspace: null, port: "4321", image: null, mcp: null,
+    noLogin: false, noOpen: false, docker: false, help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === "--workspace") a.workspace = argv[++i];
+    else if (t === "--port") a.port = argv[++i];
+    else if (t === "--image") a.image = argv[++i];
+    else if (t === "--mcp") a.mcp = argv[++i];
+    else if (t === "--no-login") a.noLogin = true;
+    else if (t === "--no-open") a.noOpen = true;
+    else if (t === "--docker") a.docker = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+const USAGE = `tot dev — run your store locally with save→reload
+
+  tot dev <tenant>              (in the monorepo) run tenants/<tenant>/
+  tot dev                       (in a checkout) run this store natively (no Docker)
+  tot dev --workspace <dir>     run a specific checkout directory
+  tot dev --port <n>            host port (default 4321)
+  tot dev --docker              use the Docker runner image instead of the native path
+  tot dev --image <ref>         runner image ref, only with --docker (default: the published image)
+  tot dev --no-open             don't auto-open the browser when the server is up
+
+Edit content/*.html or the theme + save → the browser reloads. Private local
+preview — nothing is published. Prerequisites: Node.js and an invite — no Docker,
+no hand-provisioned AWS creds.`;
+
+/** @param {string[]} argv @param {any} ctx */
+export function run(argv, ctx) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  // Monorepo: delegate to the in-tree runner (host astro dev + HMR).
+  if (ctx.mode === "monorepo" && !args.workspace) {
+    return runMonorepo(ctx, argv);
+  }
+
+  // Standalone checkout (or an explicit --workspace anywhere): native by default,
+  // Docker on request (--docker) or as an automatic fallback (see runStandalone).
+  const workspace = args.workspace
+    ? resolve(args.workspace)
+    : ctx.mode === "checkout"
+      ? ctx.workspacePath
+      : null;
+  if (!workspace) {
+    console.error(
+      fail(
+        "nothing to run — you're not inside a tenant checkout",
+        "tot checkout <tenant> --clone <dir>   (then `cd` in and re-run), or pass --workspace <dir>",
+      ),
+    );
+    return 2;
+  }
+  return runStandalone(workspace, args, ctx);
+}
+
+/**
+ * Standalone-checkout entrypoint: native runtime by default (F3 — no Docker
+ * prerequisite), Docker on explicit request, and Docker as an automatic
+ * fallback when the native artifact can't be fetched (e.g. the MCP's
+ * dev_renderer_artifact isn't configured on this deployment yet) — so `tot dev`
+ * keeps working through the WS3 rollout instead of hard-failing.
+ */
+async function runStandalone(workspace, args, ctx) {
+  if (args.docker) return runContainer(workspace, args, ctx);
+  try {
+    return await runNative(workspace, args, ctx);
+  } catch (e) {
+    if (e instanceof NativeArtifactUnavailableError) {
+      console.error(
+        `~ native runtime unavailable (${e.message}) — falling back to the Docker runner.`,
+      );
+      return runContainer(workspace, args, ctx);
+    }
+    console.error(formatError(e));
+    return e instanceof CliError ? (e.exitCode ?? 2) : 2;
+  }
+}
+
+function runMonorepo(ctx, argv) {
+  const script = join(ctx.repoRoot, "scripts", "tot-dev.mjs");
+  if (!existsSync(script)) {
+    console.error(`✗ expected the dev runner at ${script} but it's missing.`);
+    return 2;
+  }
+  return new Promise((resolvePromise) => {
+    const child = spawn(process.execPath, [script, ...argv], { stdio: "inherit" });
+    child.on("exit", (code) => resolvePromise(code ?? 0));
+    child.on("error", (e) => {
+      console.error(`✗ could not start the dev runner: ${e.message}`);
+      resolvePromise(1);
+    });
+  });
+}
+
+/**
+ * Thrown when the native runtime can't be used for a reason that's about the
+ * artifact/service, not the developer's checkout — runStandalone catches this
+ * specifically and falls back to Docker instead of hard-failing. Exported so
+ * `tot start` (C1/F3 integration) can catch it too and fall back the same way.
+ */
+export class NativeArtifactUnavailableError extends Error {}
+
+/** Same URL shape buildContainerPlan uses — factored out so native + Docker agree. */
+export function deriveUrl(cfg, port) {
+  const domain = typeof cfg.scope === "string" && cfg.scope.includes(".") ? cfg.scope : null;
+  return { domain, url: `http://localhost:${port}/${domain ? `${domain}/` : ""}` };
+}
+
+async function runNative(workspace, args, ctx) {
+  const cfg = readWorkspaceConfig(workspace);
+  if (!cfg) {
+    throw new CliError(`${workspace} isn't a tenant checkout (no readable .tot/config.json)`, {
+      next: "tot checkout <tenant> --clone <dir>   (produces a runnable checkout)",
+      exitCode: 2,
+    });
+  }
+  const port = String(args.port || "4321");
+  const { domain, url } = deriveUrl(cfg, port);
+
+  const runnerDir = await ensureRendererArtifact(args);
+
+  printDevBanner({ tenant: cfg.tenant || null, url });
+
+  const handle = spawnNativeDev(runnerDir, workspace, port, { stdio: "inherit" });
+
+  // Auto-open the browser the moment the server answers (D). Non-blocking so
+  // Ctrl-C / logs are unaffected; --no-open suppresses it.
+  if (!args.noOpen) {
+    let opened = false;
+    waitForServer(url, { until: () => handle.exited })
+      .then((up) => {
+        if (up && !opened) {
+          opened = true;
+          openBrowser(url);
+        }
+      })
+      .catch(() => {});
+  }
+
+  return handle.done;
+}
+
+/**
+ * Get the moat-free renderer artifact for this host — a signed URL from the MCP
+ * (dev_renderer_artifact, same entitlement gate as the Docker pull token),
+ * downloaded + extracted + `pnpm install`'d ONCE per version under
+ * ~/.tot/cache/renderer/<version>/. Later runs of the same version reuse the
+ * cache with no network call at all. Throws NativeArtifactUnavailableError for
+ * anything that should fall back to Docker (MCP unreachable, not entitled, not
+ * configured, no corepack/pnpm on this host) rather than hard-failing `tot dev`.
+ *
+ * Exported + accepts an already-authenticated `client` (C1/F3 integration:
+ * `tot start` reuses its own session and overlaps this with the checkout clone
+ * instead of paying for a second client.initialize()+resolveSession() — same
+ * pattern as ensureRegistryLogin's `providedClient`). `tot dev` standalone
+ * omits it and this establishes its own, as before.
+ * @returns {Promise<string>} the cached, installed runner tree's root directory.
+ */
+export async function ensureRendererArtifact(args, { client: providedClient } = {}) {
+  const baseUrl = args.mcp || process.env.MCP_BASE_URL || process.env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  let credential;
+  try {
+    const client = providedClient || createMcpClient(baseUrl);
+    if (!providedClient) {
+      await client.initialize();
+      await resolveSession(client, { env: process.env });
+    }
+    const res = await client.callTool("dev_renderer_artifact", {});
+    if (!res?.url || !res?.version) {
+      throw new Error(res?.error || "no renderer-artifact URL returned");
+    }
+    credential = res;
+  } catch (e) {
+    throw new NativeArtifactUnavailableError(String(e?.message || e));
+  }
+
+  const runnerDir = join(RENDERER_CACHE_ROOT, credential.version);
+  const marker = join(runnerDir, ".tot-cache-complete");
+  if (existsSync(marker)) return runnerDir; // already downloaded + installed
+
+  console.error(`~ fetching the native renderer (version ${credential.version}, first run only)...`);
+  const archivePath = join(tmpdir(), `tot-renderer-${process.pid}-${Date.now()}.tar.gz`);
+  try {
+    await downloadFile(credential.url, archivePath);
+    const stagingDir = `${runnerDir}.staging-${process.pid}`;
+    rmSync(stagingDir, { recursive: true, force: true });
+    mkdirSync(stagingDir, { recursive: true });
+    extractTarball(archivePath, stagingDir);
+    ensureCorepackPnpm(stagingDir);
+    runPnpmInstall(stagingDir);
+    // Atomic-ish: only rename into the final, discoverable path once install
+    // succeeded, so a crashed/interrupted run never leaves a half-built cache
+    // entry that a later `tot dev` would treat as ready.
+    rmSync(runnerDir, { recursive: true, force: true });
+    renameSync(stagingDir, runnerDir);
+    writeFileSync(marker, new Date().toISOString());
+  } catch (e) {
+    throw new NativeArtifactUnavailableError(String(e?.message || e));
+  } finally {
+    rmSync(archivePath, { force: true });
+  }
+  return runnerDir;
+}
+
+/** Stream `url` to `destPath`. Throws on a non-2xx response or a network failure. */
+async function downloadFile(url, destPath) {
+  const res = await fetch(url);
+  if (!res.ok || !res.body) {
+    throw new Error(`download failed: HTTP ${res.status} ${res.statusText}`);
+  }
+  await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
+}
+
+/** Extract a .tar.gz into `destDir` using the system `tar` (present on macOS/Linux/WSL). */
+function extractTarball(archivePath, destDir) {
+  const r = spawnSync("tar", ["xzf", archivePath, "-C", destDir], { stdio: ["ignore", "ignore", "pipe"] });
+  if (r.status !== 0) {
+    throw new Error(`tar extraction failed: ${r.stderr?.toString().trim() || `exit ${r.status}`}`);
+  }
+}
+
+/**
+ * Activate the exact package manager the runner's package.json pins
+ * (packageManager: "pnpm@x.y.z"), via corepack — Node 20+ ships corepack, so
+ * this needs no separate pnpm install on the host. Best-effort: if corepack
+ * itself is missing (very old Node), pnpm install below will surface that
+ * clearly instead.
+ */
+function ensureCorepackPnpm(runnerDir) {
+  const pkgPath = join(runnerDir, "package.json");
+  if (!existsSync(pkgPath)) return;
+  let pm;
+  try {
+    pm = JSON.parse(readFileSync(pkgPath, "utf8")).packageManager;
+  } catch {
+    return;
+  }
+  if (!pm) return;
+  spawnSync("corepack", ["enable"], { stdio: "ignore" });
+  spawnSync("corepack", ["prepare", pm, "--activate"], { stdio: "ignore" });
+}
+
+function runPnpmInstall(runnerDir) {
+  const r = spawnSync("pnpm", ["install", "--config.dangerouslyAllowAllBuilds=true"], {
+    cwd: runnerDir,
+    stdio: "inherit",
+  });
+  if (r.status !== 0) {
+    throw new Error(`pnpm install failed (exit ${r.status}) — is pnpm/corepack available on this host?`);
+  }
+}
+
+/**
+ * Run the cached runner's own scripts/tot-dev.mjs in standalone (--workspace)
+ * mode — the exact code path the WS3 spike verified gives native, non-polled
+ * fs-watch HMR. Returns a handle shaped like spawnDevContainer's, so run()'s
+ * auto-open-browser logic works unchanged for either runtime. Exported (and
+ * `stdio` overridable) so `tot start` can pipe the logs instead of inheriting.
+ */
+export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit" } = {}) {
+  const script = join(runnerDir, "scripts", "tot-dev.mjs");
+  const child = spawn(
+    process.execPath,
+    [script, "--workspace", workspace, "--port", port],
+    { cwd: runnerDir, stdio },
+  );
+  const handle = { child, exited: false, done: null };
+  handle.done = new Promise((resolvePromise) => {
+    child.on("exit", (code) => {
+      handle.exited = true;
+      resolvePromise(code ?? 0);
+    });
+    child.on("error", (e) => {
+      handle.exited = true;
+      console.error(fail(`could not start the native dev runner: ${e.message}`));
+      resolvePromise(1);
+    });
+  });
+  return handle;
+}
+
+async function runContainer(workspace, args, ctx) {
+  let plan;
+  try {
+    plan = buildContainerPlan(workspace, args, ctx);
+  } catch (e) {
+    console.error(formatError(e));
+    return e instanceof CliError ? (e.exitCode ?? 2) : 2;
+  }
+
+  printDevBanner(plan);
+
+  const handle = await spawnDevContainer(plan, args, { stdio: "inherit" });
+
+  // Auto-open the browser the moment the server answers (D). Non-blocking so
+  // Ctrl-C / logs are unaffected; --no-open suppresses it.
+  if (!args.noOpen) {
+    let opened = false;
+    waitForServer(plan.url, { until: () => handle.exited })
+      .then((up) => {
+        if (up && !opened) {
+          opened = true;
+          openBrowser(plan.url);
+        }
+      })
+      .catch(() => {});
+  }
+
+  return handle.done;
+}
+
+/**
+ * Resolve the runner image ref the same way buildContainerPlan does — exported
+ * so a caller (`tot start`, for C1) can know the image, and therefore prefetch
+ * a registry login (below), before the checkout dir exists.
+ */
+export function resolveDevImage(args, env = process.env) {
+  return args.image || env.TOT_DEV_IMAGE || DEFAULT_DEV_IMAGE;
+}
+
+/**
+ * Validate + assemble everything needed to run a standalone checkout in the
+ * runner container, without side effects. Throws a CliError (with the exact
+ * next command) when the checkout or Docker isn't ready. Shared by `tot dev`
+ * and `tot start`.
+ *
+ * @param {string} workspace @param {ReturnType<typeof parseArgs>} args @param {any} _ctx
+ * @returns {{ tenant: string|null, image: string, port: string, domain: string|null,
+ *   url: string, workspace: string, dockerArgs: string[] }}
+ */
+export function buildContainerPlan(workspace, args, _ctx) {
+  const cfg = readWorkspaceConfig(workspace);
+  if (!cfg) {
+    throw new CliError(`${workspace} isn't a tenant checkout (no readable .tot/config.json)`, {
+      next: "tot checkout <tenant> --clone <dir>   (produces a runnable checkout)",
+      exitCode: 2,
+    });
+  }
+  if (!dockerAvailable()) {
+    throw new CliError("`tot dev` needs Docker to run a standalone checkout, but Docker isn't running", {
+      next:
+        process.platform === "darwin"
+          ? "open -a Docker   (then re-run) — or install it: https://docs.docker.com/get-docker/"
+          : "start Docker (e.g. `sudo systemctl start docker`), then re-run — install: https://docs.docker.com/get-docker/",
+      exitCode: 2,
+    });
+  }
+
+  const image = resolveDevImage(args);
+  const port = String(args.port || "4321");
+  const domain = typeof cfg.scope === "string" && cfg.scope.includes(".") ? cfg.scope : null;
+  const url = `http://localhost:${port}/${domain ? `${domain}/` : ""}`;
+
+  // docker run equivalent of scripts/dev/docker-compose.pull.yml: bind-mount the
+  // checkout, map the port, force polling (reliable HMR across the mount), pull
+  // if the image is missing. --rm + --init so Ctrl-C tears it down cleanly.
+  const dockerArgs = [
+    "run",
+    "--rm",
+    "--init",
+    "--pull",
+    "missing",
+    "-p",
+    `${port}:4321`,
+    "-v",
+    `${workspace}:/workspace`,
+    "-e",
+    "CHOKIDAR_USEPOLLING=1",
+    "-e",
+    "CHOKIDAR_INTERVAL=300",
+    image,
+  ];
+
+  return { tenant: cfg.tenant || null, image, port, domain, url, workspace, dockerArgs };
+}
+
+/** The crafted "here's your running store" block (Vite/`vercel dev`-grade). */
+export function printDevBanner(plan) {
+  console.error(`\n  tot dev — ${plan.tenant || "(tenant)"}`);
+  console.error(`  ➜  Local:    ${plan.url}`);
+  console.error(`  ➜  Edit:     content/home.html + save → the browser reloads`);
+  console.error(`  ➜  Private local preview — nothing is published. Ctrl-C to stop.\n`);
+}
+
+/**
+ * Pull-credential + spawn the runner container. Returns a handle:
+ *   { child, done, exited } — `done` resolves to the exit code, `exited` is a
+ *   live boolean (for readiness polling to bail if the container dies early).
+ * `stdio` is "inherit" (a normal `tot dev`) or "piped" (so `tot start` can hold
+ * the prompt on stdin and stream logs after the aha).
+ *
+ * @param {ReturnType<typeof buildContainerPlan>} plan
+ * @param {ReturnType<typeof parseArgs>} args
+ * @param {{ stdio?: "inherit"|"piped" }} [opts]
+ */
+export async function spawnDevContainer(plan, args, { stdio = "inherit" } = {}) {
+  // Obtain a registry pull credential from the MCP (entitlement-gated) before
+  // pulling a private image. Best-effort: falls back to any existing docker login.
+  if (!args.noLogin && isPrivateRegistryImage(plan.image)) {
+    await ensureRegistryLogin(plan.image, args);
+  }
+
+  const stdioArr =
+    stdio === "piped" ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "inherit"];
+  const child = spawn("docker", plan.dockerArgs, { stdio: stdioArr });
+
+  const handle = { child, exited: false, done: null };
+  handle.done = new Promise((resolvePromise) => {
+    child.on("exit", (code) => {
+      handle.exited = true;
+      if (code && code !== 130 /* SIGINT */ && stdio === "inherit") {
+        console.error(
+          fail(
+            `the runner container exited (code ${code})`,
+            `if it couldn't pull ${plan.image}, sign in or ask your ToT contact for a registry pull credential, then re-run`,
+          ),
+        );
+      }
+      resolvePromise(code ?? 0);
+    });
+    child.on("error", (e) => {
+      handle.exited = true;
+      console.error(fail(`could not start Docker: ${e.message}`, "confirm Docker is installed and running, then re-run"));
+      resolvePromise(1);
+    });
+  });
+  return handle;
+}
+
+/** Does this image live in a private registry that needs an authenticated pull? */
+export function isPrivateRegistryImage(image) {
+  const host = String(image).split("/")[0];
+  // A registry host has a dot or a port; ECR/GHCR/etc. Docker Hub short names don't.
+  return host.includes(".dkr.ecr.") || /\.(amazonaws|azurecr|pkg\.dev)\b/.test(host);
+}
+
+/**
+ * Entitlement-gated registry login: ask the MCP for a short-lived pull credential
+ * (`dev_image_pull_token`) and `docker login` with it. Best-effort — if the MCP,
+ * the session, or the tool isn't available yet, warn softly and continue (an
+ * existing `docker login`, or the docker pull error, takes over). This is the CLI
+ * half of ~/.tot-mcp/handoffs/2026-07-09-tot-mcp-dev-image-pull-token.md.
+ *
+ * Exported + accepts an already-authenticated `client` (C1: `tot start` reuses
+ * its own session and overlaps this with the checkout clone instead of paying
+ * for a second client.initialize()+resolveSession() serially afterward).
+ * `tot dev` standalone omits it and this establishes its own, as before.
+ */
+export async function ensureRegistryLogin(image, args, { client: providedClient } = {}) {
+  const registry = String(image).split("/")[0];
+  const baseUrl = args.mcp || process.env.MCP_BASE_URL || process.env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  try {
+    const client = providedClient || createMcpClient(baseUrl);
+    if (!providedClient) {
+      await client.initialize();
+      await resolveSession(client, { env: process.env });
+    }
+    const tok = await client.callTool("dev_image_pull_token", {});
+    const username = tok?.username || "AWS";
+    const password = tok?.password;
+    const reg = tok?.registry || registry;
+    if (!password) throw new Error("no credential returned");
+    execFileSync("docker", ["login", "--username", username, "--password-stdin", reg], {
+      input: password,
+      stdio: ["pipe", "ignore", "ignore"],
+    });
+    console.error(`~ registry sign-in ok (${reg})`);
+  } catch (e) {
+    console.error(
+      `~ (using existing docker login for ${registry} — MCP pull-token not available: ${String(e?.message || e)})`,
+    );
+  }
+}
+
+function readWorkspaceConfig(dir) {
+  const p = join(dir, ".tot", "config.json");
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function dockerAvailable() {
+  const r = spawnSync("docker", ["version", "--format", "{{.Server.Version}}"], {
+    stdio: ["ignore", "ignore", "ignore"],
+  });
+  return r.status === 0;
+}
+
+/**
+ * Best-effort local Docker remediation (macOS only — Docker Desktop is the
+ * thing `open -a` can launch unattended; other platforms report false and
+ * leave it to the caller's usual next-command message). Returns true once
+ * Docker answers, false if it doesn't within the wait window. Shared by
+ * `tot start`'s preflight and `tot doctor --fix` (F2).
+ */
+export async function tryStartDocker() {
+  if (process.platform !== "darwin") return false;
+  console.log("  ~ Docker isn't running — starting Docker Desktop…");
+  spawnSync("open", ["-a", "Docker"], { stdio: "ignore" });
+  for (let i = 0; i < 30; i++) {
+    await delay(1500);
+    if (dockerAvailable()) return true;
+  }
+  return false;
+}