@dsdenes/devboard 0.1.560 → 0.1.562

package/server/scout.ts

@@ -0,0 +1,459 @@
+import { spawn } from "node:child_process";
+import { readFileSync, readlinkSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { liveLockOwner, pidAlive, type LockOwner } from "../issues/lock";
+import {
+  controlDirectory,
+  lockPath,
+  scanDirectory,
+  settingsPath,
+  statePath,
+} from "../issues/scout/paths";
+import { writeCommand, type ScoutCommand } from "../issues/scout/control";
+import { preflightScout, type ScoutPreflightResult } from "../issues/scout/preflight";
+import { cachedRepository } from "../issues/repository";
+import {
+  DEFAULT_LIMITS,
+  isValidLimit,
+  readSettings,
+  readState,
+  writeSettings,
+  type ScoutIssueRow,
+  type ScoutLimits,
+  type ScoutState,
+  type ScoutSync,
+} from "../issues/scout/state";
+import { readActivity } from "../issues/state";
+import { activityDelta } from "./activity";
+
+/**
+ * The dashboard half of Auto Scout. It never owns a scan loop, an agent, or a
+ * lock: it reads the worker's repo-scoped board, replays its activity, and
+ * writes commands to it. A worker started here is detached in its own session,
+ * so killing this server leaves it running and a replacement reattaches.
+ */
+
+export interface ScoutSnapshot {
+  present: boolean;
+  repo: string | null;
+  root: string;
+  lifecycle: ScoutState["lifecycle"];
+  enabled: boolean;
+  attached: boolean;
+  worker: ScoutState["worker"];
+  /** The limits the dashboard persisted, so a save shows without a worker. */
+  limits: ScoutLimits;
+  issues: ScoutIssueRow[];
+  sync: ScoutSync;
+  scan: ScoutState["scan"];
+  newestScanId: string | null;
+  nextAttemptAt: string | null;
+  lastError: string | null;
+  notice: string | null;
+  updatedAt: string | null;
+}
+
+export interface ScoutActivityEntry {
+  text: string;
+  append: boolean;
+}
+
+export interface ScoutBridgeOptions {
+  repoDir: string;
+  stateDir: string;
+  agentCommand: string;
+  runningVersion: string | null;
+  harnessDir: string;
+  send: (event: unknown, except?: { send(data: string): unknown }) => void;
+  log?: (line: string) => void;
+  environment?: Record<string, string | undefined>;
+  pollMs?: number;
+  /** Test seams: replace the start preflight and the detached spawn. */
+  preflight?: (options: {
+    repoDir: string;
+    stateDir: string;
+    environment: Record<string, string | undefined>;
+  }) => Promise<ScoutPreflightResult>;
+  spawnWorker?: (argv: string[], environment: Record<string, string | undefined>) => number | undefined;
+}
+
+export class ScoutBridge {
+  private readonly repoDir: string;
+  private readonly stateDir: string;
+  private readonly agentCommand: string;
+  private readonly runningVersion: string | null;
+  private readonly harnessDir: string;
+  private readonly send: (event: unknown, except?: { send(data: string): unknown }) => void;
+  private readonly environment: Record<string, string | undefined>;
+  private readonly repository: () => string | null;
+  private readonly preflight: NonNullable<ScoutBridgeOptions["preflight"]>;
+  private readonly spawnWorker: NonNullable<ScoutBridgeOptions["spawnWorker"]>;
+  private readonly log: (line: string) => void;
+  private readonly pollMsValue: number;
+
+  private timer: Timer | undefined;
+  private lastSignature = "";
+  private lastActivityScanId: string | null = null;
+  private lastActivity: string[] = [];
+  private stopping: { pid: number; timer: Timer } | undefined;
+  private starting = false;
+
+  constructor(options: ScoutBridgeOptions) {
+    this.repoDir = resolve(options.repoDir);
+    this.stateDir = resolve(options.stateDir);
+    this.agentCommand = options.agentCommand;
+    this.runningVersion = options.runningVersion;
+    this.harnessDir = options.harnessDir;
+    this.send = options.send;
+    this.environment = options.environment ?? process.env;
+    this.repository = cachedRepository(this.repoDir);
+    this.log = options.log ?? (() => undefined);
+    this.pollMsValue = Math.max(50, options.pollMs ?? 250);
+    this.preflight =
+      options.preflight ??
+      ((request) =>
+        preflightScout({
+          repoDir: request.repoDir,
+          stateDir: request.stateDir,
+          environment: request.environment,
+        }));
+    this.spawnWorker = options.spawnWorker ?? ((argv, environment) => this.detach(argv, environment));
+  }
+
+  /** Starts observing the worker state; it never starts a worker itself. */
+  begin(): void {
+    if (this.timer !== undefined) return;
+    this.timer = setInterval(() => this.refresh(), this.pollMsValue);
+    void this.refresh();
+  }
+
+  dispose(): void {
+    if (this.timer !== undefined) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+    if (this.stopping !== undefined) {
+      clearTimeout(this.stopping.timer);
+      this.stopping = undefined;
+    }
+  }
+
+  private detach(argv: string[], environment: Record<string, string | undefined>): number | undefined {
+    try {
+      const child = spawn(argv[0]!, argv.slice(1), {
+        cwd: this.repoDir,
+        env: environment,
+        detached: true,
+        stdio: "ignore",
+      });
+      child.unref();
+      return child.pid;
+    } catch (error) {
+      this.log(
+        `could not start the scout worker: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return undefined;
+    }
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Reading                                                             */
+  /* ------------------------------------------------------------------ */
+
+  private currentState(): ScoutState | undefined {
+    return readState(statePath(this.stateDir, this.repoDir));
+  }
+
+  private lockOwner(): LockOwner | undefined {
+    return liveLockOwner(lockPath(this.repoDir));
+  }
+
+  /** True when there is a worker state or a live lock to replay. */
+  get present(): boolean {
+    return this.currentState() !== undefined || this.lockOwner() !== undefined;
+  }
+
+  snapshot(): ScoutSnapshot {
+    const state = this.currentState();
+    const owner = this.lockOwner();
+    const attached =
+      owner !== undefined && resolve(owner.stateDir) === this.stateDir && pidAlive(owner.pid);
+    const active = attached ? state : undefined;
+    const lifecycle =
+      active?.lifecycle === "stopped" || active === undefined ? "stopped" : active.lifecycle;
+    const worker = state?.worker ?? null;
+    const mismatch =
+      attached && worker !== null && worker.harnessVersion !== this.runningVersion
+        ? `Auto Scout worker ${worker.harnessVersion ?? "unknown"} is running; this dashboard ` +
+          `loaded ${this.runningVersion ?? "unknown"}. It is left running; Stop it to launch the ` +
+          "current harness on the next Start."
+        : null;
+    const limits = readSettings(settingsPath(this.stateDir, this.repoDir)) ?? state?.limits;
+    return {
+      present: state !== undefined,
+      repo: state !== undefined && state.repo.length > 0 ? state.repo : this.repository(),
+      root: this.repoDir,
+      lifecycle,
+      enabled: active?.enabled === true && lifecycle !== "stopped",
+      attached,
+      worker: active?.worker ?? null,
+      limits: limits ?? { ...DEFAULT_LIMITS },
+      issues: state?.issues ?? [],
+      sync: state?.sync ?? { state: "stale", at: null, error: null },
+      scan: active?.scan ?? null,
+      newestScanId: state?.newestScanId ?? null,
+      nextAttemptAt: active?.nextAttemptAt ?? null,
+      lastError: active?.lastError ?? null,
+      notice: mismatch ?? active?.notice ?? null,
+      updatedAt: state?.updatedAt ?? null,
+    };
+  }
+
+  /**
+   * A connect-time replay: state to the caller, then the newest scan's whole
+   * activity to the caller and every other client. The baseline is shared, so
+   * advancing it for one client alone would make the next delta skip what the
+   * older clients missed.
+   */
+  replay(target?: { send(data: string): unknown }): void {
+    const deliver =
+      target === undefined
+        ? this.send
+        : (event: unknown) => {
+            try {
+              target.send(JSON.stringify(event));
+            } catch {
+              // The socket closed before the replay finished.
+            }
+          };
+    const snapshot = this.snapshot();
+    deliver({ type: "scoutState", ...snapshot });
+    const scanId = snapshot.scan?.scanId ?? snapshot.newestScanId;
+    if (scanId === null) return;
+    const activity = this.readActivity(scanId);
+    this.lastActivityScanId = scanId;
+    this.lastActivity = activity;
+    const event = {
+      type: "scoutActivity",
+      scanId,
+      replay: true,
+      entries: activity.map((text) => ({ text, append: false })),
+    };
+    deliver(event);
+    // A targeted replay also reaches the other clients: the baseline is shared,
+    // so a replay only the new client saw would make the next delta skip it.
+    if (target !== undefined) this.send(event, target);
+  }
+
+  private readActivity(scanId: string): string[] {
+    return readActivity(scanDirectory(this.repoDir, scanId));
+  }
+
+  private publishActivity(scanId: string, activity: string[]): void {
+    if (this.lastActivityScanId !== scanId) {
+      this.lastActivityScanId = scanId;
+      this.lastActivity = activity;
+      this.send({
+        type: "scoutActivity",
+        scanId,
+        replay: true,
+        entries: activity.map((text) => ({ text, append: false })),
+      });
+      return;
+    }
+    const delta = activityDelta(this.lastActivity, activity);
+    this.lastActivity = activity;
+    if (!delta.replay && delta.entries.length === 0) return;
+    this.send({
+      type: "scoutActivity",
+      scanId,
+      ...(delta.replay ? { replay: true } : {}),
+      entries: delta.entries,
+    });
+  }
+
+  refresh(): void {
+    const snapshot = this.snapshot();
+    const signature = JSON.stringify(snapshot);
+    if (signature !== this.lastSignature) {
+      this.lastSignature = signature;
+      this.send({ type: "scoutState", ...snapshot });
+    }
+    // The page shows the current scan, or the newest one once it finishes.
+    const scanId = snapshot.scan?.scanId ?? snapshot.newestScanId;
+    if (scanId === null) {
+      this.lastActivityScanId = null;
+      this.lastActivity = [];
+      return;
+    }
+    this.publishActivity(scanId, this.readActivity(scanId));
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Commands                                                            */
+  /* ------------------------------------------------------------------ */
+
+  async start(): Promise<{ ok: true; attached: boolean } | { ok: false; message: string }> {
+    if (this.starting) return { ok: true, attached: false };
+    const owner = this.lockOwner();
+    if (owner !== undefined) {
+      if (resolve(owner.stateDir) !== this.stateDir) {
+        return {
+          ok: false,
+          message:
+            `this checkout already has an Auto Scout worker (pid ${owner.pid}) using ` +
+            `${owner.stateDir}; this dashboard's STATE_DIR is ${this.stateDir}`,
+        };
+      }
+      this.refresh();
+      return { ok: true, attached: true };
+    }
+
+    this.starting = true;
+    try {
+      const result = await this.preflight({
+        repoDir: this.repoDir,
+        stateDir: this.stateDir,
+        environment: this.environment,
+      });
+      if (!result.ok) return result;
+      return await this.spawn();
+    } finally {
+      this.starting = false;
+    }
+  }
+
+  private async spawn(): Promise<{ ok: true; attached: boolean } | { ok: false; message: string }> {
+    const argv = [
+      process.execPath,
+      join(this.harnessDir, "issues", "scout", "worker.ts"),
+      "--repo",
+      this.repoDir,
+      "--state-dir",
+      this.stateDir,
+    ];
+    const pid = this.spawnWorker(argv, {
+      ...this.environment,
+      REPO_DIR: this.repoDir,
+      STATE_DIR: this.stateDir,
+      AGENT_COMMAND: this.agentCommand,
+    });
+    if (pid === undefined) {
+      return { ok: false, message: "the Auto Scout worker could not be started" };
+    }
+    return { ok: true, attached: false };
+  }
+
+  /**
+   * Saves both caps. The settings file is the durable source, so a save shows
+   * after a reload and is read by the next worker start; a running worker is
+   * told immediately through its command channel.
+   */
+  setLimits(
+    maxPerHour: unknown,
+    maxPending: unknown,
+  ): { ok: true } | { ok: false; message: string } {
+    if (!isValidLimit(maxPerHour) || !isValidLimit(maxPending)) {
+      return {
+        ok: false,
+        message: "Both limits must be integers from 1 through 100.",
+      };
+    }
+    const limits: ScoutLimits = { maxPerHour, maxPending };
+    try {
+      writeSettings(settingsPath(this.stateDir, this.repoDir), limits);
+    } catch (error) {
+      return {
+        ok: false,
+        message: `Could not save the limits: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+    const owner = this.lockOwner();
+    if (owner !== undefined && resolve(owner.stateDir) === this.stateDir) {
+      try {
+        writeCommand(controlDirectory(this.stateDir, this.repoDir), {
+          type: "limits",
+          maxPerHour,
+          maxPending,
+        });
+      } catch (error) {
+        return {
+          ok: false,
+          message: `Could not reach the worker: ${error instanceof Error ? error.message : String(error)}`,
+        };
+      }
+    }
+    this.refresh();
+    return { ok: true };
+  }
+
+  stop(): { ok: true } | { ok: false; message: string } {
+    return this.command({ type: "stop" });
+  }
+
+  private command(command: ScoutCommand): { ok: true } | { ok: false; message: string } {
+    const owner = this.lockOwner();
+    if (owner === undefined) {
+      return { ok: false, message: "No Auto Scout worker is running for this checkout." };
+    }
+    if (resolve(owner.stateDir) !== this.stateDir) {
+      return {
+        ok: false,
+        message:
+          `the Auto Scout worker (pid ${owner.pid}) uses ${owner.stateDir}; this dashboard's ` +
+          `STATE_DIR is ${this.stateDir}`,
+      };
+    }
+    // The live lock proves a worker exists even when its state file is absent,
+    // unreadable, or left by another harness version; Stop must still reach it.
+    writeCommand(controlDirectory(this.stateDir, this.repoDir), command);
+    if (command.type === "stop") this.scheduleStopProof(owner.pid);
+    return { ok: true };
+  }
+
+  /**
+   * Stop must end a worker that is still alive after the command. Only a
+   * process the table proves is this checkout's scout is signalled.
+   */
+  private scheduleStopProof(pid: number): void {
+    if (this.stopping !== undefined) clearTimeout(this.stopping.timer);
+    const timer = setTimeout(() => {
+      this.stopping = undefined;
+      if (!pidAlive(pid)) return;
+      if (!this.provesWorker(pid)) return;
+      try {
+        process.kill(pid, "SIGTERM");
+      } catch {
+        return;
+      }
+      const killTimer = setTimeout(() => {
+        if (!pidAlive(pid)) return;
+        if (!this.provesWorker(pid)) return;
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {
+          // It exited between the proof and the signal.
+        }
+      }, 2000);
+      killTimer.unref?.();
+    }, 3000);
+    timer.unref?.();
+    this.stopping = { pid, timer };
+  }
+
+  private provesWorker(pid: number): boolean {
+    let argv: string[];
+    try {
+      argv = readFileSync(`/proc/${pid}/cmdline`, "utf8").split("\u0000").filter(Boolean);
+    } catch {
+      return false;
+    }
+    if (!argv.some((entry) => entry.endsWith(join("scout", "worker.ts")))) return false;
+    if (!argv.includes(this.repoDir)) return false;
+    try {
+      return readlinkSync(`/proc/${pid}/cwd`) === this.repoDir;
+    } catch {
+      return false;
+    }
+  }
+}