mesa-ai-cto 0.1.0 → 0.2.0

package/dist/cli.js

@@ -7,7 +7,7 @@ import { parseArgs } from "./lib/args.js";
  * Returns an exit code rather than calling `process.exit`, so every path through the CLI
  * is reachable from a test without tearing down the test runner.
  */
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.0";
 const HELP = `
   mesa-ai-cto — scaffold a project from your AI CTO plan
 
@@ -19,6 +19,8 @@ const HELP = `
     --stack=<id>      pick the kit when a tier has more than one
     --force           scaffold into a folder that already has files
     --no-install      skip npm install
+    --token=<t>       fetch your plan into plan.md
+    --api=<url>       API base (the dashboard fills this in)
     --session=<id>    record which plan this came from
 
   Coming next
@@ -71,6 +73,8 @@ export async function runCli(argv) {
              */
             ...(typeof flags.stack === "string" ? { stack: flags.stack } : {}),
             ...(typeof flags.session === "string" ? { session: flags.session } : {}),
+            ...(typeof flags.token === "string" ? { token: flags.token } : {}),
+            ...(typeof flags.api === "string" ? { api: flags.api } : {}),
         });
         process.stderr.write(output + "\n");
         return code;

package/dist/commands/init.js

@@ -1,14 +1,37 @@
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
+import { runDoctor } from "./doctor.js";
 import { createExec } from "../lib/exec.js";
+import { fetchPlan, renderPlanMarkdown } from "../lib/plan.js";
+import { reportProgress, writeLocalState } from "../lib/progress.js";
+import { VERSION } from "../cli.js";
 import { defaultStack, kitId, templatesRoot } from "../lib/templates.js";
+/**
+ * Things that may be present without the folder counting as occupied.
+ *
+ * None of them is the founder's work:
+ *
+ *   - `.git` because initialising a repo and then scaffolding into it is a normal order of
+ *     operations.
+ *   - `node_modules` and the lockfiles because they are build output. The case that forced this
+ *     was a founder who deleted a project to start over: Windows left an empty `node_modules`
+ *     behind (it routinely fails to remove one, being deep and often locked) along with the
+ *     lockfile, and the CLI then refused to scaffold into what was, to any human reading it, an
+ *     empty folder. Being told to pass --force to overwrite nothing is a bad answer.
+ */
+const IGNORABLE = new Set([
+    ".git",
+    "node_modules",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    ".DS_Store",
+]);
 /** Anything already in the target that means "this is not an empty folder". */
 function isOccupied(dir) {
     if (!existsSync(dir))
         return false;
-    // `.git` alone is fine: initialising a repo and then scaffolding into it is a normal order of
-    // operations, and refusing it would send people to --force for no reason.
-    return readdirSync(dir).some((entry) => entry !== ".git");
+    return readdirSync(dir).some((entry) => !IGNORABLE.has(entry));
 }
 /*
  * The template's package.json is named for the boilerplate it came from. Left alone, every
@@ -121,6 +144,38 @@ export async function runInit(options) {
         cli: "mesa-ai-cto",
     }, null, 2)}\n`, "utf8");
     lines.push("  ✓ mesa.json written");
+    /*
+     * The plan, if we were given a token to read it with.
+     *
+     * Non-fatal by design. The tree on disk is already correct and useful; an expired token or a
+     * laptop on a bad connection is worth a line of explanation, not a failed scaffold. What it
+     * must never do is write a plan.md it could not actually fetch: an agent treats that file as
+     * authoritative, so a wrong one is worse than none at all.
+     */
+    let local = null;
+    if (options.token !== undefined) {
+        const fetched = await fetchPlan(options.token, {
+            name: options.name,
+            kit,
+            tier: options.tier,
+            stack,
+            cliVersion: VERSION,
+        }, options.api !== undefined ? { api: options.api } : {});
+        if (fetched.kind === "ok") {
+            writeFileSync(join(target, "plan.md"), renderPlanMarkdown(fetched.plan), "utf8");
+            lines.push("  ✓ plan.md written from your session");
+            // The report key arrives with the plan and is written straight to disk, gitignored.
+            local = { projectId: fetched.projectId, reportKey: fetched.reportKey };
+            writeLocalState(target, local);
+            lines.push("  ✓ progress linked to your dashboard");
+        }
+        else {
+            lines.push(`  ! plan.md not written: ${fetched.reason}`);
+            lines.push("      Copy the prompt from your dashboard instead.");
+        }
+    }
+    /** null = never attempted, so the step is PENDING rather than a claim either way. */
+    let depsInstalled = null;
     if (options.install === false) {
         lines.push("  · dependencies not installed (--no-install)");
     }
@@ -131,7 +186,22 @@ export async function runInit(options) {
          * fresh project routinely runs past a minute, and killing it at five seconds would report a
          * timeout for a command that was working perfectly.
          */
-        const outcome = await exec("npm", ["install"], { cwd: target, timeoutMs: 10 * 60_000 });
+        /*
+         * Announced BEFORE it starts, and streamed while it runs.
+         *
+         * This step takes one to three minutes on a cold cache. Run silently it looks like the CLI
+         * has hung, and the natural response is to kill it — leaving a scaffolded project with no
+         * dependencies and no obvious way to tell that is what happened.
+         */
+        process.stderr.write("\n  Installing dependencies. This takes a minute or two.\n\n");
+        const outcome = await exec("npm", ["install"], {
+            cwd: target,
+            // The default is tuned for `--version` probes. A cold install routinely runs past a
+            // minute, and killing it at five seconds would report a timeout for a working command.
+            timeoutMs: 10 * 60_000,
+            stream: true,
+        });
+        depsInstalled = outcome.kind === "ok";
         if (outcome.kind === "ok") {
             lines.push("  ✓ dependencies installed");
         }
@@ -147,14 +217,51 @@ export async function runInit(options) {
             lines.push(`      cd ${basename(target)} && npm install`);
         }
     }
+    /*
+     * Report what this run actually established.
+     *
+     * VERIFIED throughout, because every one of these is something the CLI did and observed
+     * rather than something a person claimed. `journey.installed` is a fact about the files on
+     * disk; `journey.dependencies` reflects the npm exit code we just read.
+     *
+     * Fire and forget: a failed report must never fail a good scaffold, so the outcome is a
+     * single line of output and nothing more.
+     */
+    if (local !== null) {
+        const steps = [
+            { stepId: "journey.installed", state: "DONE", source: "VERIFIED", detail: `${kit} scaffolded` },
+            {
+                stepId: "journey.dependencies",
+                state: depsInstalled === null ? "PENDING" : depsInstalled ? "DONE" : "FAILED",
+                source: "VERIFIED",
+            },
+        ];
+        const sent = await reportProgress(local, steps, VERSION, options.api !== undefined ? { api: options.api } : {});
+        if (!sent)
+            lines.push("  · progress not reported (the dashboard will catch up next run)");
+    }
+    /*
+     * The machine report, after the scaffold rather than before it.
+     *
+     * A founder standing in a fresh project wants to know what still needs configuring - git
+     * identity, a GitHub login, a Vercel login - and finding that out by hitting the failure
+     * later is the expensive way. Running it here means the answer arrives with the project.
+     *
+     * Deliberately NOT a gate. Everything on disk is already correct, and refusing to scaffold
+     * because `gh` is not logged in would block work that does not need `gh` for hours yet.
+     * The exit code stays 0 and the report is information.
+     */
+    const doctor = await runDoctor({ json: false });
+    lines.push("");
+    lines.push(doctor.output.trimEnd());
     lines.push("");
     lines.push("  Next:");
     lines.push(`    cd ${basename(target)}`);
     lines.push("    Read INITIALIZE.md, then hand it to your coding agent.");
-    if (options.session !== undefined) {
+    if (options.token === undefined && options.session !== undefined) {
         // Said plainly rather than silently omitted: the dashboard's command implies the plan
         // travels with it, and today it does not.
-        lines.push("    Paste your plan from the dashboard — it is not fetched yet.");
+        lines.push("    Copy the prompt from your dashboard for the plan.");
     }
     lines.push("");
     return { code: 0, output: ["", ...lines].join("\n") };

package/dist/lib/exec.js

@@ -69,8 +69,16 @@ export function createExec(deps = {}) {
         }
         let stdout = "";
         let stderr = "";
-        child.stdout?.on("data", (d) => (stdout += d.toString()));
-        child.stderr?.on("data", (d) => (stderr += d.toString()));
+        if (opts.stream === true) {
+            // Everything to stderr, including the child's stdout: this CLI keeps stdout clean for
+            // `--json` payloads, and npm's chatter is commentary rather than output.
+            child.stdout?.pipe(process.stderr);
+            child.stderr?.pipe(process.stderr);
+        }
+        else {
+            child.stdout?.on("data", (d) => (stdout += d.toString()));
+            child.stderr?.on("data", (d) => (stderr += d.toString()));
+        }
         timer = setTimeout(() => {
             child.kill();
             finish({ kind: "timeout" });

package/dist/lib/plan.js

@@ -0,0 +1,123 @@
+/**
+ * Fetching the plan, and writing it as `plan.md`.
+ *
+ * The scaffold gives an agent the stack. This gives it the judgement: what to build, and — far
+ * more importantly — what the founder was talked out of. Without it an agent works from the
+ * project name and rebuilds the whole original wishlist.
+ */
+/**
+ * Where the API lives.
+ *
+ * `MESA_API_URL` overrides it, which is what makes this testable against a local backend and
+ * survivable if the host ever moves without a CLI release. The default is the production API;
+ * a founder should never have to set an environment variable to run the command their dashboard
+ * printed.
+ */
+export function apiBase(env = process.env, override) {
+    return (override ?? env.MESA_API_URL ?? DEFAULT_API).replace(/\/+$/, "");
+}
+/**
+ * Only used when nothing else says otherwise.
+ *
+ * A hardcoded host in a published CLI is a hostage to fortune: it is wrong the moment the API
+ * moves, and every founder running an old version keeps hitting the old address. `--api` exists
+ * so the dashboard can state the answer in the command it renders, which means the CLI is
+ * correct wherever the backend happens to live, including a laptop during development.
+ */
+const DEFAULT_API = "https://api.mesa-ai-cto.com/api/v1";
+/**
+ * Read the plan behind an install token.
+ *
+ * Never throws. A plan that cannot be fetched must not fail the scaffold: the project on disk
+ * is already correct, and an expired token or an offline laptop is a reason to print a line,
+ * not to delete a working tree.
+ */
+export async function fetchPlan(token, facts, deps = {}) {
+    const doFetch = deps.fetch ?? globalThis.fetch;
+    const query = new URLSearchParams({
+        token,
+        name: facts.name,
+        kit: facts.kit,
+        tier: String(facts.tier),
+        stack: facts.stack,
+        cliVersion: facts.cliVersion,
+    });
+    const url = `${apiBase(deps.env, deps.api)}/chat/install/plan?${query.toString()}`;
+    try {
+        const response = await doFetch(url, { headers: { accept: "application/json" } });
+        const body = (await response.json().catch(() => null));
+        if (!response.ok) {
+            return { kind: "failed", reason: body?.error?.message ?? `the server said ${response.status}` };
+        }
+        const { plan, projectId, reportKey } = body?.data ?? {};
+        if (!plan || !projectId || !reportKey) {
+            return { kind: "failed", reason: "the response was incomplete" };
+        }
+        return { kind: "ok", plan, projectId, reportKey };
+    }
+    catch {
+        return { kind: "failed", reason: "the API could not be reached" };
+    }
+}
+/** Defensive throughout: the plan's shape lives in a model prompt, so any field may be absent. */
+function list(items) {
+    if (!Array.isArray(items))
+        return [];
+    return items
+        .map((item) => {
+        const f = item;
+        if (typeof f?.feature !== "string")
+            return null;
+        return typeof f.why === "string" ? `- **${f.feature}** — ${f.why}` : `- **${f.feature}**`;
+    })
+        .filter((line) => line !== null);
+}
+function section(heading, lines) {
+    return lines.length > 0 ? [`## ${heading}`, "", ...lines, ""] : [];
+}
+function str(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+/**
+ * The plan as markdown, for an agent to read and a founder to check.
+ *
+ * Markdown rather than the raw JSON: this file's audience is a coding agent reading a repo, and
+ * every one of them handles markdown natively. Dropping a JSON blob in the project root would
+ * be a file the founder cannot read and the agent has to parse.
+ */
+export function renderPlanMarkdown(plan) {
+    const out = [];
+    out.push(`# ${str(plan.title) ?? "Build plan"}`, "");
+    const summary = [
+        str(plan.businessSummary),
+        str(plan.coreOutcome) ? `**The one thing it must do:** ${str(plan.coreOutcome)}` : null,
+    ].filter((l) => l !== null);
+    if (summary.length > 0)
+        out.push(...summary, "");
+    const facts = [
+        str(plan.stack) ? `- **Stack:** ${str(plan.stack)} (already scaffolded)` : null,
+        typeof plan.tier === "number" ? `- **Tier:** ${plan.tier}` : null,
+        str(plan.formFactor) ? `- **Form factor:** ${str(plan.formFactor)}` : null,
+        typeof plan.buildEstimateDays === "number"
+            ? `- **Budget:** about ${plan.buildEstimateDays} day(s) of work`
+            : null,
+        str(plan.stackReason) ? `- **Why this stack:** ${str(plan.stackReason)}` : null,
+    ].filter((l) => l !== null);
+    out.push(...section("At a glance", facts));
+    out.push(...section("Build this — and only this", list(plan.p0)));
+    /*
+     * One "do not build" section, not a roadmap.
+     *
+     * Splitting these into "next" and "later" invites an agent to make a helpful start on the
+     * nearest one, which is the exact outcome the founder spent a conversation preventing.
+     */
+    const notNow = [...list(plan.p1), ...list(plan.p2)];
+    out.push(...section("Do not build these yet", notNow.length > 0
+        ? ["These were deliberately cut. Adding them back is a mistake, not a bonus.", "", ...notNow]
+        : []));
+    const milestone = str(plan.firstMilestone);
+    if (milestone !== null)
+        out.push(...section("First milestone", [milestone]));
+    out.push("---", "", "_Written by mesa-ai-cto from your AI CTO session. Re-run the command to refresh it._", "");
+    return out.join("\n").replace(/\n{3,}/g, "\n\n");
+}

package/dist/lib/progress.js

@@ -0,0 +1,70 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { apiBase } from "./plan.js";
+const DIR = ".mesa";
+const FILE = "local.json";
+/**
+ * Write the machine state, and keep it out of git.
+ *
+ * The report key is a long-lived bearer credential. Committed, it is one `git push` from being
+ * public — so `.mesa/` goes into `.gitignore` in the same breath that creates it, not as a
+ * separate step someone can forget.
+ *
+ * `.mesa/` is the one hidden directory in an otherwise recognisable project, and that is
+ * deliberate: everything a founder should read is visible at the root, and this is the only
+ * thing that is purely machine state.
+ */
+export function writeLocalState(projectRoot, state) {
+    const dir = join(projectRoot, DIR);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, FILE), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    const gitignore = join(projectRoot, ".gitignore");
+    const existing = existsSync(gitignore) ? readFileSync(gitignore, "utf8") : "";
+    // Matched on a line boundary: a bare `includes(".mesa")` would be satisfied by an unrelated
+    // path that merely contains the string.
+    if (!/^\.mesa\/?\s*$/m.test(existing)) {
+        const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+        appendFileSync(gitignore, `${prefix}\n# Machine state for mesa-ai-cto (holds a report key)\n.mesa/\n`, "utf8");
+    }
+}
+export function readLocalState(projectRoot) {
+    const file = join(projectRoot, DIR, FILE);
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (typeof parsed.projectId !== "string" || typeof parsed.reportKey !== "string")
+            return null;
+        return { projectId: parsed.projectId, reportKey: parsed.reportKey };
+    }
+    catch {
+        // A corrupt state file is not worth failing over: the project still works, it just stops
+        // reporting until the founder reruns the command.
+        return null;
+    }
+}
+/**
+ * Post steps. Never throws.
+ *
+ * Progress reporting is telemetry about a build, not part of it. A founder on a plane must still
+ * get a working scaffold, so every failure here is swallowed and reported as a boolean the
+ * caller can mention in passing.
+ */
+export async function reportProgress(state, steps, cliVersion, deps = {}) {
+    const doFetch = deps.fetch ?? globalThis.fetch;
+    try {
+        const response = await doFetch(`${apiBase(deps.env, deps.api)}/projects/progress`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                // The report key is the credential. It names one project and can do nothing else.
+                authorization: `Bearer ${state.reportKey}`,
+            },
+            body: JSON.stringify({ cliVersion, steps }),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mesa-ai-cto",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Check your machine and scaffold a production-grade project from an AI CTO plan.",
   "keywords": [
     "scaffold",