projectinator 0.3.0 → 0.3.1

package/README.md

@@ -7,7 +7,7 @@
 [![npm](https://img.shields.io/npm/v/projectinator.svg?color=e0a72d&label=npm)](https://www.npmjs.com/package/projectinator)
 ![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
 ![node](https://img.shields.io/badge/node-%E2%89%A522.19-brightgreen.svg)
-![tests: 181 passing](https://img.shields.io/badge/tests-181%20passing-brightgreen.svg)
+![tests: 187 passing](https://img.shields.io/badge/tests-187%20passing-brightgreen.svg)
 ![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg)
 ![built on Pi](https://img.shields.io/badge/built%20on-Pi%20agent%20harness-e0a72d.svg)
 
@@ -30,6 +30,8 @@ npx projectinator                 # run without installing
 npm install -g projectinator      # then just: projectinator
 ```
 
+`projectinator --help` / `--version` work without opening the app; `projectinator doctor` checks your setup.
+
 > **It's a CLI, not a library.** `npm install projectinator` (without `-g`) only drops it into a
 > project's `node_modules` — it won't create a runnable command. Use `npx projectinator` or
 > `npm install -g projectinator`. (If `-g` installs but the command isn't found, npm's global
@@ -120,16 +122,32 @@ Real, unedited output from a full build, kept in [`examples/`](examples/):
 
 ## CLI (same engine, for scripting/CI)
 
+Everything below uses the same workspace as the cockpit, so headless builds show up in the app.
+
 ```bash
-npm start                                         # the cockpit (the normal way to use it)
-npm run build -- --live --mini                    # cheap end-to-end proof (~$0.10)
-npm run build -- --live --lock anthropic "idea"   # full pipeline on one provider
-npm run build -- --live --mini --resume           # resume a halted/finished build (skips done tasks)
-npm run build -- --live --mini --task-cap 0.5 --task-timeout 5   # per-task limits (USD / minutes)
+projectinator doctor                                  # Node, keys, Chromium, Pi catalog, git
+projectinator build "a tip calculator" --dry-run      # plan + estimate only (one PM call)
+projectinator build "a tip calculator" --yes          # build without the confirmation prompt
+projectinator build "…" --json --budget 2 --provider anthropic   # NDJSON events; cap; lock provider
+projectinator build "…" --task-cap 0.5 --task-timeout 5           # per-task limits (USD / minutes)
+projectinator projects                                # past builds, status, cost
+projectinator models                                  # the roster as it will run, with prices
+```
+
+Exit codes: `0` ok · `1` environment problem · `2` bad usage · `3` build halted (resume it in the app).
+
+<details>
+<summary>Developer scripts (from a clone)</summary>
+
+```bash
+npm start                                         # the cockpit
+npm run build -- --live --mini                    # fixed 4-task build, cheap end-to-end proof (~$0.10)
+npm run build -- --live --mini --resume           # resume a halted run
 npm run bakeoff -- --capability design "Design a pricing page"   # model bake-off
-npm test                                          # 181 tests
+npm test                                          # 187 tests
 npm run typecheck
 ```
+</details>
 
 ## Configuration & data
 

package/bin/projectinator.mjs

@@ -2,14 +2,52 @@
 // Launcher for `projectinator` / `npx github:smanookian/projectinator`.
 // Runs the Ink TUI (TypeScript) through tsx — no build step, no compiled dist.
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
 const entry = join(root, "src", "tui.tsx");
 
+const args = process.argv.slice(2);
+const { version } = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+
+if (args.includes("--version") || args.includes("-v")) {
+  console.log(version);
+  process.exit(0);
+}
+if (args.includes("--help") || args.includes("-h") || args[0] === "help") {
+  console.log(`projectinator ${version} — your AI build team in the terminal
+
+Usage
+  projectinator                        open the cockpit (TUI)
+  projectinator doctor                 check Node, API keys, Chromium, Pi catalog, git
+  projectinator build "<idea>" [...]   plan + build headless (--dry-run, --yes, --json,
+                                       --budget, --provider, --concurrency, --task-cap, --task-timeout)
+  projectinator projects               list past builds with status and cost
+  projectinator models                 the roster as it will run, with prices
+  projectinator --version | --help
+
+Setup
+  Inside the app: Settings → API keys (Anthropic, OpenAI, Gemini, OpenRouter).
+  Keys live in ~/.projectinator/config.json (chmod 0600).
+  Optional: npx playwright install chromium  → lets the tester run the app headless.
+
+Exit codes: 0 ok · 1 environment problem · 2 bad usage · 3 build halted
+Docs: https://github.com/smanookian/projectinator#readme`);
+  process.exit(0);
+}
+
+const COMMANDS = new Set(["doctor", "build", "projects", "models"]);
+if (args.length && !COMMANDS.has(args[0])) {
+  console.error(`projectinator: unknown ${args[0].startsWith("-") ? "option" : "command"} "${args[0]}". Try --help.`);
+  process.exit(2);
+}
+
 // `node --import tsx <entry>` registers tsx's loader, then runs the TS entry.
-const res = spawnSync(process.execPath, ["--import", "tsx", entry], {
+// No command → the TUI; a command → the headless CLI with the remaining args.
+const target = args.length ? join(root, "src", "cli.ts") : entry;
+const res = spawnSync(process.execPath, ["--import", "tsx", target, ...args], {
   stdio: "inherit",
   cwd: root,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectinator",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Your AI build team in the terminal — hand it an app idea, a PM model plans a Scrum backlog, and the best model per role designs, codes, and tests it into working files. Bring your own API key.",
   "type": "module",
   "private": false,

package/src/cli.ts

@@ -0,0 +1,263 @@
+// Headless CLI — `projectinator <command>`. Same engine as the cockpit (engine.ts),
+// same workspace root, so builds started here show up in the TUI's project list.
+//
+//   doctor                 check Node, keys, Chromium, Pi catalog, git
+//   build "<idea>" [...]   plan + build without the TUI
+//   projects               list past builds
+//   models                 the roster as it will actually run, with prices
+//
+// The launcher (bin/projectinator.mjs) handles --version/--help itself and only
+// spawns this file for a real command, so those stay instant.
+
+import { createInterface } from "node:readline";
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { OrchestratorEvent } from "./orchestrator.js";
+import type { Provider } from "./types.js";
+import { MODELS, getModel } from "./models.js";
+import { REGISTRY } from "./registry.js";
+import { piRuntime, resolvePiModel } from "./executor.js";
+import { chromiumAvailable, CHROMIUM_INSTALL_HINT } from "./preview.js";
+import { applyKeysToEnv, getPrefs, loadConfig, ENV_VAR } from "./tui/config.js";
+import {
+  availableProviders,
+  effectiveRoster,
+  listProjects,
+  planBuild,
+  startBuild,
+  PROVIDER_LABEL,
+} from "./tui/engine.js";
+
+const NODE_MIN = "22.19.0";
+const money = (n: number) => `$${n.toFixed(2)}`;
+
+// ---- tiny argv parser: `--flag value`, `--flag=value`, `--bool`, positionals ----
+
+interface Argv {
+  positional: string[];
+  flags: Record<string, string | true>;
+}
+
+export function parseArgv(args: string[]): Argv {
+  const out: Argv = { positional: [], flags: {} };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (!a.startsWith("--")) { out.positional.push(a); continue; }
+    const eq = a.indexOf("=");
+    if (eq > 0) { out.flags[a.slice(2, eq)] = a.slice(eq + 1); continue; }
+    const next = args[i + 1];
+    if (next !== undefined && !next.startsWith("--")) { out.flags[a.slice(2)] = next; i++; }
+    else out.flags[a.slice(2)] = true;
+  }
+  return out;
+}
+
+function num(v: string | true | undefined, fallback: number): number {
+  if (v === undefined || v === true) return fallback;
+  const n = parseFloat(v);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+export function semverGte(a: string, b: string): boolean {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true;
+    if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false;
+  }
+  return true;
+}
+
+// ---- doctor ----
+
+type Check = { label: string; ok: boolean; detail: string; fatal?: boolean };
+
+async function doctor(): Promise<number> {
+  const checks: Check[] = [];
+
+  const node = process.versions.node;
+  checks.push({ label: "Node", ok: semverGte(node, NODE_MIN), detail: `v${node} (need ≥ ${NODE_MIN})`, fatal: true });
+
+  const cfg = loadConfig();
+  const providers = availableProviders();
+  for (const p of Object.keys(ENV_VAR) as Provider[]) {
+    const has = providers.includes(p);
+    const src = cfg.keys[p] ? "~/.projectinator/config.json" : has ? "env" : "";
+    checks.push({ label: `Key: ${PROVIDER_LABEL[p]}`, ok: has, detail: has ? `set (${src})` : `not set — Settings → API keys, or export ${ENV_VAR[p]}` });
+  }
+  if (providers.length === 0) checks.push({ label: "Any provider key", ok: false, detail: "no keys at all — nothing can run", fatal: true });
+
+  try {
+    const runtime = await piRuntime();
+    const bad: string[] = [];
+    for (const e of REGISTRY) for (const b of ["api", "web"] as const) {
+      try { resolvePiModel(runtime, e.byBackend[b].provider, e.byBackend[b].model); } catch { bad.push(`${e.capability}/${e.tier}/${b}`); }
+    }
+    checks.push({ label: "Pi model catalog", ok: bad.length === 0, detail: bad.length ? `unresolved: ${bad.join(", ")}` : `${Object.keys(MODELS).length} models priced, every registry pick resolves`, fatal: true });
+  } catch (e) {
+    checks.push({ label: "Pi model catalog", ok: false, detail: e instanceof Error ? e.message : String(e), fatal: true });
+  }
+
+  const chromium = await chromiumAvailable();
+  checks.push({ label: "Headless Chromium", ok: chromium, detail: chromium ? "installed — tester runs the app" : `missing — tests will be code-reading only (PASS*); ${CHROMIUM_INSTALL_HINT}` });
+
+  const git = spawnSync("git", ["--version"], { encoding: "utf8" });
+  checks.push({ label: "git", ok: git.status === 0, detail: git.status === 0 ? git.stdout.trim() : "not found — builds won't be versioned (undo/history disabled)" });
+
+  const home = join(homedir(), ".projectinator");
+  try { mkdirSync(home, { recursive: true }); accessSync(home, constants.W_OK); checks.push({ label: "Data dir", ok: true, detail: home }); }
+  catch { checks.push({ label: "Data dir", ok: false, detail: `${home} not writable`, fatal: true }); }
+
+  const prefs = getPrefs();
+  checks.push({ label: "Prefs", ok: true, detail: `budget cap ${money(prefs.budgetCapUSD)} · ${prefs.concurrency} at once · task limits ${prefs.taskTimeoutMin || "∞"} min / ${prefs.taskCostCapUSD ? money(prefs.taskCostCapUSD) : "∞"}` });
+
+  console.log("\n  projectinator doctor\n");
+  for (const c of checks) console.log(`  ${c.ok ? "✓" : c.fatal ? "✗" : "!"}  ${c.label.padEnd(22)} ${c.detail}`);
+  const fatal = checks.filter((c) => !c.ok && c.fatal);
+  const warn = checks.filter((c) => !c.ok && !c.fatal);
+  console.log(`\n  ${fatal.length ? `${fatal.length} blocking problem${fatal.length === 1 ? "" : "s"}` : "Ready"}${warn.length ? ` · ${warn.length} warning${warn.length === 1 ? "" : "s"}` : ""}\n`);
+  return fatal.length ? 1 : 0;
+}
+
+// ---- projects ----
+
+function projects(): number {
+  const list = listProjects();
+  if (!list.length) { console.log("\n  No projects yet. Run `projectinator` or `projectinator build \"an idea\"`.\n"); return 0; }
+  console.log("");
+  for (const p of list) {
+    const done = p.state.outcomes.filter((o) => !o.error).length;
+    const mark = p.status === "complete" ? "✓" : p.status === "halted" ? "⚠" : "…";
+    console.log(`  ${mark} ${p.slug.padEnd(40)} ${p.status.padEnd(9)} ${money(p.totalCost).padStart(8)}  ${done}/${p.taskCount} tasks`);
+    console.log(`      ${p.idea.slice(0, 90)}${p.idea.length > 90 ? "…" : ""}`);
+  }
+  console.log(`\n  ${list.length} project${list.length === 1 ? "" : "s"} · ${money(list.reduce((a, p) => a + p.totalCost, 0))} all time · ${join(homedir(), "…")}\n`);
+  return 0;
+}
+
+// ---- models ----
+
+function models(): number {
+  const providers = availableProviders();
+  console.log(`\n  Roster as it will run now${providers.length ? ` (keys: ${providers.join(", ")})` : " (no keys — best-of-breed picks shown)"}\n`);
+  for (const r of effectiveRoster()) {
+    const m = r.model ? getModel(r.model) : undefined;
+    const price = m ? `$${m.cost.input}/$${m.cost.output} per 1M` : "";
+    console.log(`  ${r.label.padEnd(18)} ${(r.model ?? "—").padEnd(28)} ${(r.provider ?? "").padEnd(11)} ${price}`);
+  }
+  console.log("\n  Change in the app: Settings → Models. Prices are from Pi's catalog; actual cost is measured per run.\n");
+  return 0;
+}
+
+// ---- build ----
+
+function ask(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const { promise, resolve } = Promise.withResolvers<string>();
+  rl.question(question, (a) => { rl.close(); resolve(a.trim()); });
+  return promise;
+}
+
+async function build(argv: Argv): Promise<number> {
+  const idea = argv.positional.join(" ").trim();
+  const json = argv.flags.json === true;
+  const yes = json || argv.flags.yes === true || argv.flags.y === true;
+  const dry = argv.flags["dry-run"] === true;
+  const emit = (o: Record<string, unknown>) => { if (json) process.stdout.write(JSON.stringify(o) + "\n"); };
+  const say = (s: string) => { if (!json) console.log(s); };
+
+  if (!idea) { console.error("  build: give an idea, e.g. projectinator build \"a tip calculator\""); return 2; }
+
+  let providers = availableProviders();
+  const lock = argv.flags.provider;
+  if (typeof lock === "string") {
+    if (!(lock in PROVIDER_LABEL)) { console.error(`  build: unknown provider "${lock}" (anthropic | openai | google | openrouter)`); return 2; }
+    if (!providers.includes(lock as Provider)) { console.error(`  build: no key for ${lock} — export ${ENV_VAR[lock as Provider]} or set it in the app`); return 1; }
+    providers = [lock as Provider];
+  }
+  if (!providers.length) { console.error("  build: no API key found. Run `projectinator doctor`."); return 1; }
+
+  const prefs = getPrefs();
+  const budget = num(argv.flags.budget, prefs.budgetCapUSD);
+  const concurrency = Math.max(1, Math.floor(num(argv.flags.concurrency, prefs.concurrency)));
+  const taskLimits = {
+    timeoutMs: num(argv.flags["task-timeout"], prefs.taskTimeoutMin) * 60_000,
+    costCapUSD: num(argv.flags["task-cap"], prefs.taskCostCapUSD),
+  };
+
+  say(`\n  Planning with the PM (${providers.join("/")})…`);
+  const plan = await planBuild(idea, providers);
+  emit({ event: "plan", provider: plan.provider, modelId: plan.modelId, estCost: plan.estCost, tasks: plan.tasks });
+  say(`\n  ${plan.tasks.length} tasks · estimated ${money(plan.estCost)} · cap ${money(budget)}${plan.lock ? ` · locked to ${plan.lock}` : ""}\n`);
+  for (const t of plan.tasks) {
+    const dep = t.dependsOn?.length ? `  ← ${t.dependsOn.join(", ")}` : "";
+    say(`    ${t.id.padEnd(6)} ${t.capability.padEnd(7)} ${t.difficulty.padEnd(8)} ${t.title}${dep}`);
+  }
+  if (plan.estCost > budget) say(`\n  ⚠ Estimate exceeds the cap — the build may halt partway.`);
+
+  if (dry) { say("\n  Dry run — nothing built (the PM call above was the only spend).\n"); return 0; }
+  if (!yes) {
+    const a = await ask(`\n  Build it for ~${money(plan.estCost)}? [y/N] `);
+    if (!/^y(es)?$/i.test(a)) { say("  Cancelled.\n"); return 0; }
+  }
+
+  const onEvent = (e: OrchestratorEvent) => {
+    emit({ event: e.type, ...e });
+    if (json) return;
+    if (e.type === "task_start") console.log(`  ▶ ${e.task.id} [${e.task.capability}] → ${e.provider}/${e.modelId}${e.round ? ` (round ${e.round})` : ""}`);
+    else if (e.type === "task_done") console.log(`    ✓ ${e.outcome.taskId} ${money(e.outcome.cost)}  running ${money(e.runningTotal)}${e.outcome.verdict ? `  ${e.outcome.verdict.passed ? (e.outcome.verdict.runtimeChecked || e.outcome.capability !== "test" ? "PASS" : "PASS* (app not executed)") : "FAIL"}` : ""}`);
+    else if (e.type === "task_failed") console.log(`    ⛔ ${e.outcome.taskId} aborted: ${e.outcome.error} — billed ${money(e.outcome.cost)}`);
+    else if (e.type === "task_skipped") console.log(`    · ${e.taskId} skipped`);
+    else if (e.type === "test_failed") console.log(`    ✗ ${e.taskId} failed (${e.bugs} bugs) — round ${e.round}`);
+    else if (e.type === "retry_dev") console.log(`    ↻ re-running ${e.taskId} to fix ${e.forTest}`);
+    else if (e.type === "budget_halt") console.log(`    ⚠ budget halt at ${money(e.runningTotal)} (cap ${money(e.cap)})`);
+    else if (e.type === "cycle_or_error") console.log(`    ✗ ${e.message}`);
+  };
+
+  say(`\n  Building…\n`);
+  const handle = startBuild(idea, plan, { concurrency, budgetCapUSD: budget, taskLimits, onEvent, mode: "auto" });
+  const r = await handle.promise;
+  emit({ event: "done", halted: r.halted, haltReason: r.haltReason, totalCost: r.totalCost, files: r.files, workspace: handle.workspace });
+  say(`\n  ${r.halted ? `⚠ Halted (${r.haltReason ?? "?"})` : "✓ Complete"} · ${money(r.totalCost)} · ${r.files.length} file${r.files.length === 1 ? "" : "s"}`);
+  say(`  ${handle.workspace}\n`);
+  return r.halted ? 3 : 0;
+}
+
+// ---- main ----
+
+const USAGE = `Usage: projectinator <command> [options]
+
+  doctor                        check Node, API keys, Chromium, Pi catalog, git
+  build "<idea>" [options]      plan + build headless (same workspace as the app)
+      --dry-run                 plan and estimate only (spends one PM call)
+      --yes, -y                 don't ask before building
+      --json                    NDJSON events on stdout (implies --yes)
+      --budget <usd>            cap for this build       (default: your prefs)
+      --provider <name>         anthropic|openai|google|openrouter (default: prefs / keys)
+      --concurrency <n>         tasks at once            (default: your prefs)
+      --task-cap <usd>          per-task cost ceiling    (default: your prefs; 0 = off)
+      --task-timeout <min>      per-task timeout         (default: your prefs; 0 = off)
+  projects                      list past builds with status and cost
+  models                        the roster as it will run, with prices
+
+Exit codes: 0 ok · 1 environment problem · 2 bad usage · 3 build halted`;
+
+export async function main(args: string[]): Promise<number> {
+  applyKeysToEnv();
+  const argv = parseArgv(args);
+  const cmd = argv.positional.shift();
+  switch (cmd) {
+    case "doctor": return doctor();
+    case "projects": return projects();
+    case "models": return models();
+    case "build": return build(argv);
+    case undefined: case "help": console.log(USAGE); return cmd ? 0 : 2;
+    default: console.error(`projectinator: unknown command "${cmd}".\n\n${USAGE}`); return 2;
+  }
+}
+
+if (process.argv[1] && import.meta.url === new URL(process.argv[1], "file://").href) {
+  process.exitCode = await main(process.argv.slice(2));
+}