@dev.fast/whiteboard 0.2.5-preview.20261013.113 → 0.2.5-preview.20261015.115

package/src/connect-agents.ts

@@ -0,0 +1,285 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  REVIEW_CLI_INSTALL_TARGET_LABELS,
+  REVIEW_REMOTE_AGENT_IDS,
+  type ReviewRemoteAgentId,
+} from "@dev.fast/review-protocol";
+import {
+  type AgentTraceHookAgent,
+  agentTraceHomeDirectory,
+} from "@dev.fast/trace-core";
+import { parse as parseToml } from "smol-toml";
+import { z } from "zod";
+
+import { CONNECT_COMMANDS, type ConnectCommand } from "./connect-prompts";
+import { isDirectory } from "./fs-utils";
+
+export const AGENT_CONNECT_TARGETS: readonly (ReviewRemoteAgentId &
+  AgentTraceHookAgent)[] = REVIEW_REMOTE_AGENT_IDS;
+
+export type AgentConnectTarget = ReviewRemoteAgentId;
+
+export interface DetectedAgent {
+  id: AgentConnectTarget;
+  name: string;
+  connected: boolean;
+  manual?: true;
+}
+
+export interface ConnectedAgent {
+  id: AgentConnectTarget;
+  name: string;
+  connected: boolean;
+  output: string;
+}
+
+const OUTPUT_LIMIT = 4000;
+
+export const AGENT_CONNECT_TIMEOUT_MS = 120_000;
+
+interface Scope {
+  homeDir: string;
+  env: NodeJS.ProcessEnv;
+}
+
+export async function detectAgents(scope: Scope): Promise<DetectedAgent[]> {
+  const found: DetectedAgent[] = [];
+
+  for (const id of AGENT_CONNECT_TARGETS) {
+    if (
+      !(await isDirectory(
+        agentTraceHomeDirectory(id, scope.homeDir, scope.env),
+      ))
+    )
+      continue;
+
+    const manual = !(await onPath(CONNECT_COMMANDS[id][0].argv[0], scope.env));
+
+    found.push({
+      id,
+      name: REVIEW_CLI_INSTALL_TARGET_LABELS[id],
+      connected: await connected(id, scope),
+      ...(manual && { manual: true as const }),
+    });
+  }
+
+  return found;
+}
+
+export async function connectAgents(
+  input: Scope & {
+    agents: readonly AgentConnectTarget[];
+    timeoutMs?: number;
+  },
+): Promise<ConnectedAgent[]> {
+  const results: ConnectedAgent[] = [];
+
+  for (const id of input.agents) {
+    const deadline = Date.now() + (input.timeoutMs ?? AGENT_CONNECT_TIMEOUT_MS);
+    let output = "";
+
+    const commands: readonly ConnectCommand[] = CONNECT_COMMANDS[id];
+
+    for (const { argv, ifAny } of commands) {
+      const left = deadline - Date.now();
+
+      if (left <= 0) break;
+      const step = await run(argv, input.env, left);
+
+      output += `$ ${argv.join(" ")}\n${step.output}`;
+
+      if (!step.ok && !ifAny) {
+        output += `Stopped: ${argv.join(" ")} failed.\n`;
+        break;
+      }
+    }
+
+    results.push({
+      id,
+      name: REVIEW_CLI_INSTALL_TARGET_LABELS[id],
+      connected: await connected(id, input),
+      output: output.slice(-OUTPUT_LIMIT),
+    });
+  }
+
+  return results;
+}
+
+const WHITEBOARD_PLUGIN = "whiteboard@devfast";
+
+const ClaudePluginsSchema = z.object({
+  plugins: z.record(z.string(), z.unknown()),
+});
+
+const CodexConfigSchema = z.object({
+  plugins: z.record(z.string(), z.unknown()).optional(),
+});
+
+const CodexPluginSchema = z.object({ enabled: z.boolean().optional() });
+
+const PiSettingsSchema = z.object({
+  packages: z.array(
+    z.union([
+      z.string(),
+      z.object({ source: z.string() }).transform((entry) => entry.source),
+    ]),
+  ),
+});
+
+const PI_PACKAGE = /^npm:@dev\.fast\/pi-whiteboard(@.*)?$/;
+
+const OPENCODE_PLUGIN =
+  /"plugin"\s*:\s*\[[^\]]*"@dev\.fast\/opencode-whiteboard(@[^"]*)?"/;
+
+const OpenCodeConfigSchema = z.object({
+  mcp: z.object({
+    whiteboard: z.unknown().optional(),
+    servers: z.object({ whiteboard: z.unknown().optional() }).optional(),
+  }),
+});
+
+/** OpenCode's config is JSONC: drop comments and trailing commas, keep strings. */
+const JSONC_EXTRAS =
+  /("(?:\\.|[^"\\])*")|\/\/[^\n]*|\/\*[\s\S]*?\*\/|,(?=\s*[}\]])/g;
+
+function openCodeConnected(text: string): boolean {
+  if (OPENCODE_PLUGIN.test(text)) return true;
+
+  try {
+    const { mcp } = OpenCodeConfigSchema.parse(
+      JSON.parse(text.replace(JSONC_EXTRAS, "$1")),
+    );
+
+    return (
+      mcp.whiteboard !== undefined || mcp.servers?.whiteboard !== undefined
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function connected(
+  id: AgentConnectTarget,
+  scope: Scope,
+): Promise<boolean> {
+  const home = agentTraceHomeDirectory(id, scope.homeDir, scope.env);
+
+  const read = (...parts: string[]) =>
+    readFile(path.join(home, ...parts), "utf8");
+
+  try {
+    switch (id) {
+      case "claude": {
+        const installs = ClaudePluginsSchema.parse(
+          JSON.parse(await read("plugins", "installed_plugins.json")),
+        ).plugins[WHITEBOARD_PLUGIN];
+
+        return Array.isArray(installs)
+          ? installs.length > 0
+          : Boolean(installs);
+      }
+
+      case "codex": {
+        const entry = CodexConfigSchema.parse(
+          parseToml(await read("config.toml")),
+        ).plugins?.[WHITEBOARD_PLUGIN];
+
+        return (
+          entry !== undefined &&
+          CodexPluginSchema.parse(entry).enabled !== false
+        );
+      }
+
+      case "opencode": {
+        for (const name of ["opencode.json", "opencode.jsonc", "config.json"]) {
+          if (openCodeConnected(await read(name).catch(() => ""))) return true;
+        }
+
+        return false;
+      }
+
+      case "pi":
+        return PiSettingsSchema.parse(
+          JSON.parse(await read("agent", "settings.json")),
+        ).packages.some((entry) => PI_PACKAGE.test(entry));
+    }
+  } catch {
+    return false;
+  }
+}
+
+async function onPath(
+  command: string,
+  env: NodeJS.ProcessEnv,
+): Promise<string | undefined> {
+  for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+    if (!path.isAbsolute(directory)) continue;
+    const candidate = path.join(directory, command);
+
+    try {
+      await access(candidate, constants.X_OK);
+
+      return candidate;
+    } catch {}
+  }
+
+  return undefined;
+}
+
+async function run(
+  argv: readonly string[],
+  env: NodeJS.ProcessEnv,
+  timeoutMs: number,
+): Promise<{ output: string; ok: boolean }> {
+  const [command = "", ...args] = argv;
+  const file = await onPath(command, env);
+
+  if (!file)
+    return { output: `${command} was not found on PATH.\n`, ok: false };
+
+  return new Promise((resolve) => {
+    let output = "";
+
+    const keep = (chunk: Buffer) => {
+      output = (output + chunk.toString("utf8")).slice(-OUTPUT_LIMIT);
+    };
+
+    const child = spawn(file, args, {
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: true,
+    });
+
+    const timer = setTimeout(() => {
+      output += `\n${command} did not finish within ${Math.round(timeoutMs / 1000)} seconds.\n`;
+
+      try {
+        process.kill(-child.pid!, "SIGKILL");
+      } catch {
+        child.kill("SIGKILL");
+      }
+    }, timeoutMs);
+
+    child.stdout.on("data", keep);
+    child.stderr.on("data", keep);
+    child.once("error", (error) => {
+      clearTimeout(timer);
+      resolve({ output: `${output}${error.message}\n`, ok: false });
+    });
+    child.once("close", (code) => {
+      clearTimeout(timer);
+      resolve(
+        code === 0
+          ? { output, ok: true }
+          : {
+              output: `${output}${output.endsWith("\n") || !output ? "" : "\n"}(exit ${code ?? "signal"})\n`,
+              ok: false,
+            },
+      );
+    });
+  });
+}

package/src/connect-prompts.ts

@@ -89,6 +89,64 @@ export const CLAUDE_WINDOWS_MCP_ADD = `claude mcp add -s user whiteboard -- ${WI
 /** 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(" ")}`;
 
+export interface ConnectCommand {
+  argv: readonly string[];
+  ifAny?: true;
+}
+
+export const CONNECT_COMMANDS = {
+  claude: [
+    {
+      argv: ["claude", "plugin", "marketplace", "add", "devdotfast/whiteboard"],
+    },
+    {
+      argv: [
+        "claude",
+        "plugin",
+        "install",
+        "whiteboard@devfast",
+        "--scope",
+        "user",
+      ],
+    },
+    {
+      argv: ["claude", "mcp", "remove", "-s", "user", "whiteboard"],
+      ifAny: true,
+    },
+  ],
+  codex: [
+    {
+      argv: ["codex", "plugin", "marketplace", "add", "devdotfast/whiteboard"],
+    },
+    { argv: ["codex", "plugin", "add", "whiteboard@devfast"] },
+    { argv: ["codex", "mcp", "remove", "whiteboard"], ifAny: true },
+  ],
+  opencode: [
+    {
+      argv: [
+        "opencode",
+        "mcp",
+        "add",
+        "--global",
+        "whiteboard",
+        "--",
+        REVIEW_MCP_LAUNCH.command,
+        ...REVIEW_MCP_LAUNCH.args,
+      ],
+    },
+  ],
+  pi: [{ argv: ["pi", "install", PI_WHITEBOARD_PACKAGE] }],
+} as const satisfies Record<string, readonly ConnectCommand[]>;
+
+function runBlock(commands: readonly ConnectCommand[]): string {
+  const lines = commands.map(
+    ({ argv, ifAny }) =>
+      `${argv.join(" ")}${ifAny ? " # old manual registration, if any" : ""}`,
+  );
+
+  return `Run:\n\n\`\`\`sh\n${lines.join("\n")}\n\`\`\``;
+}
+
 function pluginSteps(
   target: Exclude<InstallTarget, "cursor">,
   platform: NodeJS.Platform,
@@ -100,13 +158,9 @@ function pluginSteps(
           `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```",
-      ];
+      return [runBlock(CONNECT_COMMANDS.claude)];
     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```",
-      ];
+      return [runBlock(CONNECT_COMMANDS.codex)];
     case "opencode": {
       const launch = reviewMcpLaunch(true, platform);
 

package/src/desktop-discovery.ts

@@ -11,8 +11,10 @@ import {
   parseJsonText,
   parseReviewDesktopDiscovery,
 } from "@dev.fast/review-protocol";
+import { processIsAlive } from "@dev.fast/trace-core";
 
 import {
+  DEV_REVIEW_HOME_ENV,
   reviewDefaultInstancePath,
   reviewDevInstanceKey,
   reviewInstancesDir,
@@ -183,6 +185,28 @@ export interface ReviewInstanceDependencies {
   warn?: (message: string) => void;
 }
 
+/** Any live Desktop holds the store, attached window or not. Only a gone
+ * process counts as stopped: a paused or busy one may not answer /health. */
+export async function desktopUsesHome(
+  home: string,
+  env: NodeJS.ProcessEnv = process.env,
+) {
+  const desktops = await readReviewInstances({
+    env: { ...env, [DEV_REVIEW_HOME_ENV]: home },
+  });
+
+  const [problem] = desktops.broken.values();
+
+  if (problem)
+    throw new Error(
+      `Cannot tell whether a Whiteboard Desktop is using ${home}: ${problem.message}`,
+    );
+
+  return desktops.instances.some(({ discovery }) =>
+    [discovery.appPid, discovery.serverPid].some((pid) => processIsAlive(pid)),
+  );
+}
+
 /** Records by key, plus the files that could not be read, by key. */
 export async function readReviewInstances(
   dependencies: ReviewInstanceDependencies,

package/src/pinned-download.ts

@@ -0,0 +1,118 @@
+// Plain Node and zod only: apps/review-desktop/scripts imports this file directly.
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import type { ReadableStream as WebReadableStream } from "node:stream/web";
+
+import { z } from "zod";
+
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+
+interface DownloadOptions {
+  size?: number;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+/** Streams `url` into `file` through a temporary file and returns its sha256. */
+export async function downloadFile(
+  url: string,
+  file: string,
+  { size, timeoutMs = DOWNLOAD_TIMEOUT_MS, signal }: DownloadOptions = {},
+) {
+  const { host } = new URL(url);
+  const partial = `${file}.${process.pid}.part`;
+  let response: Response;
+
+  await mkdir(path.dirname(file), { recursive: true });
+
+  try {
+    response = await fetch(url, {
+      signal: AbortSignal.any([
+        AbortSignal.timeout(timeoutMs),
+        ...(signal ? [signal] : []),
+      ]),
+    });
+  } catch (error) {
+    throw new Error(
+      `Network error reaching ${host}: ${error instanceof Error ? networkCause(error) : String(error)}`,
+    );
+  }
+
+  if (!response.ok || !response.body)
+    throw new Error(`${host} answered ${response.status} for ${url}`);
+
+  const hash = createHash("sha256");
+  let received = 0;
+
+  const tooLarge = new Error(`${url} is larger than its pinned ${size} bytes`);
+
+  try {
+    await pipeline(
+      // SAFETY: Node's fetch body is its own web stream; the DOM type only
+      // names the same object.
+      Readable.fromWeb(response.body as WebReadableStream),
+      async function* (chunks: AsyncIterable<Buffer>) {
+        for await (const chunk of chunks) {
+          received += chunk.length;
+
+          if (size !== undefined && received > size) throw tooLarge;
+
+          hash.update(chunk);
+          yield chunk;
+        }
+      },
+      createWriteStream(partial),
+    );
+    await rename(partial, file);
+  } catch (error) {
+    await rm(partial, { force: true });
+
+    if (error === tooLarge) throw error;
+
+    throw new Error(
+      `Network error downloading from ${host}: ${error instanceof Error ? networkCause(error) : String(error)}`,
+    );
+  }
+
+  return hash.digest("hex");
+}
+
+/** Leaves a matching `file` in place; otherwise downloads it and checks the pin. */
+export async function downloadPinned(
+  pin: { url: string; sha256: string; size?: number },
+  file: string,
+  options: Omit<DownloadOptions, "size"> = {},
+) {
+  if ((await sha256File(file).catch(() => undefined)) === pin.sha256) return;
+
+  const actual = await downloadFile(pin.url, file, {
+    ...options,
+    size: pin.size,
+  });
+
+  if (actual !== pin.sha256) {
+    await rm(file, { force: true });
+    throw new Error(
+      `Checksum mismatch for ${pin.url}: expected ${pin.sha256}, got ${actual}. The download was deleted.`,
+    );
+  }
+}
+
+export async function sha256File(file: string) {
+  const hash = createHash("sha256");
+
+  for await (const chunk of createReadStream(file)) hash.update(chunk);
+
+  return hash.digest("hex");
+}
+
+const networkCauseSchema = z.object({ code: z.string() });
+
+const networkCause = (error: Error) =>
+  error.name === "TimeoutError"
+    ? "timed out"
+    : (networkCauseSchema.safeParse(error.cause).data?.code ?? error.message);

package/src/remote-attach.ts

@@ -0,0 +1,130 @@
+import { gt as greaterVersion, valid as validVersion } from "semver";
+
+import { readReviewPackageVersion } from "./package-paths";
+import {
+  type EnsureRemoteLanguageServerInput,
+  ensureRemoteLanguageServer,
+} from "./remote-language-server";
+import { missingToolchains } from "./remote-toolchains";
+import { readReviewServerHealth, serverNotReady } from "./server-discovery";
+import {
+  type EnsureBackgroundServerInput,
+  ensureBackgroundServer,
+  recordedBackgroundServer,
+  stopBackgroundServer,
+} from "./server/background-server";
+
+export async function remoteAttach(input: {
+  stateDir: string;
+  env: NodeJS.ProcessEnv;
+  packageRoot?: string;
+  cli?: EnsureBackgroundServerInput["cli"];
+  groups?: string[];
+  ensureExtensions?: EnsureRemoteLanguageServerInput["ensure"];
+  installTimeoutMs?: number;
+  replace?: boolean;
+  version?: string;
+}) {
+  const extensions = new AbortController();
+
+  const language = ensureRemoteLanguageServer({
+    env: input.env,
+    packageRoot: input.packageRoot,
+    groups: input.groups,
+    signal: extensions.signal,
+    ensure: input.ensureExtensions,
+    installTimeoutMs: input.installTimeoutMs,
+    cli: input.cli,
+  });
+
+  const toolchains = missingToolchains(input.groups ?? [], input.env);
+
+  let server: Awaited<ReturnType<typeof ensureBackgroundServer>>;
+  let previousVersion: string | undefined;
+
+  let incompatibleRunning:
+    | { version: string; pid: number; startedBy: "user" | "cli" | "desktop" }
+    | undefined;
+
+  try {
+    const version = input.version ?? readReviewPackageVersion(import.meta.url);
+
+    const other = input.replace
+      ? await otherVersionRunning(input.stateDir, version)
+      : undefined;
+
+    if (other && (other.startedBy === "user" || newer(other.version, version)))
+      incompatibleRunning = other;
+    else if (other) {
+      await stopBackgroundServer({ serverPid: other.pid });
+      previousVersion = other.version;
+    }
+
+    server = await ensureBackgroundServer({
+      stateDir: input.stateDir,
+      env: input.env,
+      startedBy: "desktop",
+      cli: input.cli,
+    });
+  } catch (error) {
+    extensions.abort();
+    await Promise.all([language, toolchains]);
+    throw error;
+  }
+
+  const { discovery, started } = server;
+
+  const {
+    languageServer,
+    languageServerDetail,
+    languageServerPending,
+    languageGroups,
+  } = await language;
+
+  const missing = await toolchains;
+
+  const health = await readReviewServerHealth(discovery);
+
+  if (!health) throw serverNotReady(input.stateDir);
+
+  return {
+    event: "remote.attach" as const,
+    version: health.version ?? null,
+    commit: health.commit ?? null,
+    serverId: health.serverId ?? null,
+    url: discovery.url,
+    token: discovery.token,
+    startedServer: started,
+    languageServer,
+    ...(languageServerDetail !== undefined && { languageServerDetail }),
+    ...(languageServerPending && { languageServerPending }),
+    languageGroups: languageGroups.map(({ group, installed, detail }) => {
+      const details = [detail, missing.get(group)].filter(Boolean).join("; ");
+
+      return { group, installed, ...(details && { detail: details }) };
+    }),
+    ...(previousVersion !== undefined && { replaced: true, previousVersion }),
+    ...(incompatibleRunning && { incompatibleRunning }),
+  };
+}
+
+const newer = (running: string, own: string) =>
+  validVersion(running) !== null &&
+  validVersion(own) !== null &&
+  greaterVersion(running, own);
+
+async function otherVersionRunning(stateDir: string, version: string) {
+  const recorded = await recordedBackgroundServer(stateDir);
+
+  if (!recorded) return undefined;
+  const { discovery, health } = recorded;
+  const running = health.version ?? "unknown";
+
+  return running === version
+    ? undefined
+    : {
+        version: running,
+        pid: discovery.serverPid,
+        startedBy: discovery.startedBy,
+      };
+}