@tokenoftrust/cli 1.0.0

package/src/commands/doctor.mjs

@@ -0,0 +1,172 @@
+/**
+ * `tot doctor` — is this machine ready to run the loop?
+ *
+ * Standalone (unlike the in-monorepo doctor): checks the things `tot checkout`
+ * and `tot dev`/`tot start` actually need — Node, git, an MCP URL, whether an
+ * auth identity is available, and Docker — plus reports the detected context
+ * so a developer knows which mode `tot` will use here.
+ *
+ * Docker is informational-only (not blocking): WS3/F3 made the native runtime
+ * the default for `tot dev`/`tot start`, so a Docker that isn't running no
+ * longer stops the loop — it only matters if you pass --docker or the native
+ * artifact can't be fetched (see dev.mjs#NativeArtifactUnavailableError).
+ *
+ * `--fix` (F2) auto-remediates what it safely can, each fix announced as it
+ * runs: starts Docker (macOS, opportunistically — harmless even though it's
+ * no longer required), creates ~/.tot if it's missing, and signs you in when
+ * there's no usable session at all. Anything it can't fix (or won't — a stale
+ * sign-in silently refreshes on next use instead, no action needed) is left
+ * in the checks list with its usual next command.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { hasOperatorCreds } from "../auth.mjs";
+import { defaultCredentialsPath, readCredentials, isExpired } from "../token-store.mjs";
+import { dockerAvailable, tryStartDocker } from "./dev.mjs";
+import { loginAndCache } from "./login.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+function parseArgs(argv) {
+  const a = { fix: false, help: false };
+  for (const t of argv) {
+    if (t === "--fix") a.fix = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+const USAGE = `tot doctor — is this machine ready to run the loop?
+
+  tot doctor          show the readiness checks
+  tot doctor --fix    auto-remediate what it safely can (Docker, ~/.tot,
+                      signing in if you aren't at all), then re-check`;
+
+/**
+ * The machine-readiness checks, as data — so both `tot doctor` (which prints
+ * them) and `tot start`'s preflight (which acts on the failing ones) read the
+ * exact same set. Each check is `{ name, pass, detail, blocking }`; `blocking`
+ * marks the ones that actually stop the loop (node, git) vs informational
+ * context (MCP endpoint, auth identity, Docker — see the module doc above).
+ *
+ * @param {any} _ctx @param {NodeJS.ProcessEnv} [env]
+ * @returns {Array<{ name: string, pass: boolean, detail: string, blocking: boolean }>}
+ */
+export function collectChecks(_ctx, env = process.env) {
+  const checks = [];
+
+  const nodeMajor = Number(process.versions.node.split(".")[0]);
+  checks.push({ name: "node >= 20", pass: nodeMajor >= 20, detail: `have ${process.versions.node}`, blocking: true });
+
+  const gitRes = spawnSync("git", ["--version"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  const git = gitRes.status === 0 ? String(gitRes.stdout).trim() : null;
+  checks.push({ name: "git installed", pass: !!git, detail: git || "not found — https://git-scm.com", blocking: true });
+
+  const dockerOk = dockerAvailable();
+  checks.push({
+    name: "Docker",
+    pass: dockerOk,
+    detail: dockerOk
+      ? "running"
+      : "not running — optional (native is the default runtime; only needed for --docker or as its fallback)",
+    blocking: false,
+  });
+
+  const mcpUrl = env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  checks.push({
+    name: "MCP endpoint",
+    pass: true,
+    detail: `${mcpUrl}${env.MCP_BASE_URL || env.TOT_MCP_URL ? " (from env)" : " (default)"}`,
+    blocking: false,
+  });
+
+  const operator = hasOperatorCreds(env);
+  const devCreds = operator ? null : readCredentials(defaultCredentialsPath(env));
+  const devUsable = !!devCreds?.accessToken && (!isExpired(devCreds) || !!devCreds.refreshToken);
+  checks.push({
+    name: "auth identity",
+    pass: operator || devUsable,
+    detail: operator
+      ? "operator creds present (TOT_API_KEY/TOT_SECRET_KEY/TOT_APP_DOMAIN)"
+      : devUsable
+        ? "signed in as a developer"
+        : "not signed in — run `tot login`",
+    blocking: false,
+  });
+
+  return checks;
+}
+
+/**
+ * Auto-remediate the checks that are safely fixable without human judgment
+ * (F2) — announcing each one as it runs. A stale-but-refreshable sign-in isn't
+ * handled here because it isn't a failing check: resolveSession() refreshes it
+ * silently the next time it's actually used (B4).
+ */
+async function applyFixes(checks, env) {
+  const totDir = join(env.TOT_HOME || homedir(), ".tot");
+  if (!existsSync(totDir)) {
+    console.log(`  ~ creating ${totDir}`);
+    mkdirSync(totDir, { recursive: true, mode: 0o700 });
+  }
+
+  const docker = checks.find((c) => c.name === "Docker");
+  if (docker && !docker.pass) await tryStartDocker();
+
+  const auth = checks.find((c) => c.name === "auth identity");
+  if (auth && !auth.pass && !hasOperatorCreds(env)) {
+    const mcpUrl = env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+    console.log("  ~ not signed in — opening the browser to sign in…");
+    try {
+      await loginAndCache(mcpUrl, env, { log: (m) => console.log(`  ${m}`) });
+      console.log("  ✓ signed in");
+    } catch (e) {
+      console.log(`  ~ couldn't sign in automatically (${e?.message || e}) — run \`tot login\``);
+    }
+  }
+}
+
+/** @param {string[]} argv @param {any} ctx */
+export async function run(argv, ctx) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  const env = process.env;
+
+  console.log("\ntot doctor\n");
+  console.log(`  context: ${describeContext(ctx)}\n`);
+
+  let checks = collectChecks(ctx, env);
+  if (args.fix) {
+    await applyFixes(checks, env);
+    checks = collectChecks(ctx, env); // re-check after fixing
+  }
+
+  let failed = 0;
+  for (const { name, pass, detail } of checks) {
+    if (!pass) failed++;
+    console.log(`  ${pass ? "✓" : "✗"} ${name}${detail ? `  — ${detail}` : ""}`);
+  }
+  console.log(
+    failed === 0
+      ? "\n✔ Ready. Try: tot start   (checks out your store and runs it), or tot checkout\n"
+      : args.fix
+        ? `\n✖ ${failed} check(s) still failing — see the exact next command(s) above, then re-run \`tot doctor\`.\n`
+        : `\n✖ ${failed} check(s) failed — try \`tot doctor --fix\`, or fix the above, then re-run \`tot doctor\`.\n`,
+  );
+  return failed === 0 ? 0 : 1;
+}
+
+function describeContext(ctx) {
+  if (ctx.mode === "monorepo") return `storefront monorepo (${ctx.repoRoot})`;
+  if (ctx.mode === "checkout")
+    return `tenant checkout${ctx.tenant ? ` for "${ctx.tenant}"` : ""} (${ctx.workspacePath})`;
+  return "loose (not inside a checkout — `tot checkout <tenant> --clone <dir>` to get one)";
+}

package/src/commands/ideas.mjs

@@ -0,0 +1,45 @@
+/**
+ * `tot ideas` — a gallery of copy-paste reskin prompts that reliably wow (G3).
+ * Not a script to run — inspiration for the AI moment: paste one into Claude
+ * (after `tot start`'s "Connect Claude?" prompt, or `claude mcp add` directly)
+ * and watch your store change and reload.
+ *
+ * IDEAS[0] doubles as the seeded first prompt `tot start` ends on and drops
+ * you into (G2, see commands/start.mjs) — one list, no drift between the two.
+ */
+
+/** Reskin prompts, ordered strongest-first. Pure data — exported for reuse + tests. */
+export const IDEAS = [
+  "make it darker but still friendly",
+  "give the homepage a bold, oversized headline",
+  "swap the accent color for something more premium — think matte gold",
+  "make the product grid feel more editorial, like a fashion lookbook",
+  "add a subtle scroll-triggered fade-in to the hero section",
+  "tighten up the spacing everywhere — it feels a little loose",
+];
+
+function parseArgs(argv) {
+  const a = { help: false };
+  for (const t of argv) if (t === "--help" || t === "-h") a.help = true;
+  return a;
+}
+
+const USAGE = `tot ideas — copy-paste prompts that reliably wow
+
+  tot ideas    print a gallery of reskin prompts to try with Claude
+
+Paste one into Claude (after \`tot start\`'s "Connect Claude?" prompt, or
+\`claude mcp add\` directly) and watch your store change and reload.`;
+
+/** @param {string[]} argv @param {any} _ctx */
+export function run(argv, _ctx) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(USAGE);
+    return 0;
+  }
+  console.log("\n  Ideas to try with Claude:\n");
+  for (const idea of IDEAS) console.log(`    "${idea}"`);
+  console.log("\n  Paste one in, save, and watch it reload.\n");
+  return 0;
+}

package/src/commands/login.mjs

@@ -0,0 +1,107 @@
+/**
+ * `tot login` — sign the developer in to Token of Trust.
+ *
+ * Runs the MCP OAuth 2.1 PKCE loopback (the same ceremony `claude mcp add` runs):
+ * opens the browser to the MCP's authorize page, the developer signs in with their
+ * ToT identity + approves, and the loopback catches the code and exchanges it for a
+ * token cached at ~/.tot/credentials.json. Every later command (`tot checkout`,
+ * `tot submit`, …) then runs as that developer with NO re-auth.
+ *
+ * The MCP defaults to the same target `tot submit` talks to (env MCP_BASE_URL /
+ * TOT_MCP_URL, else the production MCP) so the cached token matches where it's
+ * spent — point both at qa with `--mcp https://mcp.qa.tokenoftrust.com` or the env.
+ *
+ * B3 — `--device` forces the RFC 8628 device-code flow (headless/SSH/no-browser:
+ * print a code, poll until it's approved elsewhere). It's also the automatic
+ * fallback for a bare `tot login` when there's no browser opener on this box at
+ * all (oauth.mjs's loopback flow would otherwise hang forever waiting for a
+ * callback nothing can deliver — see NoOpenerError).
+ *
+ * Dependency-free (node built-ins via oauth.mjs).
+ */
+import { loginFlow, deviceLoginFlow, NoOpenerError } from "../oauth.mjs";
+import { defaultCredentialsPath, readCredentials, writeCredentials } from "../token-store.mjs";
+import { openBrowser } from "../open.mjs";
+import { fail } from "../errors.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+function parseArgs(argv) {
+  const a = { mcp: null, device: 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 === "--device") a.device = true;
+    else if (t === "--help" || t === "-h") a.help = true;
+  }
+  return a;
+}
+
+const USAGE = `tot login — sign in to Token of Trust
+
+  tot login                 open the browser, sign in, cache your session
+  tot login --device        headless/SSH: print a code, poll until approved
+                            elsewhere (also the automatic fallback when no
+                            browser opener exists on this box)
+  tot login --mcp <url>     MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
+
+After signing in, run \`tot whoami\` to confirm, then \`tot checkout\` / \`tot submit\`.`;
+
+/**
+ * The core of `tot login`: run the OAuth ceremony (browser loopback, or the
+ * device-code flow if `device` is set or the loopback can't be reached at
+ * all) and cache the result, reusing a previously-registered client for THIS
+ * MCP so we don't re-register (and burn the DCR rate limit) on every login.
+ * Exported so `tot doctor --fix` (F2) can re-login as an auto-remediation
+ * without duplicating this.
+ * @returns {Promise<object>} the credentials written to disk.
+ */
+export async function loginAndCache(mcpUrl, env = process.env, { log = () => {}, device = false } = {}) {
+  const path = defaultCredentialsPath(env);
+  const prior = readCredentials(path);
+  const clientId = prior && prior.mcpUrl === mcpUrl ? prior.clientId : undefined;
+
+  let creds;
+  if (device) {
+    creds = await deviceLoginFlow({ mcpUrl, clientId, log });
+  } else {
+    try {
+      creds = await loginFlow({ mcpUrl, clientId, open: openBrowser, log });
+    } catch (e) {
+      if (!(e instanceof NoOpenerError)) throw e;
+      log("  no browser available here — falling back to device-code sign-in …");
+      creds = await deviceLoginFlow({ mcpUrl, clientId, log });
+    }
+  }
+  writeCredentials(path, creds);
+  return creds;
+}
+
+/** @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 mcpUrl = args.mcp || env.MCP_BASE_URL || env.TOT_MCP_URL || DEFAULT_MCP_URL;
+  console.error(`~ signing in to Token of Trust (${mcpUrl})`);
+  try {
+    await loginAndCache(mcpUrl, env, { log: (m) => console.error(m), device: args.device });
+    console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
+    console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
+    return 0;
+  } catch (e) {
+    console.error(
+      fail(
+        `sign-in didn't complete: ${e?.message || e}`,
+        args.device
+          ? "re-run `tot login --device` and approve the code."
+          : "re-run `tot login` and finish the browser sign-in (approve the request) — or try `tot login --device`.",
+      ),
+    );
+    return 1;
+  }
+}