@protoboardai/cli 0.0.0-stage → 0.2.1

package/src/layout.ts

@@ -0,0 +1,166 @@
+/**
+ * `protoboard layout` (PB-1007): the diagram's layout measured, level by
+ * level, headless, and written to the display file when asked.
+ *
+ * The numbers are what the viewer draws (`@deltarobotics/uhd-viewer/headless`:
+ * the same layout and line routing): link crossings, overlapping boxes, the
+ * strip (the most cards one straight line across or down passes through), the
+ * aspect ratio, lines under cards. With --apply each level is laid out afresh
+ * (the viewer's automatic layout); with --tidy the saved arrangement is the
+ * starting point. Pinned cards keep their places. A level is written only when
+ * the result reads better than what is there (--force writes it anyway).
+ *
+ * `check` adds the findings of the levels of modules (not the boards' sheets,
+ * which `layout` reports) as PB_DIAGRAM_LAYOUT info diagnostics.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { uhdBundle, type Project, type ProjectDiagnostic } from "@protoboardai/core";
+import { DISPLAY_SCHEMA, formatDisplay, type DisplayFile, type LevelLayout } from "./dev/layout.js";
+
+type Headless = typeof import("@deltarobotics/uhd-viewer/headless");
+type LayoutMetrics = import("@deltarobotics/uhd-viewer/headless").LayoutMetrics;
+type LayoutFinding = import("@deltarobotics/uhd-viewer/headless").LayoutFinding;
+type UhdBundle = Parameters<Headless["measureLevel"]>[0];
+
+export interface LayoutOptions {
+  /** One level (an instance path; "" is the top). Default: every level. */
+  level?: string;
+  /** Write: "default" lays the level out afresh, "tidy" fixes the saved arrangement. */
+  apply?: "default" | "tidy";
+  /** Cards that keep their places (added to the level's saved `pinned`). */
+  pin?: string[];
+  /** Write even when the result does not read better. */
+  force?: boolean;
+}
+
+export interface LevelReport {
+  level: string;
+  label: string;
+  board: boolean;
+  /** The level has a saved layout (else the viewer lays it out automatically). */
+  saved: boolean;
+  metrics: LayoutMetrics;
+  findings: LayoutFinding[];
+  /** With --apply or --tidy: the proposal's metrics and findings, and whether it was written. */
+  proposed?: { mode: "default" | "tidy"; metrics: LayoutMetrics; findings: LayoutFinding[]; better: boolean; written: boolean; pinned: string[] };
+}
+
+export interface LayoutReport {
+  /** The display file, relative to the project. */
+  file: string;
+  levels: LevelReport[];
+  /** Levels written to the display file. */
+  written: string[];
+  /** Levels with a warning after this run (what --check fails on). */
+  warnings: number;
+}
+
+async function headless(): Promise<Headless> {
+  return (await import("@deltarobotics/uhd-viewer/headless")) as Headless;
+}
+
+export function displayPath(p: Project): string {
+  return join(p.root, p.config.display ?? ".protoboard/display.json");
+}
+
+const slim = (m: LayoutMetrics): LayoutMetrics => ({ ...m, detail: { overlaps: m.detail.overlaps.slice(0, 20), underCards: m.detail.underCards.slice(0, 20) } });
+
+export async function runLayout(p: Project, opts: LayoutOptions = {}): Promise<LayoutReport> {
+  const h = await headless();
+  const file = displayPath(p);
+  const previous = existsSync(file) ? readFileSync(file, "utf8") : undefined;
+  const display: DisplayFile = previous ? (JSON.parse(previous) as DisplayFile) : { schema: DISPLAY_SCHEMA };
+  const bundle = (await uhdBundle(p)) as unknown as UhdBundle;
+  const all = h.diagramLevels(bundle);
+  const levels = opts.level === undefined ? all : all.filter((l) => l.level === opts.level);
+  if (!levels.length) throw new Error(`no level "${opts.level}"; the levels are ${all.map((l) => (l.level ? `"${l.level}"` : '"" (the top)')).join(", ")}`);
+  const out: LevelReport[] = [];
+  const written: string[] = [];
+  for (const lv of levels) {
+    const now = h.measureLevel(bundle, lv.level);
+    const report: LevelReport = { level: lv.level, label: lv.label, board: lv.board, saved: now.saved, metrics: slim(now.metrics), findings: now.findings };
+    if (opts.apply) {
+      const pr = h.proposeLevel(bundle, lv.level, { mode: opts.apply, pinned: opts.pin });
+      // a level with no saved layout already draws the automatic layout, and keeps following the model as it
+      // changes: it is saved only when asked (--force), or when cards are pinned on it
+      const write = opts.force || (pr.better && now.saved);
+      if (write) {
+        display.schema ??= DISPLAY_SCHEMA;
+        display.diagram ??= {};
+        display.diagram.layouts ??= {};
+        display.diagram.layouts[lv.level] = pr.layout as LevelLayout;
+        written.push(lv.level);
+      }
+      report.proposed = { mode: opts.apply, metrics: slim(pr.after.metrics), findings: pr.after.findings, better: pr.better, written: write, pinned: pr.layout.pinned ?? [] };
+    }
+    out.push(report);
+  }
+  if (written.length) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, formatDisplay(display, previous));
+  }
+  const warnings = out.filter((r) => ((r.proposed?.written ? r.proposed.findings : r.findings) ?? []).some((f) => f.severity === "warning")).length;
+  return { file: relative(p.root, file) || file, levels: out, written, warnings };
+}
+
+const name = (r: { level: string; label: string }) => (r.level ? `${r.level} (${r.label})` : `top level (${r.label})`);
+const line = (m: LayoutMetrics) =>
+  `${m.cards} cards, ${m.links} lines: ${m.crossings} crossings, ${m.overlaps} overlaps, longest ${m.stripAxis} ${m.strip}, aspect ${m.aspect}, ${m.underCards} under cards`;
+
+export function formatLayout(r: LayoutReport): string {
+  const out: string[] = [];
+  for (const l of r.levels) {
+    out.push(`${name(l)}${l.board ? " [board]" : ""}: ${l.saved ? "saved layout" : "automatic layout"}`);
+    out.push(`  now:      ${line(l.metrics)}`);
+    for (const f of l.findings) out.push(`    ${f.severity === "warning" ? "!" : "·"} ${f.message}`);
+    // a board's sheet is laid out as a schematic; past a few dozen parts it reads better as sub-modules (model, not display)
+    if (l.board && l.findings.some((f) => f.severity === "warning") && l.metrics.cards > 24)
+      out.push(`    → a board of ${l.metrics.cards} parts reads better split into sub-modules by function (power, processor, sensors, outputs), each a level of its own: model them, the diagram follows`);
+    if (l.proposed) {
+      const p = l.proposed;
+      out.push(`  ${p.mode === "tidy" ? "tidied:  " : "default: "} ${line(p.metrics)}${p.pinned.length ? ` (pinned: ${p.pinned.join(", ")})` : ""}`);
+      for (const f of p.findings) out.push(`    ${f.severity === "warning" ? "!" : "·"} ${f.message}`);
+      out.push(`  ${p.written ? `written to ${r.file}` : !l.saved ? "not written: the level has no saved layout, so the viewer draws this already (--force saves it)" : "not written: it does not read better than what is there (--force writes it)"}`);
+    }
+  }
+  out.push(
+    "",
+    r.written.length
+      ? `wrote ${r.written.length} level${r.written.length === 1 ? "" : "s"} to ${r.file}; look at them in the viewer (protoboard dev) before you call it done`
+      : r.warnings
+        ? `${r.warnings} level${r.warnings === 1 ? " has" : "s have"} something to fix: move the cards (protoboard dev, or ${r.file}), or try --apply or --tidy`
+        : "nothing to fix",
+  );
+  return out.join("\n");
+}
+
+/**
+ * Layout findings for `check`: the levels of modules only (a board's sheet is
+ * reported by `protoboard layout`), as info, one diagnostic per level.
+ */
+export async function layoutDiagnostics(p: Project): Promise<ProjectDiagnostic[]> {
+  if (!p.rootDef) return [];
+  try {
+    const h = await headless();
+    const bundle = (await uhdBundle(p)) as unknown as UhdBundle;
+    const out: ProjectDiagnostic[] = [];
+    for (const lv of h.diagramLevels(bundle)) {
+      if (lv.board) continue;
+      const m = h.measureLevel(bundle, lv.level);
+      const warn = m.findings.filter((f) => f.severity === "warning");
+      if (!warn.length) continue;
+      out.push({
+        code: "PB_DIAGRAM_LAYOUT",
+        severity: "info",
+        message: `the diagram's ${lv.level ? `level "${lv.level}"` : "top level"} is hard to read: ${warn.map((f) => f.message).join("; ")}. Run \`protoboard layout${lv.level ? ` ${lv.level}` : ""}\`, and fix it (--apply, --tidy, or by moving cards) before you call the build done`,
+        entity: lv.level ? { kind: "instance", id: lv.level } : { kind: "project", id: p.name },
+        validator: "protoboard/layout",
+      });
+    }
+    return out;
+  } catch {
+    // no viewer build (a stack without it): no layout findings
+    return [];
+  }
+}

package/src/mcp/instructions.ts

@@ -0,0 +1,60 @@
+/**
+ * What an agent is told on connecting to the Protoboard MCP server (PB-930,
+ * docs/specs/agents-and-mcp.md §2.2). Claude Code cuts a server's
+ * instructions, and each tool's description, at 2 048 characters: the text
+ * stays under that (a test checks it), with what matters most first.
+ */
+
+/** The limit Claude Code applies to instructions and to each tool description. */
+export const DESCRIPTION_LIMIT = 2048;
+
+export function serverInstructions(templates: string[]): string {
+  const list = templates.length ? templates.join(", ") : "none installed";
+  return `Protoboard designs hardware as code: a project is a folder whose system (modules, parts, interfaces, links, harnesses, artifacts) is written in UHD, the open Unified Hardware Description (*.uhd.ts, package @deltarobotics/uhd) and checked, built and released with the \`protoboard\` CLI. These tools run that CLI.
+
+This is NOT the Protoboard alpha web app. There is no browser board to open or connect to; do not look for one. Work in the project's files and with these tools; people see the result in the Protoboard VS Code extension.
+
+Start with project_status: whether the folder is a project, what is installed, whether the user is signed in.
+
+No project yet: project_init (templates: ${list}; none gives a blank project with ext-hardware). Projects use the Protoboard installed on this machine: never run \`npm install\` (only for a project-local stack the user asked for). Add an extension with \`protoboard extensions add <name>\`.
+
+In a project, read AGENTS.md first (inside a larger repository it says what the workspace's guidance governs), then the build-a-project skill (skill_read), which gives the order of work and the skill for each stage, and the UHD reference in node_modules/@deltarobotics/uhd/docs. Run project_check before and after every change.
+
+Rules:
+- Cite a source for every number; mark assumptions.
+- Never edit generated files (.protoboard/ except display.json, release/) or parts/catalog; a variant is a new part in parts/local.
+- Boards follow the circuit-board skill; never \`tsci\` on a project's board. Another PCB tool only when that path fails, and say so to the user first.
+- When interfaces do not fit, stop and check the datasheet; never invent wires or drop functions.
+- Never put a sign-in, token or key in a file; when a tool says a sign-in is needed, ask the user to sign in; the result says how.
+- These tools never publish, order or upload. A passing check validates the model, not physical readiness.`;
+}
+
+/** The longer guide, as a resource: the instructions and the commands an agent runs in a shell. */
+export function guideText(templates: string[]): string {
+  return `# Working with Protoboard
+
+${serverInstructions(templates)}
+
+## Commands to run in a shell (not tools)
+
+The command is \`protoboard …\`. If the shell does not find it: a new VS Code terminal (the extension adds it), \`~/.protoboard/bin/protoboard\` (\`%USERPROFILE%\\.protoboard\\bin\\protoboard.cmd\` on Windows), or in a project \`./node_modules/.bin/protoboard\`. Never run a bare \`npx protoboard\`: npx would fetch an unrelated public package of that name. Never run \`npm install\` to set a project up or to add something: projects use the Protoboard installed on this machine.
+
+- \`protoboard stack link\` in a project whose packages are missing: links them to the Protoboard installed on this machine (no npm).
+- \`protoboard extensions add <name>\`: adds an extension (ext-tscircuit, ext-enclosure-cad, …) and exports its skills.
+- Signing in is the user's to do, never yours: in VS Code the command "Protoboard: Sign In to Protoboard Cloud" (or the account on the page "Protoboard: Open Settings"); in a terminal \`protoboard login\` (a browser, or a code with --device).
+- \`protoboard doctor\`: extensions, external tools and runtimes; \`protoboard tools install <cad|circuit|all>\` installs a runtime.
+- \`protoboard skills read <name>\`: a skill's text, as skill_read gives it.
+- \`protoboard release\`: writes the Manufacturing Package; release_check says first whether it would be refused.
+- \`protoboard --help\`: every command. Add \`--format json\` for machine output.
+
+## The order of work
+
+1. project_status.
+2. No project: project_init.
+3. Read AGENTS.md and the build-a-project skill; write requirements in docs/brief.md.
+4. Find parts with parts_search, add them with parts_add; research a part the library lacks into parts/local with the parts skills.
+5. Compose the system in src/*.uhd.ts; project_check after each change; project_inspect to see what resolved.
+6. project_layout: lay the diagram out by function, compact, and fix what it reports before you call the build done.
+7. project_build, bom, then release_check.
+`;
+}

package/src/mcp/server.ts

@@ -0,0 +1,215 @@
+/**
+ * `protoboard mcp`: the Protoboard MCP server over stdio (PB-930,
+ * docs/specs/agents-and-mcp.md §2). It tells an agent what Protoboard is
+ * (the instructions) and gives it the CLI's commands as tools (tools.ts).
+ * It works with or without a project in the folder it is started in.
+ *
+ * stdout carries the protocol and nothing else; anything to say goes to
+ * stderr, where clients keep a server's log.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, lstatSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { RootsListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { findProjectRoot, listTemplates } from "@protoboardai/core";
+import { guideText, serverInstructions } from "./instructions.js";
+import { cliTools, type CliRun, type ToolContext, type ToolOutcome, type ToolSpec } from "./tools.js";
+
+/** The CLI that carries this server. */
+export const SELF_CLI = fileURLToPath(new URL("../../bin/protoboard.mjs", import.meta.url));
+const SELF_VERSION = (JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")) as { version: string }).version;
+
+/** A result longer than this goes to a file; the tool returns where (Claude Code stops a result at 25 000 tokens). */
+export const RESULT_LIMIT = 40_000;
+
+/** The `@protoboardai/cli` installed for a folder: the nearest `node_modules` from it up, as Node resolves it. */
+export function projectCli(dir: string): string | undefined {
+  for (let d = resolve(dir); ; d = dirname(d)) {
+    const bin = join(d, "node_modules", "@protoboardai", "cli", "bin", "protoboard.mjs");
+    if (existsSync(bin)) return bin;
+    if (dirname(d) === d) return undefined;
+  }
+}
+
+function runCli(entry: string, args: string[], cwd: string, timeoutMs: number): Promise<CliRun> {
+  return new Promise((done) => {
+    const child = spawn(process.execPath, [entry, ...args], { cwd, env: process.env, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    const timer = setTimeout(() => {
+      stderr += `\nprotoboard: stopped after ${Math.round(timeoutMs / 1000)} s`;
+      child.kill();
+    }, timeoutMs);
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      done({ code: null, stdout, stderr: `${stderr}\n${e.message}` });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      done({ code, stdout, stderr });
+    });
+  });
+}
+
+const SPILL_PREFIX = "protoboard-mcp-";
+const SPILL_KEEP_MS = 24 * 60 * 60 * 1000;
+let spill: string | undefined;
+
+/**
+ * Remove the folders of earlier servers of this user that are more than a
+ * day old (and the one folder earlier versions shared). Only real folders
+ * this user owns: the system's temporary folder is shared on Linux.
+ */
+export function sweepSpill(now = Date.now(), tmp = tmpdir()): void {
+  let names: string[];
+  try {
+    names = readdirSync(tmp);
+  } catch {
+    return;
+  }
+  const uid = process.getuid?.();
+  for (const n of names) {
+    if (n !== "protoboard-mcp" && !n.startsWith(SPILL_PREFIX)) continue;
+    const dir = join(tmp, n);
+    try {
+      const s = lstatSync(dir);
+      if (!s.isDirectory() || dir === spill || (uid !== undefined && s.uid !== uid) || now - s.mtimeMs < SPILL_KEEP_MS) continue;
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // someone else's, or gone already
+    }
+  }
+}
+
+/** This server's own folder for results too long to return: made for this user only (0700), with a name no one can prepare. */
+function spillDir(): string {
+  if (!spill || !existsSync(spill)) spill = mkdtempSync(join(tmpdir(), SPILL_PREFIX));
+  return spill;
+}
+
+/** A tool's outcome as an MCP result: JSON text, moved to a file when it would flood the agent's context. */
+export function toResult(name: string, o: ToolOutcome): { content: { type: "text"; text: string }[]; isError?: boolean } {
+  let text = typeof o.data === "string" ? o.data : JSON.stringify(o.data, null, 2);
+  if (text.length > RESULT_LIMIT) {
+    // a project's BOM or model: readable by this user only, and removed by a later server once it is a day old
+    const file = join(spillDir(), `${name}-${Date.now()}.${typeof o.data === "string" ? "md" : "json"}`);
+    writeFileSync(file, text, { mode: 0o600 });
+    text = JSON.stringify({ truncated: true, characters: text.length, file, note: "The whole result is in `file`: read the part you need (or query it with jq). Its start follows.", start: text.slice(0, 6000) }, null, 2);
+  }
+  return { content: [{ type: "text", text }], ...(o.isError ? { isError: true } : {}) };
+}
+
+export interface ServerOptions {
+  /** The folder tools work in when they are given none (default: PROTOBOARD_PROJECT_DIR, the client's first root, the process's folder). */
+  cwd?: string;
+  /** More tools beside the CLI's (the seam for a bridge to a VS Code window, §7). */
+  tools?: ToolSpec[];
+}
+
+/** The server, not yet connected to a transport. */
+export function createServer(options: ServerOptions = {}): McpServer {
+  sweepSpill();
+  const templates = listTemplates().map((t) => t.id);
+  const about = serverInstructions(templates);
+  const server = new McpServer({ name: "protoboard-stack", title: "Protoboard Stack", version: SELF_VERSION }, { instructions: about });
+
+  let rootDir: string | undefined;
+  const base = async (): Promise<string> => {
+    if (options.cwd) return options.cwd;
+    if (process.env.PROTOBOARD_PROJECT_DIR) return resolve(process.env.PROTOBOARD_PROJECT_DIR);
+    if (rootDir === undefined && server.server.getClientCapabilities()?.roots) {
+      try {
+        const first = (await server.server.listRoots()).roots.find((r) => r.uri.startsWith("file:"));
+        rootDir = first ? fileURLToPath(first.uri) : "";
+      } catch {
+        rootDir = "";
+      }
+    }
+    return rootDir || process.cwd();
+  };
+  // a client that changes its roots says so: it is asked again at the next call
+  server.server.setNotificationHandler(RootsListChangedNotificationSchema, () => {
+    rootDir = undefined;
+  });
+
+  const ctx: ToolContext = {
+    dir: async (given) => (given ? (isAbsolute(given) ? given : resolve(await base(), given)) : base()),
+    cliFor: (dir) => {
+      const own = projectCli(dir);
+      return own ? { entry: own, from: "project" } : { entry: SELF_CLI, from: "server" };
+    },
+    cli: (dir, args, o) => runCli(ctx.cliFor(dir).entry, args, dir, o?.timeoutMs ?? 180_000),
+    version: SELF_VERSION,
+    about,
+  };
+
+  for (const spec of [...cliTools(templates), ...(options.tools ?? [])]) {
+    server.registerTool(spec.name, { title: spec.title, description: spec.description, inputSchema: spec.input, annotations: { title: spec.title, ...spec.annotations } }, async (args: Record<string, unknown>) => {
+      try {
+        const dir = typeof args.dir === "string" ? await ctx.dir(args.dir) : undefined;
+        if (dir && spec.name !== "project_init" && !existsSync(dir)) return toResult(spec.name, { data: { error: `no folder ${dir}` }, isError: true });
+        return toResult(spec.name, await spec.handler(args as never, ctx));
+      } catch (e) {
+        return toResult(spec.name, { data: { error: (e as Error).message }, isError: true });
+      }
+    });
+  }
+
+  server.registerResource("guide", "protoboard://guide", { title: "Working with Protoboard", description: "What Protoboard is, the rules, the order of work and the shell commands beside these tools.", mimeType: "text/markdown" }, async (uri) => ({
+    contents: [{ uri: uri.href, mimeType: "text/markdown", text: guideText(templates) }],
+  }));
+  // the project's own instructions, when the server was started in a project that has them
+  const startedIn = options.cwd ?? process.env.PROTOBOARD_PROJECT_DIR ?? process.cwd();
+  const root = findProjectRoot(resolve(startedIn));
+  if (root && existsSync(join(root, "AGENTS.md"))) {
+    server.registerResource("agents-md", "protoboard://project/AGENTS.md", { title: "The project's AGENTS.md", description: "The project's own instructions for agents: read it before working on the project.", mimeType: "text/markdown" }, async (uri) => ({
+      contents: [{ uri: uri.href, mimeType: "text/markdown", text: readFileSync(join(root, "AGENTS.md"), "utf8") }],
+    }));
+  }
+
+  server.registerPrompt(
+    "new_project",
+    { title: "Start a Protoboard project", description: "Start a hardware project for a device, in this folder.", argsSchema: { what: z.string().describe("The device to build, in a sentence or two.") } },
+    ({ what }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Use Protoboard to start a hardware project for: ${what}\n\nCall project_status first. If this folder is not a project yet, pick the closest template (${templates.join(", ")}; or none) and create it with project_init (it uses the Protoboard installed on this machine: never run \`npm install\`). Read the project's AGENTS.md and the build-a-project skill (skill_read), write the requirements into docs/brief.md with a source for every number, and follow the skill from there. Run project_check after each change. Do not look for a Protoboard web app: there is none to use here.`,
+          },
+        },
+      ],
+    }),
+  );
+  server.registerPrompt("continue_project", { title: "Continue this Protoboard project", description: "Pick up the Protoboard project in this folder where it stands." }, () => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: "Continue the Protoboard project in this folder. Call project_status, read AGENTS.md and docs/brief.md, run project_check and project_inspect to see where it stands, then say what the next step of the build-a-project skill is (skill_read) and what you would do. Do not change anything before I agree.",
+        },
+      },
+    ],
+  }));
+  return server;
+}
+
+/** Serve on stdio until the client closes the stream. */
+export async function serveStdio(options: ServerOptions = {}): Promise<void> {
+  const server = createServer(options);
+  await server.connect(new StdioServerTransport());
+  process.stderr.write(`protoboard mcp ${SELF_VERSION}: serving on stdio (folder: ${options.cwd ?? process.cwd()})\n`);
+  await new Promise<void>((done) => {
+    server.server.onclose = () => done();
+    process.stdin.on("close", () => done());
+  });
+}