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

package/src/cli-runner.ts

@@ -2,19 +2,22 @@ import { existsSync } from "node:fs";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
 import { createInterface } from "node:readline/promises";
-import type { Writable } from "node:stream";
+import { Writable } from "node:stream";
 import { fileURLToPath } from "node:url";
 
+import {
+  REVIEW_CLI_INSTALL_TARGET_LABELS,
+  REVIEW_REMOTE_ATTACH_BEGIN,
+  REVIEW_REMOTE_ATTACH_END,
+} from "@dev.fast/review-protocol";
 import {
   StoreApiError,
-  processIsAlive,
   readStoreAuth,
   withStoreAuthorization,
 } from "@dev.fast/trace-core";
 import {
   type CliInputStream,
   DEFAULT_STORE_ORIGIN,
-  DEV_REVIEW_HOME_ENV,
   emitJsonEvent,
   humanStream,
   jsonRequestedInArgv,
@@ -42,10 +45,16 @@ import {
   windowsInstallerCommand,
 } from "./cli-install";
 import { cliRuntimeInfo, describeCliRuntime } from "./cli-runtime-info";
+import {
+  AGENT_CONNECT_TARGETS,
+  type AgentConnectTarget,
+  connectAgents,
+  detectAgents,
+} from "./connect-agents";
 import { connectPrompts } from "./connect-prompts";
 import {
   ReviewInstanceUnavailableError,
-  readReviewInstances,
+  desktopUsesHome,
   selectReviewInstance,
 } from "./desktop-discovery";
 import {
@@ -86,6 +95,8 @@ import {
   type ReviewTelemetryErrorName,
 } from "./review-telemetry";
 import {
+  DESKTOP_TAKEOVER_SIGNAL,
+  type ReviewServerDiscovery,
   readReviewServerDiscovery,
   readReviewServerHealth,
   reviewServerIsHealthy,
@@ -265,6 +276,16 @@ export async function runReviewCli(input: ReviewCliInput): Promise<number> {
       ? { ...env, DEV_REVIEW_SERVER_DIR: path.resolve(cwd, stateDir) }
       : env;
 
+  const refuse = (message: string, json?: boolean) => {
+    if (json)
+      emitReviewEvent(input.stdout, {
+        event: "error",
+        error: { name: "Error", message },
+      });
+    else input.stderr.write(`${message}\n`);
+    state.exitCode = 1;
+  };
+
   const serverCommand = configureOutput(
     program
       .command("server")
@@ -291,6 +312,16 @@ export async function runReviewCli(input: ReviewCliInput): Promise<number> {
         "--software-maps",
         "allow the authoring skill to generate optional software maps",
       )
+      .option(
+        "--detach",
+        "start the server in the background, logging to review-server/server.log",
+      )
+      .addOption(
+        new Option("--started-by <who>")
+          .choices(["user", "cli", "desktop"])
+          .default("user")
+          .hideHelp(),
+      )
       // Batch authoring was removed; name that instead of "unknown option".
       .addOption(new Option("--authoring-mode <mode>").hideHelp()),
     "plain",
@@ -299,6 +330,8 @@ export async function runReviewCli(input: ReviewCliInput): Promise<number> {
       stateDir?: string;
       port: string;
       softwareMaps?: boolean;
+      detach?: boolean;
+      startedBy: "user" | "cli" | "desktop";
       authoringMode?: string;
       json?: boolean;
     }>();
@@ -314,17 +347,49 @@ export async function runReviewCli(input: ReviewCliInput): Promise<number> {
         "--port must be an integer between 0 and 65535.",
       );
     const stateDir = reviewServerStateDir(authoringEnv(options.stateDir));
+
+    if (options.detach) {
+      const { ensureBackgroundServer } =
+        await import("./server/background-server.js");
+
+      const { discovery, started } = await ensureBackgroundServer({
+        stateDir,
+        env,
+        args: [
+          "--port",
+          `${port}`,
+          ...(options.softwareMaps ? ["--software-maps"] : []),
+        ],
+      });
+
+      await writeServerStatus(discovery, stateDir, options.json, { started });
+
+      return;
+    }
+
     const controller = new AbortController();
     const stop = () => controller.abort();
+
+    const takeover = () => {
+      input.stderr.write(
+        `Whiteboard Desktop took over ${stateDir}; stopping this server.\n`,
+      );
+      stop();
+    };
+
     process.once("SIGINT", stop);
     process.once("SIGTERM", stop);
+    process.once(DESKTOP_TAKEOVER_SIGNAL, takeover);
+
+    const { HeadlessServerBusyError, runHeadlessServer } =
+      await import("./server/headless-host.js");
 
     try {
-      const { runHeadlessServer } = await import("./server/headless-host.js");
       await runHeadlessServer({
         stateDir,
         port,
         softwareMapEnabled: options.softwareMaps,
+        startedBy: options.startedBy,
         signal: controller.signal,
         telemetry,
         onReady: ({ url, serverPid }) => {
@@ -335,9 +400,13 @@ export async function runReviewCli(input: ReviewCliInput): Promise<number> {
           );
         },
       });
+    } catch (error) {
+      if (!(error instanceof HeadlessServerBusyError)) throw error;
+      refuse(error.message, options.json);
     } finally {
       process.off("SIGINT", stop);
       process.off("SIGTERM", stop);
+      process.off(DESKTOP_TAKEOVER_SIGNAL, takeover);
     }
   });
 
@@ -358,15 +427,64 @@ export async function runReviewCli(input: ReviewCliInput): Promise<number> {
 
     const stateDir = reviewServerStateDir(authoringEnv(options.stateDir));
     const discovery = await readReviewServerDiscovery(stateDir);
-    const health = discovery && (await readReviewServerHealth(discovery));
 
-    if (!discovery || !health) throw serverNotReady(stateDir);
-    const { url, serverPid } = discovery;
-    const { version, serverId } = health;
+    if (!discovery) throw serverNotReady(stateDir);
+    await writeServerStatus(discovery, stateDir, options.json);
+  });
+
+  configureJsonOutput(
+    serverCommand
+      .command("stop")
+      .description(
+        "Stop a background server started by --detach, the CLI, or Desktop",
+      )
+      .option(
+        "--state-dir <path>",
+        "directory selected when starting the server",
+      ),
+    "plain",
+  ).action(async (_options, command: Command) => {
+    const options = command.optsWithGlobals<{
+      stateDir?: string;
+      json?: boolean;
+    }>();
+
+    const stateDir = reviewServerStateDir(authoringEnv(options.stateDir));
+
+    const { headlessServerOwner, stopBackgroundServer } =
+      await import("./server/background-server.js");
+
+    const owner = await headlessServerOwner(stateDir);
+    const discovery = await readReviewServerDiscovery(stateDir);
+
+    if (owner === undefined) {
+      input.stdout.write(
+        options.json
+          ? `${JSON.stringify({ event: "server.stop", stopped: false, stateDir })}\n`
+          : `No Whiteboard server is running in ${stateDir}.\n`,
+      );
+
+      return;
+    }
+
+    const serverPid = owner;
+
+    if (discovery?.serverPid !== owner)
+      throw new Error(
+        `Process ${owner} holds the Whiteboard server's lock in ${stateDir} but has published no server; it may be starting. Try again, or end that process.`,
+      );
+
+    if (discovery.startedBy === "user")
+      throw new Error(
+        `The Whiteboard server in ${stateDir} (process ${serverPid}) runs in the foreground of \`whiteboard server start\`. Stop it there with Ctrl-C.`,
+      );
+
+    await stopBackgroundServer(discovery);
+
     input.stdout.write(
       options.json
-        ? `${JSON.stringify({ event: "server.status", ready: true, url, serverPid, stateDir, version, serverId })}\n`
-        : `Whiteboard server ready at ${url}\nSaved reviews: ${stateDir}\n`,
+        ? `${JSON.stringify({ event: "server.stop", stopped: true, serverPid, stateDir })}\n`
+        : `Stopped the Whiteboard server (process ${serverPid}).\n`,
     );
   });
 
@@ -394,32 +512,10 @@ export async function runReviewCli(input: ReviewCliInput): Promise<number> {
         `No saved reviews in ${stateDir}, so there is no server id to reset. Check --state-dir.`,
       );
 
-    // 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.
-    const desktops = await readReviewInstances({
-      env: { ...env, [DEV_REVIEW_HOME_ENV]: stateDir },
-    });
-
-    const [problem] = desktops.broken.values();
-
-    if (problem)
-      throw new Error(
-        `Cannot tell whether a Whiteboard Desktop is using ${stateDir}: ${problem.message}`,
-      );
-
-    const inUse = () =>
-      new Error(
-        `A Whiteboard server is using ${stateDir}. Stop it first, then run whiteboard server reset-id again.`,
-      );
+    const inUse = `A Whiteboard server is using ${stateDir}. Stop it first, then run whiteboard server reset-id again.`;
 
-    if (
-      desktops.instances.some(({ discovery }) =>
-        [discovery.appPid, discovery.serverPid].some((pid) =>
-          processIsAlive(pid),
-        ),
-      )
-    )
-      throw inUse();
+    if (await desktopUsesHome(stateDir, env))
+      return refuse(inUse, options.json);
 
     const [{ openReviewProfile }, { withHeadlessServerLock }] =
       await Promise.all([
@@ -445,7 +541,7 @@ export async function runReviewCli(input: ReviewCliInput): Promise<number> {
       },
     );
 
-    if (!reset.acquired) throw inUse();
+    if (!reset.acquired) return refuse(inUse, options.json);
     const serverId = reset.result;
 
     input.stdout.write(
@@ -455,6 +551,239 @@ export async function runReviewCli(input: ReviewCliInput): Promise<number> {
     );
   });
 
+  const remote = configureOutput(
+    program
+      .command("remote")
+      .description("Serve reviews to Whiteboard Desktop over SSH"),
+    "plain",
+  );
+
+  configureJsonOutput(
+    remote
+      .command("attach")
+      .description(
+        "Start a background server if none is healthy and report how to reach it",
+      )
+      .option(
+        "--state-dir <path>",
+        "directory for saved reviews and server discovery",
+      )
+      .option(
+        "--groups <groups>",
+        "comma-separated optional extension groups the Desktop has enabled, such as go",
+      )
+      .option(
+        "--replace",
+        "stop a running server of another version that the CLI or Desktop started, and start this one",
+      ),
+    "plain",
+  ).action(async (_options, command: Command) => {
+    const options = command.optsWithGlobals<{
+      stateDir?: string;
+      json?: boolean;
+      groups?: string;
+      replace?: boolean;
+    }>();
+
+    const stateDir = reviewServerStateDir(authoringEnv(options.stateDir));
+
+    const { remoteAttach } = await import("./remote-attach.js");
+
+    let attach: Awaited<ReturnType<typeof remoteAttach>>;
+
+    try {
+      attach = await remoteAttach({
+        stateDir,
+        env,
+        groups: options.groups?.split(",").map((group) => group.trim()),
+        replace: options.replace,
+      });
+    } catch (error) {
+      if (!options.json) throw error;
+
+      let line = "";
+
+      emitReviewEvent(
+        new Writable({
+          write(chunk, _encoding, done) {
+            line += chunk;
+            done();
+          },
+        }),
+        { event: "error", error: serializeReviewError(error) },
+      );
+      input.stdout.write(
+        `${REVIEW_REMOTE_ATTACH_BEGIN}\n${ensureTrailingNewline(line)}${REVIEW_REMOTE_ATTACH_END}\n`,
+      );
+      state.exitCode = 1;
+
+      return;
+    }
+
+    input.stdout.write(
+      options.json
+        ? `${REVIEW_REMOTE_ATTACH_BEGIN}\n${JSON.stringify(attach)}\n${REVIEW_REMOTE_ATTACH_END}\n`
+        : `Whiteboard server ${attach.startedServer ? "started" : "already running"} at ${attach.url}\nLanguage features: ${attach.languageServer ? `VS Code server on port ${attach.languageServer.port}` : `unavailable (${attach.languageServerDetail})`}\n`,
+    );
+  });
+
+  configureJsonOutput(
+    remote
+      .command("extensions")
+      .description("Language extensions for the VS Code server on a remote")
+      .command("ensure")
+      .description(
+        "Download the curated extensions for this machine and list them for the VS Code server",
+      )
+      .option(
+        "--groups <groups>",
+        "comma-separated optional extension groups the Desktop has enabled, such as go",
+      ),
+    "plain",
+  ).action(async (_options, command: Command) => {
+    const { json, groups } = command.optsWithGlobals<{
+      json?: boolean;
+      groups?: string;
+    }>();
+
+    const { ensureRemoteExtensions } = await import("./remote-extensions.js");
+
+    const result = await ensureRemoteExtensions({
+      env,
+      groups: groups?.split(",").map((group) => group.trim()),
+    });
+
+    input.stdout.write(
+      json
+        ? `${JSON.stringify(result)}\n`
+        : [
+            ...result.installed.map((id) => `Installed ${id}`),
+            ...result.skipped.map(
+              ({ id, reason }) => `Skipped ${id}: ${reason}`,
+            ),
+            ...result.failed.map(({ id, error }) => `Failed ${id}: ${error}`),
+          ]
+            .map((line) => `${line}\n`)
+            .join(""),
+    );
+    state.exitCode = result.failed.length > 0 ? 1 : 0;
+  });
+
+  configureJsonOutput(
+    remote
+      .command("uninstall")
+      .description(
+        "Remove what Whiteboard Desktop installed on this host, stopping a server it started",
+      )
+      .addOption(
+        new Option(
+          "--keep-reviews",
+          "leave the saved reviews in place",
+        ).conflicts("deleteReviews"),
+      )
+      .addOption(
+        new Option("--delete-reviews", "also delete the saved reviews"),
+      )
+      .option(
+        "--state-dir <path>",
+        "directory for saved reviews and server discovery",
+      ),
+    "plain",
+  ).action(async (_options, command: Command) => {
+    const options = command.optsWithGlobals<{
+      stateDir?: string;
+      json?: boolean;
+      keepReviews?: boolean;
+      deleteReviews?: boolean;
+    }>();
+
+    const stateDir = reviewServerStateDir(authoringEnv(options.stateDir));
+    const { remoteUninstall } = await import("./remote-uninstall.js");
+
+    let deleteReviews = options.deleteReviews
+      ? true
+      : options.keepReviews
+        ? false
+        : undefined;
+
+    if (deleteReviews === undefined && !options.json && input.stdin?.isTTY) {
+      const prompt = createInterface({
+        input: input.stdin,
+        output: input.stderr,
+      });
+
+      try {
+        deleteReviews = /^y(es)?$/i.test(
+          (
+            await prompt.question(
+              `Also delete the saved reviews in ${stateDir}? [y/N] `,
+            )
+          ).trim(),
+        );
+      } finally {
+        prompt.close();
+      }
+    }
+
+    const result =
+      deleteReviews === undefined
+        ? {
+            event: "remote.uninstall" as const,
+            ok: false as const,
+            reason:
+              "Say what happens to the saved reviews: pass --keep-reviews or --delete-reviews.",
+          }
+        : await remoteUninstall({
+            home: env.HOME ?? "",
+            env,
+            stateDir,
+            deleteReviews,
+          });
+
+    if (!result.ok) {
+      if (!options.json) throw new Error(result.reason);
+      input.stdout.write(`${JSON.stringify(result)}\n`);
+      state.exitCode = 1;
+
+      return;
+    }
+
+    input.stdout.write(
+      options.json
+        ? `${JSON.stringify(result)}\n`
+        : [
+            ...(result.stoppedServer
+              ? [
+                  `Stopped the Whiteboard server (process ${result.stoppedServer.pid}).`,
+                ]
+              : []),
+            ...result.removed.map((removed) => `Removed ${removed}`),
+            result.keptReviews
+              ? `Saved reviews kept in ${stateDir}`
+              : "Saved reviews deleted.",
+            "",
+          ].join("\n"),
+    );
+  });
+
+  async function writeServerStatus(
+    discovery: ReviewServerDiscovery,
+    stateDir: string,
+    json: boolean | undefined,
+    extra: { started?: boolean } = {},
+  ) {
+    const health = await readReviewServerHealth(discovery);
+
+    if (!health) throw serverNotReady(stateDir);
+    const { url, serverPid } = discovery;
+    const { version, serverId } = health;
+    input.stdout.write(
+      json
+        ? `${JSON.stringify({ event: "server.status", ready: true, url, serverPid, stateDir, version, serverId, ...extra })}\n`
+        : `Whiteboard server ${extra.started === false ? "already running" : "ready"} at ${url}\nSaved reviews: ${stateDir}\n`,
+    );
+  }
+
   configureJsonOutput(
     program
       .command("version")
@@ -662,53 +991,125 @@ export async function runReviewCli(input: ReviewCliInput): Promise<number> {
           "copilot",
           "all",
         ]),
+      )
+      .addOption(
+        new Option(
+          "--detect",
+          "list the agents on this machine and whether each is connected; changes nothing",
+        ).conflicts("yes"),
+      )
+      .option(
+        "--yes",
+        "run the commands the prompt gives, without an agent: claude, codex, opencode or pi",
       ),
     "plain",
   );
 
-  connect.action(async (targets: string[], options: { json?: boolean }) => {
-    const selected = parseTargets(targets);
+  connect.action(
+    async (
+      targets: string[],
+      options: { json?: boolean; detect?: boolean; yes?: boolean },
+    ) => {
+      const output = {
+        json: options.json,
+        stdout: input.stdout,
+        stderr: input.stderr,
+      };
+
+      if (options.detect) {
+        const agents = await detectAgents({ homeDir: scope.homeDir, env });
+
+        if (options.json) {
+          emitJsonEvent(output, { event: "connect.detect", agents });
+
+          return;
+        }
+
+        humanStream(output).write(
+          agents.length
+            ? `${agents.map((agent) => `${agent.name}: ${agent.connected ? "connected" : "not connected"}${agent.manual ? " (its command is not on PATH)" : ""}`).join("\n")}\n`
+            : "No agents found.\n",
+        );
+
+        return;
+      }
 
-    const { homeDir, devHome } = scope;
+      if (options.yes) {
+        const agents = parseTargets(targets);
 
-    const prompts = connectPrompts({
-      legacyPaths: await scanLegacySkills(homeDir),
-      hasShim:
-        (await isOwnedShim(pathShimPath(homeDir))) ||
-        (await windowsInstallerCommand(
-          findReviewPackageRoot(import.meta.url),
+        if (
+          targets.length === 0 ||
+          !agents.every((target): target is AgentConnectTarget =>
+            AGENT_CONNECT_TARGETS.some((known) => known === target),
+          )
+        )
+          throw new Error(
+            "connect --yes takes one or more of claude, codex, opencode or pi.",
+          );
+
+        const results = await connectAgents({
+          agents,
+          homeDir: scope.homeDir,
           env,
-        )) !== undefined,
-      traceEnabled: await traceMachineEnabled({ homeDir, env }),
-      fffBinaryPath: path.join(homeDir, ".local", "bin", "fff-mcp"),
-      fffCorpusRoot: path.join(devHome, "trace-search"),
-    });
+        });
 
-    const output = {
-      json: options.json,
-      stdout: input.stdout,
-      stderr: input.stderr,
-    };
+        state.exitCode = results.every((result) => result.connected) ? 0 : 1;
 
-    if (options.json) {
-      emitJsonEvent(output, {
-        event: "connect",
-        prompts: Object.fromEntries(
-          selected.map((target) => [target, prompts[target]]),
-        ),
+        if (options.json) {
+          emitJsonEvent(output, { event: "connect.run", agents: results });
+
+          return;
+        }
+
+        humanStream(output).write(
+          results
+            .map(
+              (result) =>
+                `${result.output}${result.name}: ${result.connected ? "connected" : "not connected"}\n`,
+            )
+            .join(""),
+        );
+
+        return;
+      }
+
+      const selected = parseTargets(targets);
+
+      const { homeDir, devHome } = scope;
+
+      const prompts = connectPrompts({
+        legacyPaths: await scanLegacySkills(homeDir),
+        hasShim:
+          (await isOwnedShim(pathShimPath(homeDir))) ||
+          (await windowsInstallerCommand(
+            findReviewPackageRoot(import.meta.url),
+            env,
+          )) !== undefined,
+        traceEnabled: await traceMachineEnabled({ homeDir, env }),
+        fffBinaryPath: path.join(homeDir, ".local", "bin", "fff-mcp"),
+        fffCorpusRoot: path.join(devHome, "trace-search"),
       });
 
-      return;
-    }
+      if (options.json) {
+        emitJsonEvent(output, {
+          event: "connect",
+          prompts: Object.fromEntries(
+            selected.map((target) => [target, prompts[target]]),
+          ),
+        });
 
-    const sections = selected.map((target) =>
-      selected.length > 1
-        ? `## ${TARGET_LABELS[target]}\n\n${prompts[target]}`
-        : prompts[target],
-    );
+        return;
+      }
 
-    humanStream(output).write(`${sections.join("\n\n")}\n`);
-  });
+      const sections = selected.map((target) =>
+        selected.length > 1
+          ? `## ${REVIEW_CLI_INSTALL_TARGET_LABELS[target]}\n\n${prompts[target]}`
+          : prompts[target],
+      );
+
+      humanStream(output).write(`${sections.join("\n\n")}\n`);
+    },
+  );
 
   const migrate = configureOutput(
     program.command("migrate", { hidden: true }),
@@ -1137,16 +1538,6 @@ export async function runReviewCli(input: ReviewCliInput): Promise<number> {
   }
 }
 
-const TARGET_LABELS: Record<InstallTarget, string> = {
-  claude: "Claude Code",
-  codex: "Codex",
-  cursor: "Cursor",
-  opencode: "OpenCode",
-  pi: "Pi",
-  omp: "oh-my-pi",
-  copilot: "Copilot CLI",
-};
-
 function parseTargets(targets: readonly string[]): InstallTarget[] {
   if (targets.length === 0 || targets.includes("all")) {
     return [...ALL_INSTALL_TARGETS];

package/src/cli.ts

@@ -71,7 +71,7 @@ async function maybeDelegateToDesktopCli(
   if (
     argv.some(
       (argument) =>
-        ["api", "mcp", "server", "instances"].includes(argument) ||
+        ["api", "mcp", "server", "remote", "instances"].includes(argument) ||
         /^--state-dir(?:=|$)/.test(argument),
     ) ||
     env.DEV_REVIEW_SERVER_DIR?.trim()