tapeo-cli 0.0.0-stage → 0.4.0

package/cli/tapeo.mjs

@@ -0,0 +1,509 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, hostname } from "node:os";
+import path from "node:path";
+import { ACTIVE_RUN_STATUSES, TapeoClient, describeGoals, describeRun, describeRunDetail, normalizeServerUrl, setClientIdentity, signInWithBrowser, stageScope, watchRun, DEFAULT_SERVER_URL } from "../shared/api.mjs";
+import { assertUnbound, designFilesFrom, downloadFile, localChanges, moveProjectFile, pullOutputs, pullProject, pushChanges, pushProjectFile, readState, removeProjectFile } from "../shared/sync.mjs";
+import { applyProposals, changeDiff, describeChange, discardProposals, loadProposals, saveProposals } from "../shared/proposals.mjs";
+import { collectRunProblems, formatProblem } from "../shared/problems.mjs";
+import { NOT_SURE, clarificationAnswersMessage } from "../shared/stream.mjs";
+import { chooseSerialPort, openSerialPort, parseBaud, serialCandidates } from "../shared/serial.mjs";
+import { OPENFPGALOADER_INSTALL, chooseBitstream, downloadBitstream, flashArguments, openFpgaLoaderAvailable, openFpgaLoaderExecutable } from "../shared/fpga.mjs";
+import { createInterface } from "node:readline/promises";
+
+const configPath = path.join(homedir(), ".config", "tapeo", "client.json");
+const clientVersion = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")).version;
+setClientIdentity("tapeo-cli", clientVersion);
+
+function usage() {
+  console.log(`Tapeo terminal client
+
+Sign in
+  tapeo login [server-url]        Sign in through your browser (approve this device there);
+                                  the server is https://tapeo.net unless you name another
+  tapeo login [server-url] --token  Paste a token from Account → VS Code and terminal access
+  tapeo logout                    Forget the saved sign-in on this computer
+  tapeo --version                 Show this client's version
+
+Projects and files
+  tapeo projects                  List your projects
+  tapeo create <name> [dir]       Create an empty project and bind a local folder
+  tapeo delete [project-id]       Delete a project on the server for good (this folder's
+                                  project by default; asks you to type its name, --yes
+                                  skips that); local files are kept
+  tapeo pull <project-id> [dir]   Pull source files without overwriting local edits
+  tapeo pull --outputs            Also download tool outputs (generated/, signoff/) read-only
+  tapeo status                    What changed locally, and the latest run
+  tapeo push <path...> | --all    Push named files, or every modified and new file
+  tapeo rm <path>                 Delete a file on the server and locally
+  tapeo mv <from> <to>            Rename a file on the server and locally
+  tapeo download <path> [dest]    Download one project file (any size, e.g. a GDS layout)
+
+AI
+  tapeo new [description] [dir]   Design a new chip with the Architect, then build it
+                                  (--from-files starts from this folder's RTL; --option N,
+                                  --auto-answers, --yes, --no-build for scripts)
+  tapeo ask "<question>"          Ask the AI Engineer about this project
+  tapeo history                   The recent Engineer conversation (shared with the browser)
+  tapeo proposals                 The Engineer's proposed file changes, with diffs
+  tapeo apply [n...]              Apply proposed changes to local files (all by default)
+  tapeo discard                   Forget the proposed changes
+  tapeo problems [run-id]         Tool errors and warnings as file:line (latest run by default)
+
+Workflow
+  tapeo run [--stage <s> | --from <s>] [--no-ai-repairs] [--watch]
+                                  Start a server run (a full run uses one build)
+  tapeo runs                      Recent runs
+  tapeo watch [run-id]            Follow a run until it ends, then show its results
+  tapeo show [run-id]             Stage results, AI changes, and tool runs of a run
+  tapeo logs <tool-run-id>        A tool run's saved output
+  tapeo goals                     The latest goal report
+  tapeo cancel [run-id]           Cancel a queued or running workflow
+  tapeo open                      Print this project's web address
+
+FPGA boards
+  tapeo flash [--board <id>] [--flash]
+                                  Download the bitstream and program the connected board with
+                                  openFPGALoader (--flash: keep it after power-off on boards
+                                  that load to SRAM by default, such as the Tang Nano 9K)
+  tapeo monitor [--port <path>] [--baud <n>]
+                                  Show the board's serial (UART) output and send what you
+                                  type; default 115200 baud (macOS and Linux)
+
+Stages: simulation, synthesis, timing, physical, post-route-timing, drc, extraction, erc, lvs.
+TAPEO_URL and TAPEO_TOKEN override the saved sign-in (for automation).`);
+}
+
+/** Split `--flag`, `--key value`, and positional arguments. */
+function parseArguments(args, valueFlags = []) {
+  const flags = {}, positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg.startsWith("--")) { positional.push(arg); continue; }
+    const name = arg.slice(2);
+    if (valueFlags.includes(name)) {
+      if (index + 1 >= args.length) throw new Error(`--${name} needs a value.`);
+      flags[name] = args[++index];
+    } else flags[name] = true;
+  }
+  return { flags, positional };
+}
+
+async function hiddenToken() {
+  if (!process.stdin.isTTY || !process.stdin.setRawMode) throw new Error("Run login in an interactive terminal, or set TAPEO_TOKEN in your environment.");
+  process.stdout.write("Paste project token (input hidden): ");
+  return new Promise((resolve, reject) => {
+    let value = "";
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    const done = (error) => {
+      process.stdin.off("data", onData);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write("\n");
+      if (error) reject(error); else resolve(value.trim());
+    };
+    const onData = (chunk) => {
+      for (const char of chunk.toString("utf8")) {
+        if (char === "\r" || char === "\n") return done();
+        if (char === "\u0003") return done(new Error("Canceled."));
+        if (char === "\u007f") value = value.slice(0, -1);
+        else if (value.length < 200) value += char;
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
+/** Open a page in the default browser; printing the address is the fallback. */
+function openBrowser(url) {
+  if (process.env.TAPEO_NO_BROWSER) return;
+  const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  try { spawn(command, args, { stdio: "ignore", detached: true }).on("error", () => undefined).unref(); } catch { /* the address is printed */ }
+}
+
+async function saveLogin(serverUrl, token) {
+  await mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });
+  await writeFile(configPath, JSON.stringify({ serverUrl, token }, null, 2) + "\n", { mode: 0o600 });
+  await chmod(configPath, 0o600);
+}
+
+async function configuredClient() {
+  let saved = {};
+  try { saved = JSON.parse(await readFile(configPath, "utf8")); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  const serverUrl = process.env.TAPEO_URL || saved.serverUrl;
+  const token = process.env.TAPEO_TOKEN || saved.token;
+  if (!serverUrl || !token) throw new Error("Run `tapeo login` first (or `tapeo login <server-url>` for your own server), or set TAPEO_URL and TAPEO_TOKEN.");
+  return new TapeoClient(serverUrl, token);
+}
+
+async function projectIdFor(client, explicit) {
+  if (explicit) return explicit;
+  const state = await readState(process.cwd()).catch((error) => {
+    if (error.code === "ENOENT") throw new Error("This folder is not a Tapeo project. Run the command in a pulled folder, or name the project id.");
+    throw error;
+  });
+  if (state.serverUrl !== client.serverUrl) throw new Error("This folder belongs to another Tapeo server.");
+  return state.projectId;
+}
+
+async function follow(client, projectId, runId) {
+  let lastStage = "";
+  const final = await watchRun(client, projectId, runId, {
+    onChange: (detail) => {
+      const label = `${detail.run.status}${detail.run.currentStage ? ` · ${detail.run.currentStage}` : ""}`;
+      if (label !== lastStage) { lastStage = label; console.log(`[${new Date().toLocaleTimeString()}] ${label}`); }
+    }
+  });
+  console.log("");
+  console.log(describeRunDetail(final));
+  const { report } = await client.goals(projectId).catch(() => ({ report: null }));
+  if (report) { console.log(""); console.log(describeGoals(report)); }
+  if (final.run.status === "failed") process.exitCode = 3;
+}
+
+/** Print an answer as it is written: only the new part each time. */
+function streamPrinter() {
+  let printed = "";
+  return {
+    update(text) { if (text.startsWith(printed)) { process.stdout.write(text.slice(printed.length)); printed = text; } },
+    finish(text) { if (text.startsWith(printed)) process.stdout.write(text.slice(printed.length)); else if (text !== printed) process.stdout.write(`\n${text}`); process.stdout.write("\n"); }
+  };
+}
+
+function showProposals(proposals) {
+  if (!proposals?.changes?.length) { console.log("No proposed file changes."); return; }
+  console.log(`Proposed changes (${proposals.changes.length}), from: "${proposals.question}"`);
+  proposals.changes.forEach((change, index) => {
+    console.log(`\n${describeChange(change, index)}`);
+    if (change.status === "pending" || change.status === "failed") console.log(changeDiff(change).split("\n").map((line) => `    ${line}`).join("\n"));
+  });
+  if (proposals.evaluationPlanProposed) console.log("\nThe Engineer also proposed an evaluation plan; review it in the web workspace (Evaluation).");
+}
+
+/** Questions on the terminal; scripts pass answers as flags instead. */
+function prompter() {
+  if (!process.stdin.isTTY) return null;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return { ask: (question) => rl.question(question), close: () => rl.close() };
+}
+
+async function newDesign(client, description, directory, flags) {
+  await assertUnbound(directory);
+  const prompt = flags["auto-answers"] && flags.yes && flags.option ? null : prompter();
+  try {
+    if (!description) {
+      if (!prompt) throw new Error("Describe the hardware: tapeo new \"A sensor that warns when a tank is full\"");
+      description = (await prompt.ask("Describe the hardware you want to build: ")).trim();
+      if (!description) throw new Error("No description given.");
+    }
+    const designFiles = flags["from-files"] ? await designFilesFrom(directory) : [];
+    if (flags["from-files"]) console.log(designFiles.length ? `Starting from ${designFiles.length} design file(s): ${designFiles.map((file) => file.path).join(", ")}` : "No design files found in this folder; starting from the description.");
+    const messages = [{ role: "user", content: description }];
+    let result;
+    for (let round = 0; round < 6; round += 1) {
+      const printer = streamPrinter();
+      process.stdout.write("\nArchitect: ");
+      result = await client.architect(messages, { designFiles }, (text) => printer.update(text));
+      printer.finish(result.message);
+      messages.push({ role: "assistant", content: result.message });
+      if (result.mode === "proposal" && result.options?.length) break;
+      const clarifications = result.clarifications ?? [];
+      if (!clarifications.length) {
+        if (!prompt) throw new Error("The Architect asked an open question; run tapeo new interactively to answer it.");
+        const reply = (await prompt.ask("\nYour answer: ")).trim();
+        messages.push({ role: "user", content: reply || "Choose sensible defaults and propose a design." });
+        continue;
+      }
+      const answers = {};
+      for (const [index, item] of clarifications.entries()) {
+        const choices = [...item.choices, NOT_SURE];
+        if (!prompt || flags["auto-answers"]) { answers[index] = NOT_SURE; continue; }
+        console.log(`\n${index + 1}. ${item.question}`);
+        choices.forEach((choice, number) => console.log(`   ${number + 1}) ${choice}`));
+        const picked = Number((await prompt.ask("   Choose a number (Enter: not sure): ")).trim() || choices.length);
+        answers[index] = choices[Math.min(Math.max(1, picked), choices.length) - 1];
+      }
+      const answer = clarificationAnswersMessage(clarifications, answers);
+      console.log(`\nYou: ${answer.replaceAll("\n", "\n     ")}`);
+      messages.push({ role: "user", content: answer });
+    }
+    if (result.mode !== "proposal" || !result.options?.length) throw new Error("The Architect did not propose a design yet. Run tapeo new again with more detail.");
+    if (result.brief?.summary) console.log(`\nBrief: ${result.brief.summary}${result.brief.successCriteria?.length ? `\n  It works when: ${result.brief.successCriteria.join("; ")}` : ""}`);
+    console.log("\nOptions:");
+    result.options.forEach((option, index) => console.log(`  ${index + 1}) ${option.name}${option.recommended ? " (recommended)" : ""}: ${option.summary}${option.tradeoffs?.length ? `\n     Trade-offs: ${option.tradeoffs.join("; ")}` : ""}`));
+    const recommended = Math.max(0, result.options.findIndex((option) => option.recommended));
+    let chosen = flags.option ? Number(flags.option) - 1 : recommended;
+    if (!flags.option && prompt) chosen = Number((await prompt.ask(`Choose an option (Enter: ${recommended + 1}): `)).trim() || recommended + 1) - 1;
+    const option = result.options[chosen];
+    if (!option) throw new Error(`There is no option ${chosen + 1}.`);
+    const { plan } = await client.designPlan(result.requirements, designFiles.map((file) => file.path));
+    console.log(`\nBuild plan for "${option.name}" · ${plan.platformLabel}${plan.platformNote ? ` (${plan.platformNote})` : ""}`);
+    for (const stage of plan.stages) console.log(`  ${stage.status === "runs" ? "✓" : stage.status === "conditional" ? "?" : "–"} ${stage.label} (${stage.tool})`);
+    if (plan.estimate) console.log(`  ${plan.estimate}`);
+    const build = !flags["no-build"];
+    if (build && !flags.yes) {
+      if (!prompt) throw new Error("Confirm the build with --yes (it uses one build from your plan).");
+      if (!/^y/i.test((await prompt.ask("Build it now? This uses one build from your plan. [y/N] ")).trim())) { console.log("Not built. Nothing was created."); return; }
+    }
+    const created = await client.createFromDesign({ requirements: result.requirements, architecture: option, designFiles, build });
+    await pullProject(client, created.project.id, directory);
+    console.log(`\nCreated ${created.project.name} (${created.project.id}) in ${directory}.`);
+    if (created.buildError) { console.log(`The build did not start: ${created.buildError}\nStart it later with: tapeo run`); return; }
+    if (!created.run) { console.log("Start the build when ready with: tapeo run"); return; }
+    console.log(`Building (run ${created.run.id}). The first run writes the RTL and testbench, then runs every stage.`);
+    const previous = process.cwd();
+    process.chdir(directory);
+    try {
+      await follow(client, created.project.id, created.run.id);
+      const pulled = await pullProject(client, created.project.id, directory);
+      console.log(`\nPulled ${pulled.pulled.length} generated file(s) into ${directory}. Edit them, then tapeo push --all and tapeo run.`);
+    } finally { process.chdir(previous); }
+  } finally { prompt?.close(); }
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || command === "help" || command === "--help") return usage();
+  if (command === "--version" || command === "version") {
+    console.log(clientVersion);
+    return;
+  }
+  if (command === "login") {
+    const { flags, positional } = parseArguments(rest);
+    const serverUrl = normalizeServerUrl(positional[0] || DEFAULT_SERVER_URL);
+    if (flags.token || process.env.TAPEO_TOKEN) {
+      const token = process.env.TAPEO_TOKEN || await hiddenToken();
+      const client = new TapeoClient(serverUrl, token);
+      await client.projects();
+      await saveLogin(serverUrl, token);
+      console.log(`Connected to ${serverUrl}. Token stored in ${configPath}.`);
+      return;
+    }
+    const signedIn = await signInWithBrowser(serverUrl, `${hostname()} · terminal`, {
+      onCode: ({ userCode, verificationUriComplete }) => {
+        console.log(`Approve this device in your browser:\n  ${verificationUriComplete}\nConfirm the code ${userCode} matches. Waiting…`);
+        openBrowser(verificationUriComplete);
+      }
+    });
+    await saveLogin(signedIn.serverUrl, signedIn.token);
+    console.log(`Signed in to ${signedIn.serverUrl} as "${signedIn.name}". Token stored in ${configPath}; revoke it any time on the Account page.`);
+    return;
+  }
+  if (command === "logout") {
+    await rm(configPath, { force: true });
+    console.log("Signed out on this computer. Revoke the token on the Account page to end its access everywhere.");
+    return;
+  }
+  // The serial monitor talks only to the board, so it needs no sign-in.
+  if (command === "monitor") {
+    const { flags } = parseArguments(rest, ["port", "baud"]);
+    const port = chooseSerialPort(serialCandidates(), typeof flags.port === "string" ? flags.port : undefined);
+    const baud = parseBaud(flags.baud);
+    const serial = openSerialPort(port, baud);
+    console.error(`Connected to ${port} at ${baud} baud. Type a line and press Enter to send it; Ctrl+C stops.`);
+    serial.input.pipe(process.stdout);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (text) => serial.write(text));
+    await new Promise((resolve) => {
+      const stop = () => { serial.close(); resolve(); };
+      process.once("SIGINT", stop);
+      // Ctrl+D at a keyboard stops; piped input just sends and keeps listening.
+      if (process.stdin.isTTY) process.stdin.once("end", stop);
+      serial.input.once("close", stop);
+      serial.input.once("error", (error) => { console.error(`The serial port closed: ${error.message}`); stop(); });
+    });
+    process.stdin.destroy();
+    return;
+  }
+  const client = await configuredClient();
+  const { flags, positional: args } = parseArguments(rest, ["stage", "from", "option", "limit", "board"]);
+  if (command === "new") {
+    await newDesign(client, args[0], path.resolve(args[1] || "."), flags);
+  } else if (command === "ask") {
+    const directory = process.cwd();
+    const projectId = await projectIdFor(client);
+    let question = args.join(" ").trim();
+    if (!question) {
+      const prompt = prompter();
+      if (!prompt) throw new Error('Usage: tapeo ask "<question>"');
+      try { question = (await prompt.ask("Ask the Engineer: ")).trim(); } finally { prompt.close(); }
+      if (!question) throw new Error("No question given.");
+    }
+    const changes = await localChanges(directory).catch(() => null);
+    if (changes && (changes.modified.length || changes.added.length)) console.log(`Note: the Engineer sees the server copy. ${changes.modified.length + changes.added.length} local change(s) are not pushed (tapeo push --all).`);
+    const printer = streamPrinter();
+    process.stdout.write("Engineer: ");
+    const result = await client.askEngineer(projectId, question, (text) => printer.update(text));
+    printer.finish(result.message);
+    if (result.proposedChanges?.length || result.proposedEvaluationPlan) {
+      const proposals = await saveProposals(directory, { question, result });
+      console.log("");
+      showProposals(proposals);
+      if (proposals.changes.some((change) => change.status === "pending")) console.log(`\nApply with: tapeo apply${proposals.changes.length > 1 ? " (or only some: tapeo apply 1 2)" : ""}, then tapeo push --all. Or: tapeo discard`);
+    }
+    if (result.invalidChangeCount) console.log(`(${result.invalidChangeCount} malformed change(s) from the Engineer were left out.)`);
+  } else if (command === "history") {
+    const projectId = await projectIdFor(client);
+    const { messages } = await client.engineerHistory(projectId);
+    for (const message of messages.slice(-Number(flags.limit ?? 10))) console.log(`${message.role === "user" ? "You" : "Engineer"} · ${new Date(message.createdAt).toLocaleString()}\n${message.content}\n`);
+    if (!messages.length) console.log('No Engineer conversation yet. Start one with: tapeo ask "<question>"');
+  } else if (command === "proposals") {
+    showProposals(await loadProposals(process.cwd()));
+  } else if (command === "apply") {
+    const results = await applyProposals(process.cwd(), args.length ? args : "all");
+    for (const result of results) console.log(result.ok ? `Applied ${result.file}${result.deleted ? " (deleted locally; run tapeo rm " + result.file + " to delete it on the server)" : ""}.` : `Not applied${result.file ? ` (${result.file})` : ""}: ${result.message}`);
+    if (results.some((result) => result.ok)) console.log("Review the files, then save them to Tapeo with: tapeo push --all");
+    if (results.some((result) => !result.ok)) process.exitCode = 2;
+  } else if (command === "discard") {
+    await discardProposals(process.cwd());
+    console.log("Proposed changes discarded.");
+  } else if (command === "problems") {
+    const projectId = await projectIdFor(client);
+    const runId = await client.latestRunId(projectId, args[0]);
+    const { files } = await client.project(projectId);
+    const problems = await collectRunProblems(client, projectId, runId, files.map((file) => file.path));
+    for (const problem of problems) console.log(formatProblem(problem));
+    const errors = problems.filter((problem) => problem.severity === "error").length;
+    console.log(problems.length ? `\n${errors} error(s), ${problems.length - errors} warning(s) in run ${runId}.` : `No file-level problems in run ${runId}'s tool logs. See tapeo show for stage results.`);
+  } else if (command === "projects") {
+    const { projects } = await client.projects();
+    for (const project of projects) console.log(`${project.id}\t${project.name}`);
+    if (!projects.length) console.log("No projects yet. Run tapeo create <name> [directory].");
+  } else if (command === "delete") {
+    const directory = process.cwd();
+    const projectId = await projectIdFor(client, args[0]);
+    const { project } = await client.project(projectId);
+    if (!flags.yes) {
+      if (!process.stdin.isTTY) throw new Error(`Deleting "${project.name}" cannot be undone. Confirm with --yes.`);
+      const prompt = prompter();
+      try {
+        console.log(`This deletes "${project.name}" (${project.id}) on ${client.serverUrl} for good: its files, checkpoints, runs, layouts, and Engineer history. A running workflow stops. Local files are kept.`);
+        const typed = (await prompt.ask("Type the project name to confirm: ")).trim();
+        if (typed !== project.name.trim()) { console.log("The name did not match. Nothing was deleted."); return; }
+      } finally { prompt.close(); }
+    }
+    await client.deleteProject(projectId);
+    // A folder bound to the deleted project is unbound, so later commands do not point at it.
+    const bound = await readState(directory).catch(() => null);
+    if (bound?.projectId === projectId && bound.serverUrl === client.serverUrl) await rm(path.join(directory, ".tapeo"), { recursive: true, force: true });
+    console.log(`Deleted "${project.name}".${bound?.projectId === projectId ? " This folder is no longer linked to a Tapeo project; its files are unchanged." : ""}`);
+  } else if (command === "create") {
+    if (!args[0]?.trim()) throw new Error("Usage: tapeo create <name> [directory]");
+    const directory = path.resolve(args[1] || ".");
+    await assertUnbound(directory);
+    const { project } = await client.createProject(args[0].trim());
+    await pullProject(client, project.id, directory);
+    console.log(`Created ${project.name} (${project.id}) in ${directory}. Add RTL and a testbench, then run tapeo push --all.`);
+  } else if (command === "pull") {
+    const bound = await readState(process.cwd()).catch(() => null);
+    const projectId = args[0] ?? (bound && bound.serverUrl === client.serverUrl ? bound.projectId : null);
+    if (!projectId) throw new Error("Usage: tapeo pull <project-id> [directory] [--outputs]");
+    const directory = path.resolve(args[0] ? args[1] || "." : ".");
+    const result = await pullProject(client, projectId, directory);
+    console.log(`Pulled ${result.pulled.length} files. Skipped ${result.skipped.length} generated/large files.`);
+    if (result.conflicts.length) {
+      console.error(`Local changes kept: ${result.conflicts.join(", ")}`);
+      for (const [file, copy] of Object.entries(result.remoteCopies)) console.error(`Compare ${file} with ${copy}`);
+      process.exitCode = 2;
+    }
+    if (flags.outputs) {
+      const outputs = await pullOutputs(client, projectId, directory);
+      console.log(`Outputs: ${outputs.downloaded.length} downloaded, ${outputs.unchanged.length} unchanged (read-only, under generated/ and signoff/).`);
+      for (const item of outputs.skipped) console.log(`  Skipped ${item.path} (${(item.sizeBytes / 1048576).toFixed(1)} MB). Download it with: tapeo download ${item.path}`);
+    }
+  } else if (command === "status") {
+    const changes = await localChanges(process.cwd());
+    if (changes.serverUrl !== client.serverUrl) throw new Error("This folder belongs to another Tapeo server.");
+    const lines = [...changes.modified.map((file) => `  modified  ${file}`), ...changes.added.map((file) => `  new       ${file}`), ...changes.deleted.map((file) => `  deleted   ${file} (run tapeo rm to delete it on the server)`), ...changes.tooLarge.map((file) => `  too large ${file} (over 2 MB; not pushed)`)];
+    console.log(lines.length ? `Local changes:\n${lines.join("\n")}\nPush them with: tapeo push --all` : "No local changes since the last pull or push.");
+    const { runs } = await client.runs(changes.projectId);
+    console.log(runs.length ? `\nLatest run: ${describeRun(runs[0])}` : "\nNo workflow runs yet.");
+  } else if (command === "push") {
+    if (flags.all) {
+      const result = await pushChanges(client, process.cwd());
+      console.log(result.saved.length ? `Saved ${result.saved.length} file(s): ${result.saved.join(", ")}` : "Nothing to push.");
+      for (const conflict of result.conflicts) console.error(`Not pushed, server changed: ${conflict.path}. ${conflict.message}`);
+      for (const failure of result.failed) console.error(`Not pushed: ${failure.path}: ${failure.message}`);
+      if (result.deletedLocally.length) console.log(`Deleted locally, still on the server: ${result.deletedLocally.join(", ")} (use tapeo rm).`);
+      if (result.conflicts.length || result.failed.length) process.exitCode = 2;
+    } else {
+      if (!args.length) throw new Error("Usage: tapeo push <project-relative-path...> or tapeo push --all");
+      for (const file of args) {
+        const result = await pushProjectFile(client, process.cwd(), file);
+        console.log(`Saved ${result.path} (${result.sha256.slice(0, 12)}).`);
+      }
+    }
+  } else if (command === "rm") {
+    if (!args[0]) throw new Error("Usage: tapeo rm <project-relative-path>");
+    await removeProjectFile(client, process.cwd(), args[0]);
+    console.log(`Deleted ${args[0]} on the server and locally.`);
+  } else if (command === "mv") {
+    if (!args[0] || !args[1]) throw new Error("Usage: tapeo mv <from> <to>");
+    await moveProjectFile(client, process.cwd(), args[0], args[1]);
+    console.log(`Renamed ${args[0]} to ${args[1]}.`);
+  } else if (command === "download") {
+    if (!args[0]) throw new Error("Usage: tapeo download <project-path> [destination]");
+    const projectId = await projectIdFor(client);
+    const result = await downloadFile(client, projectId, args[0], args[1] || path.basename(args[0]));
+    console.log(`Downloaded ${result.path} (${result.bytes.toLocaleString()} bytes) to ${result.destination}.`);
+  } else if (command === "run") {
+    const projectId = await projectIdFor(client, args[0]);
+    const scope = stageScope({ stage: flags.stage, from: flags.from, aiRepairs: !flags["no-ai-repairs"] });
+    const { run } = await client.run(projectId, scope);
+    console.log(`Queued workflow ${run.id}${scope ? ` (${scope.from === scope.to ? `${scope.from} only` : `${scope.from} → ${scope.to}`})` : " (full run: uses one build)"}.`);
+    if (flags.watch) await follow(client, projectId, run.id);
+    else console.log("Follow it with: tapeo watch");
+  } else if (command === "runs") {
+    const projectId = await projectIdFor(client, args[0]);
+    const { runs } = await client.runs(projectId);
+    for (const run of runs) console.log(describeRun(run));
+    if (!runs.length) console.log("No workflow runs yet.");
+  } else if (command === "watch") {
+    const projectId = await projectIdFor(client);
+    await follow(client, projectId, await client.latestRunId(projectId, args[0]));
+  } else if (command === "show") {
+    const projectId = await projectIdFor(client);
+    console.log(describeRunDetail(await client.runDetail(projectId, await client.latestRunId(projectId, args[0]))));
+  } else if (command === "logs") {
+    if (!args[0]) throw new Error("Usage: tapeo logs <tool-run-id> (ids are listed by tapeo show)");
+    const projectId = await projectIdFor(client);
+    const { toolRun } = await client.toolRunLog(projectId, args[0]);
+    console.log(`${toolRun.tool} · ${toolRun.status} · ${new Date(toolRun.createdAt).toLocaleString()}\n${toolRun.summary}\n`);
+    if (toolRun.stdout) console.log(`--- stdout ---\n${toolRun.stdout}`);
+    if (toolRun.stderr) console.log(`--- stderr ---\n${toolRun.stderr}`);
+    if (!toolRun.stdout && !toolRun.stderr) console.log("This tool run saved no output.");
+  } else if (command === "goals") {
+    const projectId = await projectIdFor(client, args[0]);
+    console.log(describeGoals((await client.goals(projectId)).report));
+  } else if (command === "cancel") {
+    const projectId = await projectIdFor(client);
+    let runId = args[0];
+    if (!runId) {
+      const { runs } = await client.runs(projectId);
+      runId = runs.find((run) => ACTIVE_RUN_STATUSES.includes(run.status))?.id;
+      if (!runId) throw new Error("No queued or running workflow to cancel.");
+    }
+    const { run } = await client.cancelRun(projectId, runId);
+    console.log(`Cancelled ${run.id}. A tool step already running finishes first; finished stages keep their results.`);
+  } else if (command === "flash") {
+    const directory = process.cwd();
+    const projectId = await projectIdFor(client);
+    const { files } = await client.project(projectId);
+    const bitstream = chooseBitstream(files, flags.board);
+    const executable = openFpgaLoaderExecutable();
+    if (!openFpgaLoaderAvailable(executable)) throw new Error(OPENFPGALOADER_INSTALL);
+    const local = await downloadBitstream(client, projectId, bitstream, directory);
+    console.log(`Programming the ${bitstream.label} with ${path.relative(directory, local)}${flags.flash ? " (writing to flash)" : ""}…`);
+    const result = spawnSync(executable, flashArguments(bitstream, local, { flash: Boolean(flags.flash) }), { stdio: "inherit" });
+    if (result.error || result.status !== 0) throw new Error("openFPGALoader could not program the board. Check the USB cable and that no other program is using the board; its messages are above.");
+    console.log(`Programmed the ${bitstream.label}.`);
+  } else if (command === "open") {
+    const projectId = await projectIdFor(client, args[0]);
+    console.log(`${client.serverUrl}/?project=${encodeURIComponent(projectId)}`);
+  } else usage();
+}
+
+main().catch((error) => { console.error(`Tapeo: ${error.message}`); process.exitCode = process.exitCode || 1; });

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "tapeo-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Terminal client for Tapeo: edit hardware projects locally, run the server's EDA workflow, read results, and work with the AI Architect and Engineer.",
+  "keywords": [
+    "tapeo",
+    "hardware",
+    "rtl",
+    "verilog",
+    "systemverilog",
+    "eda",
+    "asic",
+    "fpga",
+    "cli"
+  ],
+  "homepage": "https://tapeo.net",
+  "license": "UNLICENSED",
+  "author": "Tapeo",
+  "type": "module",
+  "bin": {
+    "tapeo": "./cli/tapeo.mjs"
+  },
+  "files": [
+    "cli",
+    "shared",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}