@tokenoftrust/cli 1.4.0 → 1.5.0

package/src/commands/start.mjs

@@ -4,30 +4,30 @@
  *
  * It COMPOSES the other commands' cores in-process (no shelling out to `tot …`):
  *
- *   preflight   collectChecks()  (F — self-healing where it can be)
+ *   preflight   collectChecks() — self-healing where it can be
  *   login       establishSession()  (developer OAuth; offers inline sign-in when
- *               there's no session yet — no re-run — see tryResolveSession)
- *              (A2 — run concurrently: neither gates the other; wait on the slower)
+ *               there's no session yet — no re-run — see tryResolveSession),
+ *               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)
+ *               use --tenant, else the remembered last tenant, else choose
  *      ↓
  *   checkout ─┬─ checkoutTenant() → ./<tenant>
  *   runner   ─┘  prefetch the runner: the native renderer artifact by default
- *               (F3 — no Docker prerequisite), or the Docker registry
+ *               (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)
+ *               uses — see dev.mjs#NativeArtifactUnavailableError), run
+ *               concurrently with checkout: both just need the
+ *               session resolved above
  *      ↓
  *   dev         spawnNativeDev() or spawnDevContainer() → wait for ready →
- *               open the browser (C/D)
+ *               open the browser
  *      ↓
- *   you're live crafted ending (elapsed time printed — A3), seeded with
- *               IDEAS[0] (G3), THEN the optional "Connect Claude?" prompt: on
+ *   you're live crafted ending (elapsed time printed), seeded with
+ *               IDEAS[0], 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.
+ *               prompt — the payoff, not a pointer to go write one.
  *
  * ZERO-LOGIN FREE TASTE (--sample / no session): when the user passes --sample,
  * or has no Token of Trust session (and doesn't decline), `tot start` SKIPS
@@ -36,11 +36,11 @@
  * ends on the SAME "connect the ToT MCP for the real power" opt-in. The MCP is
  * repositioned as the upsell, not a gate. See runSampleStart + sample.mjs.
  *
- * Value-first ordering (C): the running site + browser come BEFORE any mention of
+ * Value-first ordering: 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
+ * ONE felt browser login: `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).
+ * Every failure ends with the exact next command via the shared formatter.
  *
  * Dependency-free (node:readline/promises + the cores above).
  */
@@ -67,7 +67,7 @@ import {
   activityBridgeEnv, NativeArtifactUnavailableError,
 } from "./dev.mjs";
 import { scaffoldSample, isSampleCheckout, sampleConfig, SAMPLE_DIR_NAME } from "../sample.mjs";
-import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
+import { startHeartbeatFromEnv, resolveEditor } from "../dev-heartbeat.mjs";
 import { streamDevLogs } from "../dev-logs.mjs";
 import { milestoneBanner, cockpitUrlFrom, DEVELOPER_COCKPIT } from "../banner.mjs";
 import { IDEAS } from "./ideas.mjs";
@@ -130,7 +130,7 @@ export function pickStore(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.
+ * run. 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
@@ -191,7 +191,7 @@ export async function run(argv, ctx) {
 
   const startedAt = Date.now();
 
-  // Explicit free taste: skip login/store/checkout entirely (A0 zero-login).
+  // Explicit free taste: skip login/store/checkout entirely (zero-login).
   if (decideStartMode({ sampleFlag: args.sample, hasSession: true }) === "sample") {
     return runSampleStart(args, ctx, env, startedAt);
   }
@@ -205,7 +205,7 @@ export async function run(argv, ctx) {
     const client = createMcpClient(baseUrl);
 
     // Resolve a session, tolerating a no-session / no-network condition so we can
-    // offer the free local preview instead of dead-ending (B/A0).
+    // offer the free local preview instead of dead-ending.
     const session = await tryResolveSession(client, env, args);
     if (decideStartMode({ sampleFlag: false, hasSession: !!session }) === "sample") {
       if (!(await confirmSampleFallback(args))) {
@@ -216,18 +216,18 @@ export async function run(argv, ctx) {
       return await runSampleStart(args, ctx, env, startedAt);
     }
 
-    // Authenticated path. Preflight (F) now that we know we're taking it — the
+    // Authenticated path. Preflight now that we know we're taking it — the
     // local machine checks (node/git/Docker) that the authed loop needs.
     await preflight(ctx, env);
     console.log(`  ✓ signed in as ${describeIdentity(session)} via ${mcpOrigin(baseUrl)}`);
 
     // Resolve the activity-bridge credential + the hosted Developer Cockpit URL
     // ONCE, up front — both the pre-pick "keep the cockpit alive" heartbeat below
-    // (b2) and the post-boot heartbeat + milestone banners (u2) use them.
+    // and the post-boot heartbeat + milestone banners use them.
     const bridgeEnv = activityBridgeEnv(env);
     const cockpitUrl = cockpitUrlFrom(bridgeEnv.TOT_DEV_ACTIVITY_URL);
 
-    // b2 — a >1-store identity blocks on the interactive store picker below, and
+    // A >1-store identity blocks on the interactive store picker below, and
     // (before this) the hosted cockpit got NO heartbeat until the dev server
     // spawned much later, so a multi-store dev's cockpit sat on Step 1 forever
     // while the terminal quietly waited for a number. Start beating NOW (no local
@@ -236,7 +236,7 @@ export async function run(argv, ctx) {
     // the live localhost URL) takes over once we have it.
     const stopEarlyHeartbeat = startHeartbeatFromEnv(bridgeEnv, {});
 
-    // 3. store — auto-pick, use --tenant, use the remembered one, or choose (A4).
+    // 3. store — auto-pick, use --tenant, use the remembered one, or choose.
     // Keep the raw client_list so a tool ERROR (unauthenticated / not-entitled) is
     // surfaced with who + where, not collapsed to an empty list (fb-...f45zg9).
     let tenant;
@@ -254,31 +254,31 @@ export async function run(argv, ctx) {
     }
 
     // 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
+    // OVERLAPPED with prefetching the runner: the native artifact by
+    // default (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);
     // Resolve a free port so the URL we open/poll/print matches what the runner
     // binds (Vite strictPort is off → a busy port would drift). No-op if free.
-    const devArgs = {
+    const devArgs = /** @type {any} */ ({
       image: null, port: String(await firstFreePort(Number(args.port || 4321))), mcp: args.mcp,
       noLogin: false, noOpen: args.noOpen, docker: args.docker,
-    };
-    const runtime = { useDocker: args.docker, runnerDir: null };
+    });
+    const runtime = /** @type {{ useDocker: boolean, runnerDir: any }} */ ({ useDocker: args.docker, runnerDir: null });
     await Promise.all([
       ensureCheckout(client, tenant, dir, env),
       prefetchRuntime(client, devArgs, env, runtime, ctx),
     ]);
 
-    // u3 — say EXACTLY where the code landed + THE one next step, so a freshly
+    // Say EXACTLY where the code landed + THE one next step, so a freshly
     // checked-out dev is never left wondering what to open. Absolute path (works
     // from any directory) and a single, unambiguous action.
     printCheckoutLanding(dir, cockpitUrl);
 
-    // 5. dev — native by default (F3), Docker on --docker or the fallback
-    // above; wait for the server, open the browser (C/D).
+    // 5. dev — native by default, Docker on --docker or the fallback
+    // above; wait for the server, open the browser.
     const ctxDev = detectContext(dir);
     let url, handle;
     if (runtime.useDocker) {
@@ -292,11 +292,11 @@ export async function run(argv, ctx) {
       handle = spawnNativeDev(runtime.runnerDir, dir, devArgs.port, { stdio: "piped", env: bridgeEnv });
     }
 
-    // Heartbeat the hosted cockpit (G1) with the CLI version + this live localhost
+    // Heartbeat the hosted cockpit with the CLI version + this live localhost
     // URL for the life of the run — CLI-side, using the cached bridge credential
     // (no-op when none is cached). The runner keeps reporting file-saves itself.
     // Hand off from the pre-pick (URL-less) beat to this URL-bearing one so the
-    // cockpit's live local link lights up exactly when the server is up (b2).
+    // cockpit's live local link lights up exactly when the server is up.
     stopEarlyHeartbeat();
     const stopHeartbeat = startHeartbeatFromEnv(bridgeEnv, { url, cwd: dir });
     handle.done.finally(() => stopHeartbeat());
@@ -314,11 +314,11 @@ export async function run(argv, ctx) {
       console.log("  ✓ opened your browser");
     }
 
-    // 6. you're live (G) — land on the store ROOT (not /dev), print elapsed time
-    // (A3) so the "instant" claim is measured. The "Connect Claude" step is
+    // 6. you're live — land on the store ROOT (not /dev), print elapsed time
+    // so the "instant" claim is measured. The "Connect Claude" step is
     // intentionally removed for now — a blocking prompt here meant Ctrl-C'ing it
     // tore down the dev server; revisit AI-connect as a non-blocking step later.
-    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt), cockpitUrl);
+    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt), cockpitUrl, dir);
 
     // 7. hand the terminal to the running dev server until Ctrl-C.
     console.log("\n  Watching your store — edit content/home.html + save. Ctrl-C to stop.\n");
@@ -463,10 +463,10 @@ async function confirmSampleFallback(args) {
 }
 
 /**
- * Self-healing preflight (F): run the readiness checks; a blocking failure
- * ends with the next command. Docker is informational-only here (F3: native
+ * Self-healing preflight: run the readiness checks; a blocking failure
+ * ends with the next command. Docker is informational-only here — native
  * is the default runtime, so Docker not running doesn't block `tot start`
- * anymore) — its own readiness is handled lazily in prefetchDockerLogin(),
+ * anymore — its own readiness is handled lazily in prefetchDockerLogin(),
  * only when the run actually needs it (--docker or the native fallback).
  */
 async function preflight(ctx, env) {
@@ -482,8 +482,8 @@ async function preflight(ctx, env) {
 }
 
 /**
- * Prefetch the runner (C1) so it's overlapped with checkout instead of paid
- * for serially afterward: the native renderer artifact by default (F3 — no
+ * Prefetch the runner so it's overlapped with checkout instead of paid
+ * for serially afterward: the native renderer artifact by default (no
  * Docker prerequisite), or the Docker registry pull credential on --docker.
  *
  * On a native (entitled-artifact) fetch failure the runtime stays NATIVE: it
@@ -524,8 +524,8 @@ async function prefetchRuntime(client, devArgs, env, runtime, ctx) {
 
 /**
  * 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
+ * already-authenticated client) plus a best-effort Docker auto-start
+ * (self-healing) so buildContainerPlan doesn't have to hard-fail on a
  * Docker Desktop that just needs a nudge.
  */
 async function prefetchDockerLogin(client, devArgs, env) {
@@ -570,7 +570,7 @@ function noStoresError({ session, baseUrl, listErr, list = null }) {
       { next: "run `tot whoami` to check your session, or `tot login` again — then re-run `tot start`" },
     );
   }
-  // Status-aware (card c2): an UNLINKED identity is pointed at `tot link`, not the
+  // Status-aware: an UNLINKED identity is pointed at `tot link`, not the
   // misleading "ask for a store invite" copy; the genuine zero-grants case keeps it.
   const g = noStoresGuidance(list);
   return new CliError(`signed in as ${who} via ${origin}, but ${g.headline}`, { next: g.next });
@@ -578,9 +578,13 @@ function noStoresError({ session, baseUrl, listErr, list = null }) {
 
 /**
  * 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
+ * the remembered last tenant — then remember whatever was decided so the
  * next bare `tot start` doesn't have to ask again.
  */
+/**
+ * @param {any} stores @param {any} args @param {any} env @param {string} baseUrl
+ * @param {{ session?: any, listErr?: string|null, list?: any }} [opts]
+ */
 async function resolveTenant(stores, args, env, baseUrl, { session = null, listErr = null, list = null } = {}) {
   const lastTenantPath = defaultLastTenantPath(env);
   const pick = pickTenant(stores, {
@@ -603,22 +607,23 @@ async function resolveTenant(stores, args, env, baseUrl, { session = null, listE
   } else {
     // Many stores, nothing remembered — choose. Non-interactive (no TTY /
     // --yes without a name) can't guess.
+    const many = /** @type {any} */ (pick);
     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(", ")})`,
+        next: `tot start --tenant <tenant>  (one of: ${many.stores.map((s) => s.id).join(", ")})`,
       });
     }
     // Loud + unmissable: a >1-store dev is often looking at their browser
     // cockpit (which is waiting on this pick), so make the terminal shout for
-    // their attention rather than sitting as a quiet one-liner (b2).
+    // their attention rather than sitting as a quiet one-liner.
     console.log("");
     console.log("  ⚑ ACTION NEEDED IN YOUR TERMINAL — you can build on several stores.");
     console.log("    Pick one here to light up your cockpit:\n");
-    pick.stores.forEach((s, i) => console.log(`    ${i + 1}. ${s.id}${s.name ? `  — ${s.name}` : ""}`));
+    many.stores.forEach((s, i) => console.log(`    ${i + 1}. ${s.id}${s.name ? `  — ${s.name}` : ""}`));
     console.log("");
-    const idx = await promptChoice(pick.stores.length);
+    const idx = await promptChoice(many.stores.length);
     console.log("");
-    tenant = pick.stores[idx].id;
+    tenant = many.stores[idx].id;
   }
 
   writeLastTenant(lastTenantPath, { mcpUrl: baseUrl, tenant });
@@ -668,7 +673,7 @@ async function waitForBoot(url, handle) {
 
 /**
  * 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
+ * ending — measure, don't just claim, "instant". Pure + exported so it's
  * unit-tested without any I/O.
  * @param {number} ms
  * @returns {string|null}
@@ -679,12 +684,13 @@ export function formatElapsed(ms) {
 }
 
 /**
- * u3 — after checkout, tell the developer EXACTLY where their code landed and
+ * After checkout, tell the developer EXACTLY where their code landed and
  * THE single next step. `dir` is absolute (from resolve(cwd, tenant)) so the
  * "open this" path works no matter what directory they're in. When we know the
  * Developer Cockpit URL, the one next step is framed as "edit a line → see it in
  * your cockpit"; otherwise it's the same edit-to-see-it-reload action.
  */
+/** @param {string} dir @param {string|null} [cockpitUrl] */
 function printCheckoutLanding(dir, cockpitUrl = null) {
   console.log("");
   console.log(`  📁 Your store code is at:  ${dir}`);
@@ -693,11 +699,38 @@ function printCheckoutLanding(dir, cockpitUrl = null) {
   console.log(`     content/home.html — you'll see it reflected in ${where}.`);
 }
 
+/**
+ * OS/editor-aware suggestions for opening the checkout, shown once at the
+ * "you're live" moment. $VISUAL/$EDITOR (same signal the cockpit's "open this
+ * file" hint uses — see dev-heartbeat.mjs#resolveEditor) wins when set;
+ * otherwise a short per-platform shortlist of common editor launch commands.
+ * Deliberately NOT probed against PATH — a spawnSync per candidate would add
+ * real latency to the crafted "aha" ending for the common case (nothing set),
+ * so this is a labeled suggestion list, not a detection result.
+ */
+function editorOpenLines(dir, { platform = process.platform, env = process.env } = {}) {
+  const configured = resolveEditor(env);
+  if (configured) return [`${configured} ${dir}`];
+  if (platform === "darwin") {
+    return [`code ${dir}      (VS Code, if installed)`, `cursor ${dir}    (Cursor, if installed)`, `open ${dir}      (Finder)`];
+  }
+  if (platform === "win32") {
+    return [`code ${dir}      (VS Code, if installed)`, `explorer ${dir}  (File Explorer)`];
+  }
+  return [`code ${dir}      (VS Code, if installed)`, `cursor ${dir}    (Cursor, if installed)`, `xdg-open ${dir}  (file manager)`];
+}
+
 /** The crafted "you're live" ending — a PROMINENT milestone banner (u2) that,
  * when we hold a Developer Cockpit URL, explicitly sends the developer BACK to
- * their cockpit as the next place to look; then the AI-wow (G), seeded with
- * IDEAS[0] (G2/G3 — one prompt list shared with `tot ideas`, no drift). */
-function printLiveEnding(tenant, url, elapsed, cockpitUrl = null) {
+ * their cockpit as the next place to look. Then: an OS-suited "open this in
+ * an editor" suggestion, and the four-pane layout tip (this terminal, cockpit,
+ * local preview, editor) so a build problem, a reload, and the code are never
+ * more than a glance apart. */
+/**
+ * @param {string} tenant @param {string} url @param {string|null} elapsed
+ * @param {string|null} [cockpitUrl] @param {string|null} [dir]
+ */
+function printLiveEnding(tenant, url, elapsed, cockpitUrl = null, dir = null) {
   const lines = [
     `✨  You're live.${elapsed ? `  (${elapsed})` : ""}`,
     `    ${url}`,
@@ -711,10 +744,19 @@ function printLiveEnding(tenant, url, elapsed, cockpitUrl = null) {
   console.log(milestoneBanner(lines));
   console.log("  " + versionStamp("native"));
   console.log("");
-  console.log("  Now try, in Claude:");
-  console.log(`     "${IDEAS[0]}"`);
+  if (dir) {
+    console.log("  Open your project in an editor (an AI coding agent like Claude works too —");
+    console.log("  same idea, different hands on the keyboard):");
+    for (const line of editorOpenLines(dir)) console.log(`     ${line}`);
+    console.log("");
+  }
+  console.log("  Keep THIS terminal open — it's your live build/status feed, the fastest way to");
+  console.log("  see a problem the moment it happens. Need the command line for something else?");
+  console.log("  Open a NEW terminal window rather than closing this one.");
   console.log("");
-  console.log("  More ideas: tot ideas");
+  console.log("  Best view: arrange this terminal, your Developer Cockpit, the local preview,");
+  console.log("  and your editor so you can see all four at once — site, cockpit, build status,");
+  console.log("  and code, together.");
   console.log("");
 }
 
@@ -738,7 +780,7 @@ function printSampleLiveEnding(url, elapsed) {
 }
 
 /**
- * Offer + wire Claude (G2): `claude mcp add`, then — the payoff, not just a
+ * Offer + wire Claude: `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.
  */