tapeo-cli 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2026 Tapeo (https://tapeo.net). All rights reserved.
+
+This software is proprietary. You may install and use it to work with Tapeo
+services. You may not copy, modify, redistribute, sublicense, or create
+derivative works of it, except as permitted by law, without written permission.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# Tapeo local clients (developer preview)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A terminal client and a VS Code extension for the same Tapeo projects as the web app. They call the same server, file storage, workflow queue, and plan allowances as the browser, through the token-authenticated API under `/api/client/v1`. They are a developer preview: installed from this repository. Publishing on npm (`tapeo-cli`) and the VS Code Marketplace (`tapeo.tapeo-vscode`) is prepared but not done; see [`docs/RELEASING.md`](../docs/RELEASING.md).
+
+The edit → run → results loop works without the browser: push your files, start a run, follow it stage by stage, and read stage results, tool logs, and goal results. You can also start a new design with the Architect, ask the AI Engineer and apply its proposed changes locally, and see tool errors on the lines they name. The 2D/3D layout views, Evaluation-plan review, and Architect image/PDF attachments stay in the web workspace.
+
+The server needs migrations `0008_client_tokens` and `0009_device_authorization` (`npx prisma migrate deploy`; the Docker deployment applies them on start).
+
+## Sign in
+
+```sh
+npm install -g ./clients          # or: npm run tapeo -- <command> from the repository root
+                                  # once published: npm install -g tapeo-cli
+tapeo login                       # https://tapeo.net; or: tapeo login https://your-own-server
+```
+
+`tapeo login` opens `/device?code=ABCD-EFGH` in your browser. Check that the code matches, approve the device, and the terminal finishes signing in. Only a digest of the device code is stored, and no token exists until you approve. The device gets its own token: it expires after 90 days, appears on **Account → VS Code and terminal access**, and can be revoked there. Without a browser, create a token on that page and use `tapeo login <url> --token` (hidden prompt). The sign-in is saved in `~/.config/tapeo/client.json` (mode 0600); `tapeo logout` removes it. `TAPEO_URL` and `TAPEO_TOKEN` override it for automation. `TAPEO_NO_BROWSER=1` makes `tapeo login` only print the approval address instead of opening a browser. Remote servers must use HTTPS; HTTP is accepted for localhost only.
+
+## Terminal
+
+```sh
+tapeo projects                         # your projects
+tapeo create "My sensor" ./my-sensor   # new empty project, bound to the folder
+tapeo pull PROJECT_ID ./existing       # or bind an existing project
+cd ./my-sensor
+tapeo status                           # what changed locally, and the latest run
+tapeo push --all                       # push every modified and new source file
+tapeo run --watch                      # full run; follow it, then show results and goals
+tapeo run --stage drc                  # rerun one stage on the saved files
+tapeo run --from synthesis             # rerun a stage and every later one
+tapeo runs                             # recent runs and their status
+tapeo watch                            # follow the latest run until it ends, then show results
+tapeo show                             # stage results, AI changes, tool runs of the latest run
+tapeo logs TOOL_RUN_ID                 # a tool run's saved output (ids from tapeo show)
+tapeo goals                            # the latest goal report
+tapeo cancel                           # cancel the active run
+tapeo pull --outputs                   # also download tool outputs (read-only)
+tapeo download generated/layout/top.openroad.gds
+tapeo rm rtl/old.sv                    # delete on the server and locally
+tapeo mv rtl/a.sv rtl/core/a.sv        # rename
+tapeo open                             # the project's web address
+tapeo --version                        # this client's version (tapeo help lists every command)
+```
+
+### AI
+
+```sh
+tapeo new "A sensor that warns when a tank is full" ./tank   # design with the Architect, then build
+tapeo new "Wrap my FIFO" . --from-files                        # start from the RTL in this folder
+tapeo ask "Why does the counter not wrap at 15?"                # ask the Engineer (answer streams)
+tapeo proposals                                                 # its proposed changes, as diffs
+tapeo apply              # apply all of them to local files (or: tapeo apply 1 3)
+tapeo push --all         # then save them in Tapeo
+tapeo discard            # or forget them
+tapeo history            # the Engineer conversation, shared with the browser (--limit N, default 10)
+tapeo problems           # tool errors and warnings of the latest run, as file:line:col
+```
+
+`tapeo new` asks the Architect's clarifying questions and lets you pick an option when run in a terminal. For scripts, `--auto-answers` answers "Not sure — you choose", `--option N` picks a design, `--yes` confirms the build (one build from your plan), and `--no-build` creates the project without building. After the build, the generated files are pulled into the folder. The Architect conversation is not saved on the server; the project keeps the chosen requirements and design.
+
+The Engineer reads the saved server copy of your files (`tapeo ask` warns when local edits are not pushed). Its proposed changes are kept in `.tapeo/proposals.json` until you apply or discard them, and a new answer with changes replaces them. Applying follows the browser's rules: a new file must not exist yet, and the code being replaced must occur exactly once. A change that no longer fits is marked failed with the reason and can be retried after you fix the file. Changes to tool outputs (`generated/`, `signoff/`) or paths outside the project are refused. Deleting a file applies locally; `tapeo rm` deletes it on the server. If the Engineer also proposed an evaluation plan, review it in the web workspace.
+
+`tapeo problems [run-id]` reads the run's tool logs and lists file-level errors from every tool run, plus warnings from tool runs that failed. It recognizes Verilator, Icarus Verilog, Yosys, and Tcl script locations and matches log paths to project files by their ending. Messages without a project file and line stay in `tapeo logs`.
+
+Stages: `simulation`, `synthesis`, `timing`, `physical`, `post-route-timing`, `drc`, `extraction`, `erc`, `lvs`. `--no-ai-repairs` turns off AI repairs for a stage run. A full run uses one build from your plan; a stage run does not. `tapeo run --watch` exits with code 3 when the run fails.
+
+## VS Code
+
+Run `npm run build:vscode`, open `clients/vscode` in VS Code, and press F5; or run `npm run package:vscode` and install `clients/vscode/tapeo-vscode.vsix` with **Extensions: Install from VSIX...**. In the Command Palette:
+
+- **Tapeo: Connect to Server**: sign in with your browser (recommended) or paste a token. The token is kept in VS Code SecretStorage. **Tapeo: Sign Out** removes it.
+- **Create Project** / **Pull Project Files** bind the open folder; **Pull Tool Outputs (read-only)** adds tool outputs.
+- **Show Local Changes**, **Push Current File**, **Push All Changes**, **Delete Current File on the Server**.
+- **Run Workflow** (full run, one stage, or from a stage). The status bar follows the run; when it ends, a notification offers the details, the goals, or the project in the browser.
+- **Show Workflow Runs**, **Show Run Details**, **Open a Tool Log**, **Show Goal Results**, **Cancel Workflow**, **Open Project in Browser**.
+- **New Design with the Architect** (in an empty folder): the Architect's questions appear as quick picks with "Not sure — you choose", then the design options and the build plan; **Build** creates the project, starts the first build, and pulls the generated files when it ends.
+- **Open AI Engineer** opens the **Tapeo Engineer** panel beside the editor: the project conversation, streamed answers, and the proposed changes with **Review** (a side-by-side diff), **Apply**, **Apply all**, and **Discard**. **Ask the AI Engineer**, **Review Proposed Changes**, **Apply All Proposed Changes**, and **Discard Proposed Changes** do the same from the Command Palette. Applying is refused while the file has unsaved edits; push afterwards.
+- **Show Tool Problems**: the latest run's tool errors and warnings in the Problems panel. This also happens automatically when a run the status bar follows ends, and starting a run clears them.
+
+The setting `tapeo.serverUrl` holds the server (Connect to Server sets it; remote servers must use HTTPS).
+
+In a bound folder, the status bar shows the latest run when VS Code starts and follows it if it is still running.
+
+## How files are kept safe
+
+- `.tapeo/state.json` records the project id, the server, and the SHA-256 of each file as last pulled or pushed. It holds no token and is ignored by Git.
+- Pull skips `generated/`, `signoff/`, and files over 2 MB, never overwrites a local edit, and reports conflicts. When both sides changed, the server copy is saved under `.tapeo/conflicts/` for comparison.
+- Push (one file or `--all`) sends each file with the hash it was based on. If the server copy changed meanwhile, that file is refused (HTTP 409), the local edit is kept, and the server copy is saved under `.tapeo/conflicts/`; other files still push. New files are found by source extension (`.sv`, `.v`, `.vhd`, `.sdc`, `.tcl`, `.hex`, `.mem`, `.c`, `.h`, `.S`, `.ld`, and similar) outside `generated/`, `signoff/`, hidden folders, and build folders.
+- Deleting a file locally does not delete it on the server; `tapeo rm` does, and only the version last pulled.
+- Tool outputs (`generated/`, `signoff/`) are read-only: they download with mode 0444 and are never pushed. Outputs over 25 MB (a layout) are listed for `tapeo download`.
+- An expired or revoked sign-in asks you to sign in again; an unreachable server reports a network error or timeout. A run is refused before using a build when no workflow worker is connected. None of these change local files.
+
+## Workflow runs
+
+A run from a local client executes the saved files, including edits just pushed; it never regenerates HDL. It uses the same queue, checkpoints, plan limits, and usage accounting as the browser (`lib/workflow-runs.ts`). Cancelling stops a run before its next stage; a tool step already running finishes first, and finished stages keep their results. A full run still counts as the build it started as.
+
+## Tests
+
+- `tests/client-ai.test.ts`: streamed answers, clarification wording, problem extraction for each tool's format, proposals (apply rules, retry, refusals, discard), design-file limits, the client API, and the real `tapeo` command for `ask`/`proposals`/`apply`/`history`/`problems`/`discard` and `new` (questions, option, plan, build, follow, pull, bound-folder refusal).
+- `npm test` includes `tests/client-workflow.test.ts` (shared client: sign-in, watching, status, push-all, rm/mv, outputs, formatting), `tests/client-sync.test.ts`, and `tests/client-cli.test.ts` (the real `tapeo` command against a fake server, from sign-in to cancel).
+- `npm run test:e2e` checks the server side against a real database: browser device approval, run details, tool logs, goals, cancel (client and browser), raw download, delete with its conflict check, the Engineer and Architect routes' sign-in, validation, and ownership checks, the build plan, and creating a project from a design (with "build" refused, and no run recorded, when no worker is connected). It does not call the AI.
+- `npm run test:vscode` drives a real VS Code Extension Development Host through connect, create, a new design with the Architect (and its refusal in a bound folder), pull, push, push all, run, tool problems in the Problems panel, run details, goals, the Engineer (ask, review diff, apply refused for an unsaved file, apply, push), and conflict, worker, and sign-in failures, against a local fixture server. `TAPEO_VSCODE_VSIX="$PWD/clients/vscode/tapeo-vscode.vsix" npm run test:vscode` repeats it with the packaged extension. VS Code must be installed; `TAPEO_VSCODE_BIN` selects another `code` executable.

package/cli/tapeo.mjs

@@ -0,0 +1,444 @@
+#!/usr/bin/env node
+import { spawn } 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 { 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 (developer preview)
+
+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 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
+
+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 <server-url>` first, 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;
+  }
+  const client = await configuredClient();
+  const { flags, positional: args } = parseArguments(rest, ["stage", "from", "option", "limit"]);
+  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 === "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 === "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.3.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"
+  }
+}