@launchchair/agent 0.4.0

package/launchchair-cli.mjs

@@ -0,0 +1,1013 @@
+#!/usr/bin/env node
+
+/**
+ * LaunchChair Agent CLI.
+ *
+ * Thin convenience wrapper around the public Agent API and local bridge.
+ * MCP-only setups do not need this file; CLI users can use it for doctor,
+ * project discovery/creation, and local bridge control.
+ */
+
+import { spawn } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const VERSION = "0.4.0";
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_BASE_URL = "https://www.launchchair.io";
+const CONFIG_DIR = process.env.LAUNCHCHAIR_CONFIG_DIR?.trim()
+  ? path.resolve(process.env.LAUNCHCHAIR_CONFIG_DIR.trim())
+  : path.join(os.homedir() || process.cwd(), ".launchchair");
+const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+
+const COLORS_ENABLED = !process.env.NO_COLOR && process.env.TERM !== "dumb";
+const color = {
+  reset: "\u001b[0m",
+  bold: "\u001b[1m",
+  dim: "\u001b[2m",
+  green: "\u001b[32m",
+  yellow: "\u001b[33m",
+  red: "\u001b[31m",
+  cyan: "\u001b[36m",
+  purple: "\u001b[35m",
+};
+
+function env(name, fallback = "") {
+  const value = process.env[name];
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+
+function paint(value, tone) {
+  if (!COLORS_ENABLED || !color[tone]) return value;
+  return `${color[tone]}${value}${color.reset}`;
+}
+
+function loadConfig() {
+  if (!existsSync(CONFIG_PATH)) return {};
+  try {
+    const raw = readFileSync(CONFIG_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function saveConfig(patch) {
+  const next = {
+    ...loadConfig(),
+    ...Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined)),
+  };
+  mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CONFIG_PATH, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  try {
+    chmodSync(CONFIG_PATH, 0o600);
+  } catch {
+    // Best effort only. Some filesystems do not support POSIX chmod.
+  }
+  return next;
+}
+
+function deleteConfigKeys(keys) {
+  const current = loadConfig();
+  keys.forEach((key) => {
+    delete current[key];
+  });
+  mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CONFIG_PATH, `${JSON.stringify(current, null, 2)}\n`, { mode: 0o600 });
+  return current;
+}
+
+function configValue(key, envNames = [], fallback = "") {
+  for (const name of envNames) {
+    const value = env(name);
+    if (value) return value;
+  }
+  const config = loadConfig();
+  const value = config[key];
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+
+function token() {
+  return configValue("agentToken", ["LAUNCHCHAIR_AGENT_TOKEN", "LAUNCHCHAIR_API_KEY"]);
+}
+
+function tokenSource() {
+  if (env("LAUNCHCHAIR_AGENT_TOKEN")) return "LAUNCHCHAIR_AGENT_TOKEN";
+  if (env("LAUNCHCHAIR_API_KEY")) return "LAUNCHCHAIR_API_KEY";
+  if (loadConfig().agentToken) return CONFIG_PATH;
+  return "missing";
+}
+
+function baseUrl() {
+  return configValue("baseUrl", ["LAUNCHCHAIR_BASE_URL"], DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+
+function defaultProjectId() {
+  return configValue("projectId", ["LAUNCHCHAIR_PROJECT_ID"]);
+}
+
+function maskToken(value) {
+  if (!value) return "missing";
+  if (value.length <= 18) return `${value.slice(0, 6)}...`;
+  return `${value.slice(0, 10)}...${value.slice(-6)}`;
+}
+
+function print(message = "") {
+  // eslint-disable-next-line no-console
+  console.log(message);
+}
+
+function write(message = "") {
+  // eslint-disable-next-line no-console
+  process.stdout.write(message);
+}
+
+function title(message) {
+  print(`${paint("LaunchChair", "purple")} ${paint(message, "bold")}`);
+}
+
+function row(label, value, tone = "dim") {
+  print(`${paint(label.padEnd(18), "dim")} ${paint(String(value), tone)}`);
+}
+
+function ok(message) {
+  print(`${paint("OK", "green")} ${message}`);
+}
+
+function warn(message) {
+  print(`${paint("WARN", "yellow")} ${message}`);
+}
+
+function fail(message) {
+  print(`${paint("ERROR", "red")} ${message}`);
+}
+
+function help() {
+  print(`
+LaunchChair Agent CLI v${VERSION}
+
+Use MCP-only when you want agent tools inside Codex/Claude/Hermes.
+Use CLI + MCP when you also want quick terminal commands, diagnostics, and bridge control.
+
+Commands:
+  doctor                         Check token, docs, API reachability, and local bridge files
+  login [--token TOKEN]           Open browser login and save a LaunchChair Agent API token locally
+  logout                          Remove the saved local token
+  whoami                          Show the current API identity and token source
+  projects [--query name]         List projects visible to the token
+  create --name NAME [options]    Create a LaunchChair project
+  continue [--project-id ID]       Ask LaunchChair to continue the project loop once
+  run-once                        Claim and run one queued LaunchChair job through the local bridge
+  bridge                          Start the long-running local bridge for Run with Agent
+  setup codex|claude|terminal [options]
+                                  Guided setup for CLI, CWD, AGENTS.md, MCP config, and bridge
+  config                          Show local CLI config without printing the token
+  config set KEY VALUE             Save base-url, project-id, codex-cwd, or claude-code-cwd
+  mcp-config codex|claude         Print MCP config with current paths/defaults
+  install-agent-md [--cwd PATH]   Create a small AGENTS.md pointer in a fresh repo
+
+Create options:
+  --one-liner TEXT
+  --project-type b2b|b2c|both
+  --problem TEXT
+  --target-user TEXT
+  --solution TEXT
+  --start-loop
+  --save-project                  Save the created project id as the CLI default
+  --idempotency-key KEY
+
+Feature create options:
+  --project-kind feature
+  --feature-description TEXT      Feature idea; --one-liner can be used as a shortcut
+  --product-description TEXT      Existing product context
+  --current-workflow TEXT         Current workflow being changed
+  --desired-workflow TEXT         Desired workflow after the feature ships
+  --changes-existing-workflow     Mark the feature as changing existing product behavior
+  --plan-to-build-board           Default for feature projects unless --create-only is used
+  --create-only                   Create the feature project without planning to the build board
+  --full-loop                     After planning, continue into Build MVP
+  --max-steps NUMBER              Max planning loop steps. Default: 12, max: 25
+  --build-max-steps NUMBER        Max build loop steps for --full-loop. Default: 25
+
+Continue options:
+  --project-id ID                 Optional when LAUNCHCHAIR_PROJECT_ID or config project-id is set
+  --stop-phase-key KEY            Stop after a phase, for example market_validation
+  --completion-target TEXT        Natural-language target for the loop run
+
+Setup options:
+  --cwd PATH                      Repo folder or empty folder the agent should build into
+  --token TOKEN                   Optional manual lc_at token fallback to save during setup
+  --project-id ID                 Optional default LaunchChair project id
+  --base-url URL                  Optional LaunchChair base URL
+  --skip-login                    Do not start browser login during setup
+  --no-open                       During setup login, print the approval URL instead of opening a browser
+  --timeout SECONDS               During setup login, approval timeout. Default: 600
+  --start-bridge                  Start the local bridge after setup
+
+Login options:
+  --token TOKEN                   Manual fallback: save an existing lc_at token
+  --base-url URL                  Optional LaunchChair base URL
+  --project-id ID                 Optional default LaunchChair project id
+  --name TEXT                     Optional token name shown in Settings -> API Access
+  --no-open                       Print the approval URL instead of opening a browser
+  --timeout SECONDS               Default: 600
+
+Env:
+  LAUNCHCHAIR_AGENT_TOKEN         Optional full lc_at token override
+  LAUNCHCHAIR_BASE_URL            Default: https://www.launchchair.io
+  LAUNCHCHAIR_PROJECT_ID          Optional default project id
+  LC_AGENT_CODEX_CWD              Folder Codex should build into
+  LC_AGENT_CLAUDE_CODE_CWD        Folder Claude Code should build into
+
+Config:
+  ${CONFIG_PATH}
+`);
+}
+
+function parseArgs(argv) {
+  const result = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      result._.push(arg);
+      continue;
+    }
+    const eqIndex = arg.indexOf("=");
+    if (eqIndex > 2) {
+      result[arg.slice(2, eqIndex)] = arg.slice(eqIndex + 1);
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      result[key] = true;
+      continue;
+    }
+    result[key] = next;
+    index += 1;
+  }
+  return result;
+}
+
+async function api(pathname, options = {}) {
+  const agentToken = token();
+  if (!agentToken) {
+    throw new Error("Missing LaunchChair token. Run: launchchair login");
+  }
+  const response = await fetch(`${baseUrl()}${pathname}`, {
+    ...options,
+    headers: {
+      Authorization: `Bearer ${agentToken}`,
+      "Content-Type": "application/json",
+      ...(options.headers ?? {}),
+    },
+  });
+  const text = await response.text();
+  let body = null;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = { raw: text };
+  }
+  if (!response.ok) {
+    const retryAfter = response.headers.get("retry-after");
+    const suffix = retryAfter ? ` Retry after ${retryAfter}s.` : "";
+    throw new Error(`${body?.error ?? response.statusText}${suffix}`);
+  }
+  return body;
+}
+
+async function publicApi(pathname, options = {}) {
+  const response = await fetch(`${baseUrl()}${pathname}`, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...(options.headers ?? {}),
+    },
+  });
+  const text = await response.text();
+  let body = null;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = { raw: text };
+  }
+  if (!response.ok) {
+    const retryAfter = response.headers.get("retry-after");
+    const suffix = retryAfter ? ` Retry after ${retryAfter}s.` : "";
+    throw new Error(`${body?.error ?? response.statusText}${suffix}`);
+  }
+  return body;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+  const child = spawn(command, args, {
+    stdio: "ignore",
+    detached: true,
+  });
+  child.on("error", () => {});
+  child.unref();
+}
+
+async function doctor() {
+  title("CLI doctor");
+  row("Base URL", baseUrl(), "cyan");
+  row("Config file", existsSync(CONFIG_PATH) ? CONFIG_PATH : "not created yet", existsSync(CONFIG_PATH) ? "dim" : "yellow");
+  row("Token", token() ? `${maskToken(token())} (${tokenSource()})` : "missing", token() ? "green" : "yellow");
+  row("Local bridge", existsSync(path.join(SCRIPT_DIR, "local-bridge.mjs")) ? "present" : "missing", existsSync(path.join(SCRIPT_DIR, "local-bridge.mjs")) ? "green" : "red");
+  row("MCP bridge", existsSync(path.join(SCRIPT_DIR, "mcp-bridge-server.mjs")) ? "present" : "missing", existsSync(path.join(SCRIPT_DIR, "mcp-bridge-server.mjs")) ? "green" : "red");
+  row("AGENTS.md", existsSync(path.join(SCRIPT_DIR, "AGENTS.md")) ? "present" : "missing", existsSync(path.join(SCRIPT_DIR, "AGENTS.md")) ? "green" : "yellow");
+  if (!token()) {
+    warn("Run launchchair login to approve this CLI in your browser.");
+    return;
+  }
+  const status = await api("/api/agent/v1");
+  ok(`API reachable (${status?.version ?? "v1"})`);
+  const projects = await api("/api/agent/v1/projects?limit=5");
+  row("Visible projects", projects?.count ?? projects?.projects?.length ?? 0, "green");
+}
+
+async function login(args) {
+  const incomingToken = typeof args.token === "string" ? args.token.trim() : "";
+  const incomingBaseUrl = typeof args["base-url"] === "string" ? args["base-url"].trim().replace(/\/+$/, "") : undefined;
+  const incomingProjectId = typeof args["project-id"] === "string" ? args["project-id"].trim() : undefined;
+  if (incomingBaseUrl || incomingProjectId) {
+    saveConfig({
+      baseUrl: incomingBaseUrl ?? baseUrl(),
+      projectId: incomingProjectId || defaultProjectId() || undefined,
+    });
+  }
+
+  title("CLI login");
+
+  if (incomingToken) {
+    if (!incomingToken.startsWith("lc_at_")) {
+      throw new Error("LaunchChair agent tokens start with lc_at_. Paste the full Agent API token.");
+    }
+    saveConfig({
+      agentToken: incomingToken,
+      baseUrl: incomingBaseUrl ?? baseUrl(),
+      projectId: incomingProjectId || defaultProjectId() || undefined,
+    });
+    ok(`Saved token to ${CONFIG_PATH}`);
+    row("Token", maskToken(incomingToken), "green");
+    row("Base URL", incomingBaseUrl ?? baseUrl(), "cyan");
+    if (incomingProjectId || defaultProjectId()) row("Project ID", incomingProjectId || defaultProjectId(), "cyan");
+    try {
+      const status = await api("/api/agent/v1");
+      ok(`API reachable (${status?.version ?? "v1"})`);
+    } catch (error) {
+      warn(`Token was saved, but API verification failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return;
+  }
+
+  row("Base URL", baseUrl(), "cyan");
+  const start = await publicApi("/api/agent/v1/cli-login/start", {
+    method: "POST",
+    body: JSON.stringify({
+      clientName: `LaunchChair CLI on ${os.hostname() || "local machine"}`,
+      tokenName: typeof args.name === "string" && args.name.trim() ? args.name.trim() : `LaunchChair CLI (${os.hostname() || "local"})`,
+    }),
+  });
+  if (!start?.deviceCode || !start?.verificationUriComplete) {
+    throw new Error("LaunchChair did not return a complete CLI login challenge.");
+  }
+
+  row("Code", start.userCode ?? "unknown", "bold");
+  row("Approve", start.verificationUriComplete, "cyan");
+  if (args["no-open"] === true) {
+    warn("Browser opening skipped. Open the approval URL above.");
+  } else {
+    try {
+      openBrowser(start.verificationUriComplete);
+      ok("Opened browser approval page.");
+    } catch {
+      warn("Could not open a browser automatically. Open the approval URL above.");
+    }
+  }
+
+  const timeoutSeconds =
+    typeof args.timeout === "string" && Number.isFinite(Number(args.timeout)) ? Math.max(10, Number(args.timeout)) : Number(start.expiresIn ?? 600);
+  const intervalSeconds = Math.max(2, Number(start.interval ?? 2));
+  const startedAt = Date.now();
+  print("");
+  print("Waiting for approval. Leave this terminal open.");
+
+  while (Date.now() - startedAt < timeoutSeconds * 1000) {
+    await sleep(intervalSeconds * 1000);
+    let poll;
+    try {
+      poll = await publicApi("/api/agent/v1/cli-login/poll", {
+        method: "POST",
+        body: JSON.stringify({ deviceCode: start.deviceCode }),
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (/pending/i.test(message)) continue;
+      throw error;
+    }
+    if (poll?.status === "pending") {
+      write(paint(".", "dim"));
+      continue;
+    }
+    if (poll?.status === "approved" && poll?.token) {
+      print("");
+      saveConfig({
+        agentToken: poll.token,
+        baseUrl: baseUrl(),
+        projectId: incomingProjectId || defaultProjectId() || undefined,
+      });
+      ok(`Saved token to ${CONFIG_PATH}`);
+      row("Token", maskToken(poll.token), "green");
+      if (poll.tokenRecord?.tokenPrefix) row("Token prefix", poll.tokenRecord.tokenPrefix, "green");
+      const status = await api("/api/agent/v1");
+      ok(`API reachable (${status?.version ?? "v1"})`);
+      return;
+    }
+    if (poll?.status === "expired") throw new Error("CLI login expired. Run launchchair login again.");
+    if (poll?.status === "denied") throw new Error("CLI login was denied.");
+    if (poll?.status === "token_creation_failed") throw new Error(poll.error ?? "LaunchChair could not create a CLI token.");
+  }
+  throw new Error("CLI login timed out. Run launchchair login again.");
+}
+
+function logout() {
+  deleteConfigKeys(["agentToken"]);
+  title("CLI logout");
+  ok(`Removed saved token from ${CONFIG_PATH}`);
+  if (env("LAUNCHCHAIR_AGENT_TOKEN") || env("LAUNCHCHAIR_API_KEY")) {
+    warn("An environment token is still set, so CLI commands may remain authenticated in this shell.");
+  }
+}
+
+async function whoami() {
+  title("CLI identity");
+  row("Base URL", baseUrl(), "cyan");
+  row("Token source", tokenSource(), token() ? "green" : "yellow");
+  row("Token", maskToken(token()), token() ? "green" : "yellow");
+  row("Project ID", defaultProjectId() || "not set", defaultProjectId() ? "cyan" : "dim");
+  if (!token()) return;
+  const status = await api("/api/agent/v1");
+  row("API", `ok (${status?.version ?? "v1"})`, "green");
+}
+
+async function listProjects(args) {
+  const query = typeof args.query === "string" ? args.query : "";
+  const params = new URLSearchParams();
+  if (query) params.set("query", query);
+  const body = await api(`/api/agent/v1/projects${params.toString() ? `?${params.toString()}` : ""}`);
+  const projects = Array.isArray(body?.projects) ? body.projects : [];
+  title("Projects");
+  if (!projects.length) {
+    warn(query ? `No projects matched "${query}".` : "No projects visible to this token.");
+    return;
+  }
+  projects.forEach((project) => {
+    print(`${paint(project.name ?? "Untitled project", "bold")} ${paint(project.id ?? "", "dim")}`);
+    if (project.updatedAt || project.createdAt) row("Updated", project.updatedAt ?? project.createdAt, "dim");
+    if (project.url) row("Open", project.url, "cyan");
+    print("");
+  });
+}
+
+async function createProject(args) {
+  const name = typeof args.name === "string" ? args.name : "";
+  if (!name) {
+    throw new Error("create requires --name.");
+  }
+  const projectKind = String(args["project-kind"] ?? "product").trim().toLowerCase();
+  if (projectKind !== "product" && projectKind !== "feature") {
+    throw new Error("--project-kind must be product or feature.");
+  }
+  const featureProject = projectKind === "feature";
+  const featureDescription = String(args["feature-description"] ?? args["one-liner"] ?? "").trim();
+  const featureProblem = String(args.problem ?? "").trim();
+  if (featureProject && (!featureDescription || !featureProblem)) {
+    throw new Error(
+      "Feature creation requires --feature-description (or --one-liner) and --problem. The Feature beta must also be enabled for the token owner.",
+    );
+  }
+  const changesExistingWorkflow =
+    args["changes-existing-workflow"] === true ||
+    String(args["changes-existing-workflow"] ?? "").toLowerCase() === "true" ||
+    Boolean(String(args["current-workflow"] ?? "").trim()) ||
+    Boolean(String(args["desired-workflow"] ?? "").trim());
+  const planToBuildBoard =
+    featureProject &&
+    args["create-only"] !== true &&
+    String(args["plan-to-build-board"] ?? "true").toLowerCase() !== "false";
+  const headers = {};
+  if (typeof args["idempotency-key"] === "string") {
+    headers["Idempotency-Key"] = args["idempotency-key"];
+  }
+  const requestBody = featureProject
+    ? {
+        name,
+        oneLiner: featureDescription,
+        projectKind: "feature",
+        featureSnapshot: {
+          description: featureDescription,
+          problem: featureProblem,
+          existingProductDescription: String(args["product-description"] ?? "").trim() || undefined,
+          changesExistingWorkflow,
+          currentWorkflow: changesExistingWorkflow
+            ? String(args["current-workflow"] ?? "").trim() || undefined
+            : undefined,
+          desiredOutcome: changesExistingWorkflow
+            ? String(args["desired-workflow"] ?? "").trim() || undefined
+            : undefined,
+        },
+        startLoop: false,
+        clientRequestId: args["idempotency-key"] ?? undefined,
+      }
+    : {
+        name,
+        oneLiner: args["one-liner"] ?? "",
+        projectType: args["project-type"] ?? "both",
+        ideaSnapshot:
+          args.problem || args["target-user"] || args.solution
+            ? {
+                problem: args.problem ?? "",
+                targetUser: args["target-user"] ?? "",
+                solution: args.solution ?? "",
+              }
+            : undefined,
+        startLoop: args["start-loop"] === true,
+        clientRequestId: args["idempotency-key"] ?? undefined,
+      };
+  const body = await api("/api/agent/v1/projects", {
+    method: "POST",
+    headers,
+    body: JSON.stringify(requestBody),
+  });
+  const projectId = body?.project?.id ?? body?.projectId ?? "";
+  title("Project created");
+  row("Name", body?.project?.name ?? name, "bold");
+  row("Project ID", projectId || "unknown", "cyan");
+  if (body?.project?.url) row("Project URL", body.project.url, "cyan");
+  if (body?.project?.phasesUrl) row("Phases URL", body.project.phasesUrl, "cyan");
+  if (args["save-project"] === true && projectId) {
+    saveConfig({ projectId });
+    ok("Saved project id as the CLI default.");
+  }
+  if (body?.loop) {
+    row("Loop", body.loop.status ?? "started", body.loop.status === "error" ? "yellow" : "green");
+  }
+  if (planToBuildBoard && projectId) {
+    const maxSteps = Math.min(Math.max(Number.parseInt(String(args["max-steps"] ?? "12"), 10) || 12, 1), 25);
+    const planning = await planFeatureToBuildBoard(projectId, maxSteps);
+    row("Planning", planning?.status ?? "stopped", planning?.status === "build_board_ready" ? "green" : "yellow");
+    if (planning?.board?.url) row("Build Board", planning.board.url, "cyan");
+    if (planning?.board?.cardCount !== undefined) row("Build cards", planning.board.cardCount, "green");
+    if (planning?.message) row("Result", planning.message, "dim");
+    if (args["full-loop"] === true && planning?.status === "build_board_ready") {
+      const build = await runFeatureBuild(projectId, Math.min(Math.max(Number.parseInt(String(args["build-max-steps"] ?? "25"), 10) || 25, 1), 25));
+      row("Feature build", build?.status ?? "stopped", build?.status === "phase_complete" ? "green" : "yellow");
+      if (build?.message) row("Build result", build.message, "dim");
+      if (build?.humanInputUrl) row("Needs user", build.humanInputUrl, "yellow");
+    }
+  }
+}
+
+async function continueProject(args) {
+  const projectId = args["project-id"] || defaultProjectId();
+  if (!projectId) {
+    throw new Error("continue requires --project-id, LAUNCHCHAIR_PROJECT_ID, or config set project-id.");
+  }
+  const body = await api(`/api/agent/v1/projects/${encodeURIComponent(projectId)}/loop/continue`, {
+    method: "POST",
+    body: JSON.stringify({
+      stopPhaseKey: args["stop-phase-key"] ?? null,
+      completionTarget: args["completion-target"] ?? null,
+    }),
+  });
+  title("Project loop");
+  row("Project ID", projectId, "cyan");
+  row("Status", body?.status ?? "queued", body?.status === "error" ? "yellow" : "green");
+  if (body?.message) row("Message", body.message, "dim");
+  if (body?.phaseComplete?.url) row("Phase synthesis", body.phaseComplete.url, "cyan");
+  if (body?.humanInputUrl) row("Needs user", body.humanInputUrl, "yellow");
+  if (body?.queuedRun?.id) row("Queued run", body.queuedRun.id, "cyan");
+  if (body?.board?.url) row("Build Board", body.board.url, "cyan");
+}
+
+function targetDetails(target) {
+  if (target === "terminal" || target === "cli" || target === "shell") {
+    return {
+      label: "Terminal agent",
+      mcpTarget: null,
+      cwdConfigKey: "codexCwd",
+      cwdEnvName: "LC_AGENT_CODEX_CWD",
+      routerTarget: "cli",
+      terminalOnly: true,
+    };
+  }
+  if (target === "claude" || target === "claude-code" || target === "claude_code") {
+    return {
+      label: "Claude Desktop + Claude Code",
+      mcpTarget: "claude",
+      cwdConfigKey: "claudeCodeCwd",
+      cwdEnvName: "LC_AGENT_CLAUDE_CODE_CWD",
+      routerTarget: "claude_code",
+    };
+  }
+  return {
+    label: "Codex Desktop",
+    mcpTarget: "codex",
+    cwdConfigKey: "codexCwd",
+    cwdEnvName: "LC_AGENT_CODEX_CWD",
+    routerTarget: "codex",
+  };
+}
+
+function buildBridgeEnv(projectId = defaultProjectId()) {
+  const childEnv = {
+    ...process.env,
+    LAUNCHCHAIR_BASE_URL: baseUrl(),
+    LAUNCHCHAIR_AGENT_TOKEN: token(),
+    LAUNCHCHAIR_PROJECT_ID: projectId,
+    LC_AGENT_CODEX_CWD: configValue("codexCwd", ["LC_AGENT_CODEX_CWD"], ""),
+    LC_AGENT_CLAUDE_CODE_CWD: configValue("claudeCodeCwd", ["LC_AGENT_CLAUDE_CODE_CWD"], ""),
+  };
+  Object.keys(childEnv).forEach((key) => {
+    if (childEnv[key] === undefined || childEnv[key] === null || childEnv[key] === "") {
+      delete childEnv[key];
+    }
+  });
+  return childEnv;
+}
+
+function runBridgeOnce(projectId) {
+  const bridgePath = path.join(SCRIPT_DIR, "local-bridge.mjs");
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [bridgePath, "--once", "--verbose"], {
+      stdio: "inherit",
+      env: buildBridgeEnv(projectId),
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if ((code ?? 0) === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`LaunchChair local bridge exited with code ${code ?? "unknown"}.`));
+    });
+  });
+}
+
+async function planFeatureToBuildBoard(projectId, maxSteps) {
+  let last = null;
+  for (let step = 0; step < maxSteps; step += 1) {
+    const loop = await api(`/api/agent/v1/projects/${encodeURIComponent(projectId)}/loop/continue`, {
+      method: "POST",
+      body: JSON.stringify({
+        stopPhaseKey: "build",
+        completionTarget: "build_board_ready",
+      }),
+    });
+    last = loop;
+    if (loop?.status === "build_board_ready") {
+      return loop;
+    }
+    if (loop?.status !== "queued_run" && loop?.status !== "waiting_for_run") {
+      return loop;
+    }
+    await runBridgeOnce(projectId);
+  }
+  return {
+    status: "max_steps_reached",
+    projectId,
+    message: `Feature planning stopped after maxSteps=${maxSteps}. Run launchchair continue to inspect or resume it.`,
+    previous: last,
+  };
+}
+
+async function runFeatureBuild(projectId, maxSteps) {
+  let last = null;
+  for (let step = 0; step < maxSteps; step += 1) {
+    const loop = await api(`/api/agent/v1/projects/${encodeURIComponent(projectId)}/loop/continue`, {
+      method: "POST",
+      body: JSON.stringify({
+        stopPhaseKey: "build",
+        completionTarget: "phase_complete",
+      }),
+    });
+    last = loop;
+    if (loop?.status !== "queued_run" && loop?.status !== "waiting_for_run") {
+      return loop;
+    }
+    await runBridgeOnce(projectId);
+  }
+  return {
+    status: "max_steps_reached",
+    projectId,
+    message: `Feature build stopped after maxSteps=${maxSteps}. Run launchchair continue to inspect or resume it.`,
+    previous: last,
+  };
+}
+
+function spawnBridge(extraArgs = []) {
+  const bridgePath = path.join(SCRIPT_DIR, "local-bridge.mjs");
+  const child = spawn(process.execPath, [bridgePath, ...extraArgs], {
+    stdio: "inherit",
+    env: buildBridgeEnv(),
+  });
+  child.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+}
+
+function renderMcpConfig(target) {
+  const bridgePath = path.join(SCRIPT_DIR, "mcp-bridge-server.mjs");
+  const agentTokenPlaceholder = "<full lc_at token from LaunchChair Settings API Access>";
+  const projectId = defaultProjectId() || "optional-if-agent-creates-project";
+  if (target === "claude") {
+    return JSON.stringify(
+      {
+        mcpServers: {
+          launchchair: {
+            command: "node",
+            args: [bridgePath],
+            env: {
+              LAUNCHCHAIR_BASE_URL: baseUrl(),
+              LAUNCHCHAIR_AGENT_TOKEN: agentTokenPlaceholder,
+              LAUNCHCHAIR_PROJECT_ID: projectId,
+              LC_AGENT_ROUTER_GPT_TARGET: "claude_code",
+              LC_AGENT_ROUTER_CODEX_TARGET: "claude_code",
+              LC_AGENT_CLAUDE_CODE_CWD: configValue("claudeCodeCwd", ["LC_AGENT_CLAUDE_CODE_CWD"], "/absolute/path/to/repo-or-empty-folder"),
+            },
+          },
+        },
+      },
+      null,
+      2,
+    );
+  }
+  return `[mcp_servers.launchchair]
+command = "node"
+args = ["${bridgePath}"]
+required = true
+startup_timeout_sec = 20
+tool_timeout_sec = 3600
+default_tools_approval_mode = "approve"
+
+[mcp_servers.launchchair.env]
+LAUNCHCHAIR_BASE_URL = "${baseUrl()}"
+LAUNCHCHAIR_AGENT_TOKEN = "${agentTokenPlaceholder}"
+LAUNCHCHAIR_PROJECT_ID = "${projectId}"
+LC_AGENT_ROUTER_GPT_TARGET = "codex"
+LC_AGENT_ROUTER_CODEX_TARGET = "codex"
+LC_AGENT_CODEX_CWD = "${configValue("codexCwd", ["LC_AGENT_CODEX_CWD"], "/absolute/path/to/repo-or-empty-folder")}"`;
+}
+
+function printMcpConfig(target) {
+  print(renderMcpConfig(target));
+}
+
+function showConfig() {
+  const config = loadConfig();
+  title("CLI config");
+  row("Path", CONFIG_PATH, existsSync(CONFIG_PATH) ? "dim" : "yellow");
+  row("Base URL", baseUrl(), "cyan");
+  row("Token", maskToken(token()), token() ? "green" : "yellow");
+  row("Token source", tokenSource(), token() ? "green" : "yellow");
+  row("Project ID", defaultProjectId() || "not set", defaultProjectId() ? "cyan" : "dim");
+  row("Codex CWD", configValue("codexCwd", ["LC_AGENT_CODEX_CWD"], "not set"), config.codexCwd || env("LC_AGENT_CODEX_CWD") ? "cyan" : "dim");
+  row("Claude Code CWD", configValue("claudeCodeCwd", ["LC_AGENT_CLAUDE_CODE_CWD"], "not set"), config.claudeCodeCwd || env("LC_AGENT_CLAUDE_CODE_CWD") ? "cyan" : "dim");
+}
+
+function setConfig(args) {
+  const key = args._[0];
+  const value = args._[1];
+  const allowed = {
+    "base-url": "baseUrl",
+    "project-id": "projectId",
+    "codex-cwd": "codexCwd",
+    "claude-code-cwd": "claudeCodeCwd",
+  };
+  if (!key || !value || !allowed[key]) {
+    throw new Error("Usage: launchchair config set base-url|project-id|codex-cwd|claude-code-cwd VALUE");
+  }
+  saveConfig({ [allowed[key]]: key === "base-url" ? value.replace(/\/+$/, "") : value });
+  ok(`Saved ${key} to ${CONFIG_PATH}`);
+}
+
+function installAgentMd(args) {
+  const cwd = path.resolve(String(args.cwd || process.cwd()));
+  const target = path.join(cwd, "AGENTS.md");
+  const bootstrapPath = path.join(SCRIPT_DIR, "AGENTS.md");
+  if (existsSync(target)) {
+    print(`AGENTS.md already exists: ${target}`);
+    return;
+  }
+  writeFileSync(
+    target,
+    [
+      "# LaunchChair Agent Bootstrap Pointer",
+      "",
+      `Before searching this repo, read ${bootstrapPath}.`,
+      "Use LaunchChair MCP/API first for product phases, project discovery, project creation, and phase loops.",
+      "Do not ask for extra confirmation before using LaunchChair MCP/API when the user already requested the action and the token permits it.",
+      "Only inspect this repo for Stack Setup, Build MVP, Design/Landing Page, SEO implementation, smoke testing, security review, or code remediation.",
+      "",
+    ].join("\n"),
+  );
+  print(`Created ${target}`);
+}
+
+function installLaunchChairSkill(args) {
+  const cwd = path.resolve(String(args.cwd || process.cwd()));
+  const featureEnabled = args.featureEnabled === true;
+  const skillDir = path.join(cwd, ".agents", "skills", "launchchair");
+  const target = path.join(skillDir, "SKILL.md");
+  if (existsSync(target)) {
+    print(`LaunchChair skill already exists: ${target}`);
+    return;
+  }
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(
+    target,
+    [
+      "---",
+      "name: launchchair",
+      featureEnabled
+        ? "description: Use whenever the user mentions LaunchChair or asks to create, plan, validate, or build a Product or a Feature in an existing product with LaunchChair."
+        : "description: Use whenever the user mentions LaunchChair or asks to create, plan, validate, or build a Product with LaunchChair.",
+      "---",
+      "",
+      "# LaunchChair workflow",
+      "",
+      "Use the installed LaunchChair MCP tools before web search or local repo discovery for LaunchChair project work.",
+      "Call launchchair_status if capability context is unclear.",
+      "For a new product, use launchchair_create_project.",
+      ...(featureEnabled
+        ? [
+            "For a feature in an existing product, use launchchair_create_feature_project. Never substitute a Product project if that tool is unavailable; report the setup or beta-access issue instead.",
+            "Use planToBuildBoard=true for planning through the Feature build board.",
+            "Use fullLoop=true only when the user asks to implement/build the feature; continue agent-run QA and stop for production SQL or a genuine external authorization boundary.",
+          ]
+        : []),
+      "Do not ask for extra confirmation for ordinary LaunchChair MCP calls when the user already requested the workflow and the token permits it.",
+      "",
+    ].join("\n"),
+  );
+  print(`Created ${target}`);
+}
+
+async function setup(args) {
+  const details = targetDetails(args._[0] || "codex");
+  const cwd = path.resolve(String(args.cwd || process.cwd()));
+  const incomingToken = typeof args.token === "string" ? args.token.trim() : "";
+  const incomingBaseUrl = typeof args["base-url"] === "string" ? args["base-url"].trim().replace(/\/+$/, "") : undefined;
+  const incomingProjectId = typeof args["project-id"] === "string" ? args["project-id"].trim() : "";
+
+  title(`guided setup for ${details.label}`);
+  mkdirSync(cwd, { recursive: true });
+  ok(`Build folder ready: ${cwd}`);
+
+  if (incomingToken) {
+    if (!incomingToken.startsWith("lc_at_")) {
+      throw new Error("LaunchChair agent tokens start with lc_at_. Paste the full Agent API token.");
+    }
+    saveConfig({
+      agentToken: incomingToken,
+      baseUrl: incomingBaseUrl ?? baseUrl(),
+      projectId: incomingProjectId || defaultProjectId() || undefined,
+    });
+    ok(`Saved token to ${CONFIG_PATH}`);
+  } else if (incomingBaseUrl || incomingProjectId) {
+    saveConfig({
+      baseUrl: incomingBaseUrl ?? baseUrl(),
+      projectId: incomingProjectId || defaultProjectId() || undefined,
+    });
+  }
+
+  saveConfig({ [details.cwdConfigKey]: cwd });
+  ok(`Saved ${details.cwdEnvName}: ${cwd}`);
+  installAgentMd({ cwd });
+
+  if (!token() && args["skip-login"] !== true) {
+    print("");
+    warn("No saved LaunchChair token found. Starting browser approval now.");
+    await login({
+      "base-url": incomingBaseUrl ?? baseUrl(),
+      "project-id": incomingProjectId || defaultProjectId() || undefined,
+      name:
+        typeof args.name === "string" && args.name.trim()
+          ? args.name.trim()
+          : `LaunchChair ${details.label} CLI (${os.hostname() || "local"})`,
+      "no-open": args["no-open"],
+      timeout: args.timeout,
+    });
+  }
+
+  if (details.mcpTarget === "codex") {
+    let featureEnabled = false;
+    if (token()) {
+      try {
+        const status = await api("/api/agent/v1");
+        featureEnabled = Boolean(status?.capabilities?.featureProjectWorkflow);
+      } catch {
+        // Install the public Product workflow when gated capability discovery is unavailable.
+      }
+    }
+    installLaunchChairSkill({ cwd, featureEnabled });
+  }
+
+  print("");
+  title("doctor");
+  try {
+    await doctor();
+  } catch (error) {
+    warn(`Doctor could not finish: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  print("");
+  if (details.terminalOnly) {
+    title("terminal agent commands");
+    print("Give a terminal agent the build folder and let it run these commands when needed:");
+    print(`  ${paint("launchchair doctor", "cyan")}`);
+    print(`  ${paint("launchchair projects", "cyan")}`);
+    print(`  ${paint("launchchair create --name \"My Project\" --one-liner \"...\" --project-type b2b --save-project", "cyan")}`);
+    print(`  ${paint("launchchair continue --project-id <project-id>", "cyan")}`);
+    print(`  ${paint("launchchair run-once", "cyan")}`);
+    print(`  ${paint("launchchair bridge", "cyan")}`);
+  } else {
+    title("MCP config to paste");
+    print(renderMcpConfig(details.mcpTarget));
+  }
+
+  print("");
+  title("next steps");
+  if (!token()) {
+    warn("No token is saved yet. Run browser login, then rerun setup or start the bridge:");
+    print(`  ${paint("launchchair login", "cyan")}`);
+    print(`  ${paint("launchchair login --token <full lc_at token>", "dim")} ${paint("(manual fallback)", "dim")}`);
+  }
+  if (details.terminalOnly) {
+    print("1. Open your terminal agent in the build folder above.");
+    print("2. Ask it to read AGENTS.md before searching the repo.");
+    print("3. For product/project work, have it use launchchair projects/create/continue before local code discovery.");
+    print("4. Keep launchchair bridge running only when LaunchChair UI Run with agent jobs should be picked up.");
+  } else {
+    print(`1. Paste the MCP config above into ${details.label}.`);
+    print(`2. Restart or reload ${details.label} so the MCP server is exposed to fresh chats.`);
+    print("3. Keep this bridge running when you want LaunchChair's Run with agent button to work:");
+    print(`   ${paint("launchchair bridge", "cyan")}`);
+    print("4. Start a fresh agent chat. Codex will discover the LaunchChair skill and MCP server instructions automatically.");
+  }
+  print("");
+  row("Build folder", cwd, "cyan");
+  row("Runner target", details.routerTarget, "cyan");
+  row("Config file", CONFIG_PATH, "dim");
+
+  if (args["start-bridge"] === true) {
+    if (!token()) {
+      warn("Bridge was not started because no token is configured yet.");
+      return;
+    }
+    print("");
+    ok("Starting LaunchChair local bridge. Leave this terminal open.");
+    spawnBridge(["--verbose"]);
+  }
+}
+
+async function main() {
+  const [command = "help", ...rest] = process.argv.slice(2);
+  const args = parseArgs(rest);
+  if (command === "help" || command === "--help" || command === "-h") return help();
+  if (command === "doctor") return doctor();
+  if (command === "login") return login(args);
+  if (command === "logout") return logout();
+  if (command === "whoami") return whoami();
+  if (command === "projects") return listProjects(args);
+  if (command === "create") return createProject(args);
+  if (command === "continue") return continueProject(args);
+  if (command === "run-once") return spawnBridge(["--once", "--verbose"]);
+  if (command === "bridge") return spawnBridge(["--verbose"]);
+  if (command === "setup") return setup(args);
+  if (command === "config" && args._[0] === "set") return setConfig({ ...args, _: args._.slice(1) });
+  if (command === "config") return showConfig();
+  if (command === "mcp-config") return printMcpConfig(args._[0] || "codex");
+  if (command === "install-agent-md") return installAgentMd(args);
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main().catch((error) => {
+  fail(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});