@dev.fast/whiteboard 0.0.0-stage → 0.2.0

package/src/cli-runtime-info.ts

@@ -0,0 +1,35 @@
+import path from "node:path";
+
+import { jsonString } from "@dev.fast/review-protocol";
+
+import { readBuildInfo } from "./package-paths";
+
+/** Build identity belongs to the executable, never the current checkout. */
+export function cliRuntimeInfo(
+  requestedPath: string,
+  effectivePath = requestedPath,
+) {
+  const metadata = readBuildInfo(path.dirname(effectivePath));
+
+  return {
+    event: "version" as const,
+    requestedPath,
+    effectivePath,
+    delegated: requestedPath !== effectivePath,
+    version: jsonString(metadata?.version) ?? null,
+    commit: jsonString(metadata?.commit) ?? null,
+    dirty:
+      metadata?.dirty === true
+        ? true
+        : metadata?.dirty === false
+          ? false
+          : null,
+    builtAt: jsonString(metadata?.builtAt) ?? null,
+  };
+}
+
+export function describeCliRuntime(
+  info: ReturnType<typeof cliRuntimeInfo>,
+): string {
+  return `CLI: ${info.effectivePath}${info.delegated ? ` (delegated from ${info.requestedPath})` : " (direct)"}\nBuild: ${info.version ?? "unknown"}, commit ${info.commit ?? "unknown"}, dirty ${info.dirty ?? "unknown"}, built ${info.builtAt ?? "unknown"}\n`;
+}

package/src/cli.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  jsonNumber,
+  jsonObject,
+  jsonString,
+  parseJsonText,
+} from "@dev.fast/review-protocol";
+
+// A standalone build (npx/global install) defers to the CLI bundled with a
+// running Review Desktop so the CLI can never skew from the server it talks
+// to. Checkout runs execute src/cli.ts via tsx and therefore never delegate.
+// Delegation runs before the Node floor check on purpose: the app's
+// Electron-as-Node runtime can rescue a machine whose system Node is too old.
+const argv = process.argv.slice(2);
+
+const ownCliPath = fileURLToPath(import.meta.url);
+
+const delegatedExitCode = await maybeDelegateToDesktopCli(argv);
+
+process.exitCode = delegatedExitCode ?? (await runCli(ownCliPath));
+
+async function runCli(effectivePath: string): Promise<number> {
+  if (!supportedNodeRuntime()) {
+    process.stderr.write(
+      `Whiteboard needs Node.js 24 or newer; found ${process.versions.node}. ` +
+        "Update Node, or use the whiteboard command installed by Whiteboard Desktop.\n",
+    );
+
+    return 1;
+  }
+
+  const { runReviewCli } = await import("./cli-runner.js");
+
+  return runReviewCli({
+    argv,
+    cliPaths: { requestedPath: ownCliPath, effectivePath },
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+  });
+}
+
+// An Electron-as-Node runtime (the app's) is trusted as-is: it is the same
+// runtime the Review server runs on. Only a system Node gets the floor check,
+// so an old `node` fails with an instruction instead of a syntax or
+// missing-builtin crash deeper in.
+function supportedNodeRuntime(): boolean {
+  if (process.versions.electron) return true;
+
+  return Number(process.versions.node.split(".")[0]) >= 24;
+}
+
+async function maybeDelegateToDesktopCli(
+  argv: string[],
+): Promise<number | null> {
+  const env = process.env;
+
+  if (env.DEV_FAST_REVIEW_CLI_NO_DELEGATE || env.DEV_FAST_REVIEW_CLI_DELEGATED)
+    return null;
+
+  // api and mcp are thin HTTP clients whose tool catalog comes from the
+  // server, so they cannot skew from it and must not be handed to a bundled
+  // CLI that predates them.
+  if (
+    argv.some(
+      (argument) =>
+        ["api", "mcp", "server", "instances"].includes(argument) ||
+        /^--state-dir(?:=|$)/.test(argument),
+    ) ||
+    env.DEV_REVIEW_SERVER_DIR?.trim()
+  )
+    return null;
+  const ownPath = fileURLToPath(import.meta.url);
+
+  if (!/[\\/]dist[\\/]cli\.js$/.test(ownPath)) return null;
+
+  // This bootstrap runs before the Node floor check, so it cannot import
+  // devReviewHome() from @dev.fast/trace-core: that module graph needs a modern
+  // Node. Keep this copy in step with devReviewHome().
+  const devHome = env.DEV_REVIEW_HOME?.trim()
+    ? path.resolve(env.DEV_REVIEW_HOME.trim())
+    : path.join(os.homedir(), ".dev");
+
+  let cliPath: string;
+  let runtimePath: string | undefined;
+  const discoveryFile = selectedDiscoveryFile(devHome, env);
+
+  if (!discoveryFile) return null;
+
+  try {
+    const discovery = jsonObject(
+      parseJsonText(readFileSync(discoveryFile, "utf8")),
+    );
+
+    const discoveredCliPath = jsonString(discovery?.cliPath);
+
+    if (!discoveredCliPath) return null;
+    cliPath = discoveredCliPath;
+    const discoveredRuntimePath = jsonString(discovery?.cliRuntimePath);
+
+    if (discoveredRuntimePath && existsSync(discoveredRuntimePath)) {
+      runtimePath = discoveredRuntimePath;
+    }
+  } catch {
+    return null;
+  }
+
+  try {
+    if (realpathSync(cliPath) === realpathSync(ownPath)) return null;
+  } catch {
+    return null;
+  }
+
+  // Prefer the app's Electron-as-Node runtime: it matches the server exactly
+  // and works even when this process runs on an older system Node.
+  const childEnv: NodeJS.ProcessEnv = {
+    ...env,
+    DEV_FAST_REVIEW_CLI_DELEGATED: "1",
+  };
+
+  // The current parser owns verbose diagnostics, including usage errors and
+  // help, even when the selected Desktop CLI predates this option.
+  const command = argv.filter((argument) => argument !== "--json");
+
+  if (command[0] === "version" && command.includes("--verbose")) {
+    return runCli(cliPath);
+  }
+
+  if (runtimePath) childEnv.ELECTRON_RUN_AS_NODE = "1";
+
+  const result = spawnSync(
+    runtimePath ?? process.execPath,
+    [cliPath, ...argv],
+    { stdio: "inherit", env: childEnv },
+  );
+
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+
+    return 1;
+  }
+
+  return result.status ?? 1;
+}
+
+/**
+ * The shim's selection, kept in step with it and with selectReviewInstance:
+ * DEV_REVIEW_INSTANCE, the machine default, the only live Desktop, then
+ * stable, then the pre-instance server.json.
+ */
+function selectedDiscoveryFile(devHome: string, env: NodeJS.ProcessEnv) {
+  const desktop = path.join(devHome, "review-desktop");
+  const instances = path.join(desktop, "instances");
+  let key = env.DEV_REVIEW_INSTANCE?.trim();
+
+  try {
+    key ||= readFileSync(path.join(desktop, "default-instance"), "utf8").trim();
+  } catch {
+    // No machine default.
+  }
+
+  // Keys name files; the CLI rejects anything else.
+  if (key && !/^[A-Za-z0-9_.-]+$/.test(key)) return undefined;
+
+  // A stable Desktop that predates instances wrote only server.json; it never
+  // stands in for any other key.
+  const legacy = path.join(desktop, "server.json");
+  let stable = path.join(instances, "stable.json");
+
+  if (!existsSync(stable)) stable = legacy;
+
+  let selected =
+    key === "stable" ? stable : key && path.join(instances, `${key}.json`);
+
+  if (!selected) {
+    let names: string[] = [];
+
+    try {
+      names = readdirSync(instances).filter((name) => name.endsWith(".json"));
+    } catch {
+      // No instance has started yet.
+    }
+
+    const live = [
+      ...names.map((name) => path.join(instances, name)),
+      ...(stable === legacy ? [legacy] : []),
+    ].filter(recordIsLive);
+
+    selected = live.length === 1 ? live[0]! : stable;
+  }
+
+  return recordIsLive(selected) ? selected : undefined;
+}
+
+function recordIsLive(filePath: string) {
+  try {
+    const serverPid = jsonNumber(
+      jsonObject(parseJsonText(readFileSync(filePath, "utf8")))?.serverPid,
+    );
+
+    return serverPid !== undefined && processIsAlive(serverPid);
+  } catch {
+    return false;
+  }
+}
+
+function processIsAlive(pid: number) {
+  try {
+    process.kill(pid, 0);
+
+    return true;
+  } catch (error) {
+    return error instanceof Error && "code" in error && error.code === "EPERM";
+  }
+}

package/src/connect-prompts.ts

@@ -0,0 +1,248 @@
+import { cursorInstallDeeplink } from "./cursor-deeplink";
+import type { InstallTarget } from "./install";
+
+/** The macOS and Linux launch form; the Claude and Cursor plugins must match it byte for byte, and the Codex plugin's bin/whiteboard-mcp runs the same command. */
+export const REVIEW_MCP_LAUNCH = {
+  command: "sh",
+  args: ["-c", 'exec "$HOME/.local/bin/whiteboard" mcp'],
+} as const;
+
+/**
+ * Windows has no sh, and Node-based harnesses cannot start a .cmd file
+ * directly. cmd finds whiteboard.cmd on PATH, whether the first-run step or
+ * the installer put it there.
+ */
+export const WINDOWS_MCP_LAUNCH = {
+  command: "cmd",
+  args: ["/d", "/c", "whiteboard", "mcp"],
+} as const;
+
+export interface ConnectPromptInput {
+  /** False when the serving package has no built CLI (Desktop from source): prompts fall back to a bare `whiteboard`. */
+  hasShim: boolean;
+  legacyPaths: string[];
+  traceEnabled: boolean;
+  fffBinaryPath: string;
+  fffCorpusRoot: string;
+  /** Defaults to this process's platform. */
+  platform?: NodeJS.Platform;
+}
+
+export const FFF_INSTALL_URL =
+  "https://raw.githubusercontent.com/dmtrKovalenko/fff/v0.11.0/install-mcp.sh";
+
+export const PI_FFF_PACKAGE = "npm:@ff-labs/pi-fff";
+
+export const PI_WHITEBOARD_PACKAGE = "npm:@dev.fast/pi-whiteboard";
+
+/** A stdio MCP server launch, as harness configs spell it. */
+export interface McpLaunch {
+  command: string;
+  args: string[];
+}
+
+export function reviewMcpLaunch(
+  hasShim: boolean,
+  platform: NodeJS.Platform = process.platform,
+): McpLaunch {
+  if (platform === "win32")
+    return {
+      command: WINDOWS_MCP_LAUNCH.command,
+      args: [...WINDOWS_MCP_LAUNCH.args],
+    };
+
+  return hasShim
+    ? {
+        command: REVIEW_MCP_LAUNCH.command,
+        args: [...REVIEW_MCP_LAUNCH.args],
+      }
+    : { command: "whiteboard", args: ["mcp"] };
+}
+
+function shellQuote(value: string): string {
+  return "'" + value.replaceAll("'", "'\"'\"'") + "'";
+}
+
+function numbered(steps: string[]): string[] {
+  return steps.map((step, index) => `${index + 1}. ${step}`);
+}
+
+function fffSteps(input: ConnectPromptInput, target: InstallTarget): string[] {
+  if (!input.traceEnabled) return [];
+
+  if (target === "pi" || target === "omp") {
+    return [`Run: ${target} install ${PI_FFF_PACKAGE}`];
+  }
+
+  const binary = shellQuote(input.fffBinaryPath);
+  const root = shellQuote(input.fffCorpusRoot);
+  const add = target === "claude" ? "claude mcp add -s user" : "codex mcp add";
+
+  return [
+    `Unless \`${target} mcp get fff\` finds an existing server, run:\n\n\`\`\`sh\n[ -x ${binary} ] || curl -fsSL ${FFF_INSTALL_URL} | bash\n${add} fff -- ${binary} ${root}\n\`\`\``,
+  ];
+}
+
+/** The Claude plugin's sh launch cannot start on Windows, so register the server directly. */
+export const CLAUDE_WINDOWS_MCP_ADD = `claude mcp add -s user whiteboard -- ${WINDOWS_MCP_LAUNCH.command} ${WINDOWS_MCP_LAUNCH.args.join(" ")}`;
+
+/** Copilot CLI loads the Claude plugin, so on Windows it too registers the server directly. */
+export const COPILOT_WINDOWS_MCP_ADD = `copilot mcp add whiteboard -- ${WINDOWS_MCP_LAUNCH.command} ${WINDOWS_MCP_LAUNCH.args.join(" ")}`;
+
+function pluginSteps(
+  target: Exclude<InstallTarget, "cursor">,
+  platform: NodeJS.Platform,
+): string[] {
+  switch (target) {
+    case "claude":
+      if (platform === "win32")
+        return [
+          `Run:\n\n\`\`\`sh\nclaude plugin uninstall whiteboard@devfast # its launch cannot start on Windows, if installed\nclaude mcp remove -s user whiteboard # old registration, if any\n${CLAUDE_WINDOWS_MCP_ADD}\n\`\`\``,
+        ];
+
+      return [
+        "Run:\n\n```sh\nclaude plugin marketplace add devdotfast/whiteboard\nclaude plugin install whiteboard@devfast --scope user\nclaude mcp remove -s user whiteboard # old manual registration, if any\n```",
+      ];
+    case "codex":
+      return [
+        "Run:\n\n```sh\ncodex plugin marketplace add devdotfast/whiteboard\ncodex plugin add whiteboard@devfast\ncodex mcp remove whiteboard # old manual registration, if any\n```",
+      ];
+    case "opencode": {
+      const launch = reviewMcpLaunch(true, platform);
+
+      const entry = JSON.stringify(
+        {
+          whiteboard: {
+            type: "local",
+            command: [launch.command, ...launch.args],
+          },
+        },
+        null,
+        2,
+      );
+
+      return [
+        `On OpenCode 2.0 or later, run:\n\n\`\`\`sh\nopencode mcp add --global whiteboard -- ${launchCommand(launch)}\n\`\`\`\n\nOn older OpenCode, add this entry to "mcp" in ~/.config/opencode/opencode.json, keeping the rest of the file:\n\n\`\`\`json\n${entry}\n\`\`\``,
+        `Remove "@dev.fast/opencode-whiteboard" from "plugin" in ~/.config/opencode/opencode.json if it is there.`,
+      ];
+    }
+
+    case "copilot":
+      if (platform === "win32")
+        return [
+          `Run:\n\n\`\`\`sh\ncopilot plugin uninstall whiteboard@devfast # its launch cannot start on Windows, if installed\ncopilot mcp remove whiteboard # old registration, if any\n${COPILOT_WINDOWS_MCP_ADD}\n\`\`\``,
+        ];
+
+      return [
+        "Run:\n\n```sh\ncopilot plugin marketplace add devdotfast/whiteboard\ncopilot plugin install whiteboard@devfast\ncopilot mcp remove whiteboard # old manual registration, if any\n```",
+      ];
+    case "pi":
+      return [
+        `On Pi 0.99.0 or later, run:\n\n\`\`\`sh\npi mcp add whiteboard -- ${launchCommand(reviewMcpLaunch(true, platform))}\npi remove ${PI_WHITEBOARD_PACKAGE} # if installed\n\`\`\`\n\nOn older Pi, run \`pi install ${PI_WHITEBOARD_PACKAGE}\`.`,
+      ];
+    case "omp": {
+      const entry = JSON.stringify(
+        { whiteboard: reviewMcpLaunch(true, platform) },
+        null,
+        2,
+      );
+
+      return [
+        `Add this entry to mcpServers in ~/.omp/agent/mcp.json, keeping the rest of the file:\n\n\`\`\`json\n${entry}\n\`\`\``,
+        `Run \`omp plugin uninstall @dev.fast/pi-whiteboard\` if installed.`,
+      ];
+    }
+  }
+}
+
+export function launchCommand(launch: McpLaunch): string {
+  return [launch.command, ...launch.args]
+    .map((arg) => (/^[\w./-]+$/.test(arg) ? arg : shellQuote(arg)))
+    .join(" ");
+}
+
+function cursorSteps(): string[] {
+  const launch = reviewMcpLaunch(true);
+  const deeplink = cursorInstallDeeplink(launch);
+  const entry = JSON.stringify({ whiteboard: launch }, null, 2);
+
+  return [
+    `Do not paste the install link in chat. Chat clients do not open cursor:// links. Open Cursor's MCP install deeplink with the OS URL handler using the command for this operating system, then stop and let me confirm the install:\n\nmacOS: open ${shellQuote(deeplink)}\nLinux: xdg-open ${shellQuote(deeplink)}\nWindows: cmd /c start "" "${deeplink}"`,
+    `After I confirm, check for a whiteboard server in ~/.cursor/mcp.json. If the deeplink did not add it, merge this entry into the file's mcpServers object without removing other servers or settings (create the file and object if missing). Do not use this fallback if I declined the install:\n\n\`\`\`json\n${entry}\n\`\`\``,
+  ];
+}
+
+export function connectPrompt(
+  target: InstallTarget,
+  input: ConnectPromptInput,
+): string {
+  if (!input.hasShim) {
+    return "Connect this agent to dev.fast Whiteboard.\n\nStop and ask me to install the whiteboard command in Whiteboard Desktop (Settings → Command line), then run this connect command again. The connection requires ~/.local/bin/whiteboard.";
+  }
+
+  const extra =
+    target === "claude" ||
+    target === "codex" ||
+    target === "pi" ||
+    target === "omp"
+      ? fffSteps(input, target)
+      : [];
+
+  const verify =
+    target === "pi"
+      ? "Ask me to run /reload, then call `session_get_instructions` on the Whiteboard server (older Pi: `whiteboard api session_get_instructions '{}'`). Do not author anything yet."
+      : target === "omp"
+        ? "Ask me to run /mcp reload, then call `session_get_instructions` on the Whiteboard server. Do not author anything yet."
+        : target === "opencode"
+          ? "Stop and tell me to quit and reopen OpenCode: it loads MCP servers only at startup. After I reopen it, call `session_get_instructions` on the Whiteboard server to confirm the connection. Do not author anything yet."
+          : "Reload your MCP tools and call `session_get_instructions` on the Whiteboard server. If a restart is needed, tell me and verify after it. Do not author anything yet.";
+
+  return [
+    "Connect this agent to dev.fast Whiteboard.",
+    "",
+    ...numbered([
+      ...(input.legacyPaths.length
+        ? [
+            `Delete these old Whiteboard skill folders and plugin files:\n${input.legacyPaths.map((item) => `- ${JSON.stringify(item)}`).join("\n")}`,
+          ]
+        : []),
+      ...(target === "cursor"
+        ? cursorSteps()
+        : [
+            ...pluginSteps(target, input.platform ?? process.platform),
+            ...extra,
+          ]),
+      verify,
+    ]),
+  ].join("\n");
+}
+
+export function connectSetupPrompt(target: InstallTarget): string {
+  return `Run \`whiteboard connect ${target}\` and follow the instructions to connect this agent to Whiteboard.`;
+}
+
+export function connectSetupPrompts(): Record<InstallTarget, string> {
+  return {
+    claude: connectSetupPrompt("claude"),
+    codex: connectSetupPrompt("codex"),
+    cursor: connectSetupPrompt("cursor"),
+    opencode: connectSetupPrompt("opencode"),
+    pi: connectSetupPrompt("pi"),
+    omp: connectSetupPrompt("omp"),
+    copilot: connectSetupPrompt("copilot"),
+  };
+}
+
+export function connectPrompts(
+  input: ConnectPromptInput,
+): Record<InstallTarget, string> {
+  return {
+    claude: connectPrompt("claude", input),
+    codex: connectPrompt("codex", input),
+    cursor: connectPrompt("cursor", input),
+    opencode: connectPrompt("opencode", input),
+    pi: connectPrompt("pi", input),
+    omp: connectPrompt("omp", input),
+    copilot: connectPrompt("copilot", input),
+  };
+}

package/src/cursor-deeplink.ts

@@ -0,0 +1,11 @@
+/** Cursor's one-click MCP install link for Whiteboard's server. */
+export function cursorInstallDeeplink(launch: {
+  command: string;
+  args: string[];
+}): string {
+  const config = Buffer.from(
+    JSON.stringify({ command: launch.command, args: launch.args }),
+  ).toString("base64");
+
+  return `cursor://anysphere.cursor-deeplink/mcp/install?name=whiteboard&config=${encodeURIComponent(config)}`;
+}