@dsdenes/devboard 0.1.559 → 0.1.562

package/index.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en" data-theme="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="/favicon.ico" sizes="any" />
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+    <title>Devboard</title>
+    <script>
+      (function () {
+        var theme = "dark";
+        try {
+          var stored = localStorage.getItem("devboard.theme");
+          if (stored === "light" || stored === "dark") theme = stored;
+        } catch (error) {
+          /* A blocked localStorage keeps the dark default. */
+        }
+        document.documentElement.dataset.theme = theme;
+        document.documentElement.style.colorScheme = theme;
+      })();
+    </script>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/client/main.ts"></script>
+  </body>
+</html>

package/install.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# Install the harness agent wrappers into the host's .omp directory.
+#
+# Usage: install.sh [--force] [host-path]
+#
+# Copies every file under this directory's omp/ tree to the same relative path
+# under <host>/.omp/. The host path is discovered with
+# `git rev-parse --show-toplevel` when omitted. Files that already match are left
+# untouched, unrelated files in <host>/.omp/ are never removed, and a differing
+# file stops the run unless --force is given.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: install.sh [--force] [host-path]
+
+Copies every file under omp/ to <host>/.omp/ at the same relative path.
+The host path defaults to the git repository root of the current directory.
+
+  --force      overwrite files that differ from the installed copy
+  -h, --help   show this help
+EOF
+}
+
+force=0
+host_arg=""
+for arg in "$@"; do
+  case "$arg" in
+    --force) force=1 ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    -*)
+      printf 'install: unknown option: %s\n' "$arg" >&2
+      usage >&2
+      exit 2
+      ;;
+    *)
+      if [ -n "$host_arg" ]; then
+        printf 'install: unexpected extra argument: %s\n' "$arg" >&2
+        exit 2
+      fi
+      host_arg="$arg"
+      ;;
+  esac
+done
+
+source_dir=$(cd -- "$(dirname -- "$0")" && pwd)
+source_omp="$source_dir/omp"
+if [ ! -d "$source_omp" ]; then
+  printf 'install: no omp directory beside %s\n' "$0" >&2
+  exit 1
+fi
+
+if [ -z "$host_arg" ]; then
+  if ! host_arg=$(git rev-parse --show-toplevel 2>/dev/null); then
+    printf 'install: no host path given and the working directory is not a git work tree\n' >&2
+    exit 1
+  fi
+fi
+
+if ! host=$(cd -- "$host_arg" 2>/dev/null && pwd); then
+  printf 'install: host path does not exist: %s\n' "$host_arg" >&2
+  exit 1
+fi
+
+if [ ! -d "$host/.devboard" ]; then
+  printf 'install: no .devboard directory in %s; install the harness there first\n' "$host" >&2
+  exit 1
+fi
+
+target_omp="$host/.omp"
+
+relative_paths=()
+while IFS= read -r -d '' source_file; do
+  relative_paths+=("${source_file#"$source_omp"/}")
+done < <(find "$source_omp" -type f -print0)
+
+if [ "${#relative_paths[@]}" -eq 0 ]; then
+  printf 'install: no files under %s\n' "$source_omp" >&2
+  exit 1
+fi
+
+conflicts=()
+for relative_path in "${relative_paths[@]}"; do
+  destination="$target_omp/$relative_path"
+  if [ -e "$destination" ] && ! cmp -s -- "$source_omp/$relative_path" "$destination"; then
+    conflicts+=("$relative_path")
+  fi
+done
+
+if [ "${#conflicts[@]}" -gt 0 ] && [ "$force" -eq 0 ]; then
+  printf 'install: refusing to overwrite differing files in %s:\n' "$target_omp" >&2
+  printf '  %s\n' "${conflicts[@]}" >&2
+  printf 'install: rerun with --force to replace them\n' >&2
+  exit 1
+fi
+
+installed=0
+for relative_path in ${relative_paths[@]+"${relative_paths[@]}"}; do
+  destination="$target_omp/$relative_path"
+  if [ -f "$destination" ] && cmp -s -- "$source_omp/$relative_path" "$destination"; then
+    continue
+  fi
+  mkdir -p -- "$(dirname -- "$destination")"
+  cp -- "$source_omp/$relative_path" "$destination"
+  installed=$((installed + 1))
+done
+
+printf 'install: %d file(s) installed into %s\n' "$installed" "$target_omp"

package/issues/control.ts

@@ -0,0 +1,91 @@
+import { mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isInteger, isRecord } from "./guards";
+
+/**
+ * The dashboard-to-worker channel. Commands are individual files created by
+ * atomic rename, so the worker never reads a half-written command, and their
+ * names sort in submission order. A worker consumes them from any dashboard
+ * attached to the same repository state.
+ */
+
+export type IssuesCommand =
+  | { type: "pause" }
+  | { type: "resume" }
+  | { type: "stop" }
+  | { type: "check" }
+  | { type: "answer"; id: number | string; value: string; runId?: string };
+
+let sequence = 0;
+
+export function writeCommand(directory: string, command: IssuesCommand): string {
+  mkdirSync(directory, { recursive: true });
+  sequence += 1;
+  const name = `${String(Date.now()).padStart(14, "0")}-${String(sequence).padStart(6, "0")}.json`;
+  const path = join(directory, name);
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(command)}\n`);
+  renameSync(temporary, path);
+  return path;
+}
+
+function parseCommand(text: string): IssuesCommand | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(parsed)) return undefined;
+  switch (parsed.type) {
+    case "pause":
+    case "resume":
+    case "stop":
+    case "check":
+      return { type: parsed.type };
+    case "answer":
+      if (
+        (typeof parsed.id === "string" || isInteger(parsed.id)) &&
+        typeof parsed.value === "string" &&
+        (parsed.runId === undefined || typeof parsed.runId === "string")
+      ) {
+        return {
+          type: "answer",
+          id: parsed.id,
+          value: parsed.value,
+          ...(parsed.runId === undefined ? {} : { runId: parsed.runId }),
+        };
+      }
+      return undefined;
+    default:
+      return undefined;
+  }
+}
+
+/** Reads and consumes every pending command in name order. */
+export function takeCommands(directory: string): IssuesCommand[] {
+  let names: string[];
+  try {
+    names = readdirSync(directory).filter((name) => name.endsWith(".json")).sort();
+  } catch {
+    return [];
+  }
+  const commands: IssuesCommand[] = [];
+  for (const name of names) {
+    const path = join(directory, name);
+    let text: string;
+    try {
+      text = readFileSync(path, "utf8");
+    } catch {
+      continue;
+    }
+    try {
+      unlinkSync(path);
+    } catch {
+      // Another consumer already took it.
+    }
+    const command = parseCommand(text);
+    if (command !== undefined) commands.push(command);
+  }
+  return commands;
+}

package/issues/guards.ts

@@ -0,0 +1,12 @@
+/** One shared object guard for every issues boundary parser. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function nullableString(value: unknown): value is string | null {
+  return value === null || typeof value === "string";
+}
+
+export function isInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value);
+}

package/issues/ledger.ts

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { isInteger, isRecord } from "./guards";
+import { LEDGER_VERSION, ledgerPath } from "./paths";
+
+/**
+ * The ledger records which issue numbers a successful ACP prompt already
+ * handled, keyed by the repository's state directory. It controls triggers
+ * only; the prompt itself is never scoped. A closed issue that reopens is new
+ * again because pruning drops entries that are no longer open.
+ */
+
+export interface HandledIssue {
+  number: number;
+  /** The run that handled it, or `legacy` for a migrated entry. */
+  runId: string;
+  at: string;
+}
+
+export interface Ledger {
+  version: 1;
+  handled: Record<string, HandledIssue>;
+}
+
+export function emptyLedger(): Ledger {
+  return { version: LEDGER_VERSION, handled: {} };
+}
+
+function isEntry(value: unknown): value is HandledIssue {
+  return (
+    isRecord(value) &&
+    isInteger(value.number) &&
+    typeof value.runId === "string" &&
+    typeof value.at === "string"
+  );
+}
+
+export function parseLedger(text: string): Ledger | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(parsed) || parsed.version !== LEDGER_VERSION) return undefined;
+  if (!isRecord(parsed.handled)) return undefined;
+  const handled: Record<string, HandledIssue> = {};
+  for (const [key, value] of Object.entries(parsed.handled)) {
+    if (!isEntry(value)) return undefined;
+    handled[key] = value;
+  }
+  return { version: LEDGER_VERSION, handled };
+}
+
+/** A missing or unusable ledger reads as empty. */
+export function readLedger(stateDir: string, repoDir: string): Ledger {
+  try {
+    return parseLedger(readFileSync(ledgerPath(stateDir, repoDir), "utf8")) ?? emptyLedger();
+  } catch {
+    return emptyLedger();
+  }
+}
+
+/** A damaged ledger is renamed aside, preserved, and read as empty. */
+export function loadLedger(stateDir: string, repoDir: string): Ledger {
+  const path = ledgerPath(stateDir, repoDir);
+  if (!existsSync(path)) return emptyLedger();
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return emptyLedger();
+  }
+  const ledger = parseLedger(text);
+  if (ledger !== undefined) return ledger;
+  try {
+    renameSync(path, `${path}.invalid-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+  } catch {
+    // The next successful run writes a fresh ledger anyway.
+  }
+  return emptyLedger();
+}
+
+export function writeLedger(stateDir: string, repoDir: string, ledger: Ledger): void {
+  const path = ledgerPath(stateDir, repoDir);
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(ledger, null, 2)}\n`);
+  renameSync(temporary, path);
+}
+
+export function handledNumbers(ledger: Ledger): Set<number> {
+  return new Set(Object.values(ledger.handled).map((entry) => entry.number));
+}
+
+export function recordHandled(
+  ledger: Ledger,
+  issues: Array<{ number: number }>,
+  runId: string,
+  now: Date,
+): Ledger {
+  const handled = { ...ledger.handled };
+  const at = now.toISOString();
+  for (const issue of issues) {
+    handled[String(issue.number)] = { number: issue.number, runId, at };
+  }
+  return { version: LEDGER_VERSION, handled };
+}
+
+/** Drops entries whose issue is no longer open. */
+export function pruneLedger(ledger: Ledger, open: Set<number>): Ledger {
+  const handled: Record<string, HandledIssue> = {};
+  let changed = false;
+  for (const [key, entry] of Object.entries(ledger.handled)) {
+    if (open.has(entry.number)) {
+      handled[key] = entry;
+      continue;
+    }
+    changed = true;
+  }
+  return changed ? { version: LEDGER_VERSION, handled } : ledger;
+}

package/issues/legacy.ts

@@ -0,0 +1,68 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { isRecord } from "./guards";
+import { parseLedger, type HandledIssue } from "./ledger";
+import { pidAlive, readLock, type LockOwner } from "./lock";
+import { legacyLedgerPath, legacyLockPath, legacyStatePath, ledgerPath } from "./paths";
+
+/**
+ * The removed systemd orchestrator left three facts worth reading exactly
+ * once: its handled issue numbers, its state's root, and a live lock. Nothing
+ * here starts, stops, or edits that process; the operator owns its cleanup.
+ */
+
+export function legacyLiveLock(stateDir: string): LockOwner | undefined {
+  const path = legacyLockPath(stateDir);
+  const owner = readLock(path);
+  if (owner === undefined || !pidAlive(owner.pid)) return undefined;
+  return owner;
+}
+
+export function legacyLockRefusal(owner: LockOwner, stateDir: string): string {
+  return (
+    `the legacy devboard-orchestrator still holds ${legacyLockPath(stateDir)} (pid ${owner.pid}). ` +
+    "Stop it with 'systemctl --user stop devboard-orchestrator.service', disable it with " +
+    "'systemctl --user disable devboard-orchestrator.service', remove " +
+    "'$HOME/.config/systemd/user/devboard-orchestrator.service', then run " +
+    "'systemctl --user daemon-reload'."
+  );
+}
+
+function legacyRootMatches(stateDir: string, repoDir: string): boolean {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(legacyStatePath(stateDir), "utf8"));
+    if (!isRecord(parsed) || typeof parsed.root !== "string") return false;
+    return resolve(parsed.root) === resolve(repoDir);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Copies the legacy handled numbers into the repository-keyed ledger, but only
+ * when that ledger does not exist yet, the legacy state parses, and its root
+ * names this checkout. Missing, damaged, or mismatched legacy files are
+ * ignored; the legacy bytes are never rewritten.
+ */
+export function migrateLegacyLedger(options: {
+  stateDir: string;
+  repoDir: string;
+  now?: Date;
+}): HandledIssue[] | undefined {
+  if (existsSync(ledgerPath(options.stateDir, options.repoDir))) return undefined;
+  if (!legacyRootMatches(options.stateDir, options.repoDir)) return undefined;
+  let text: string;
+  try {
+    text = readFileSync(legacyLedgerPath(options.stateDir), "utf8");
+  } catch {
+    return undefined;
+  }
+  const ledger = parseLedger(text);
+  if (ledger === undefined) return undefined;
+  const at = (options.now ?? new Date()).toISOString();
+  return Object.values(ledger.handled).map((entry) => ({
+    number: entry.number,
+    runId: entry.runId,
+    at: entry.at.length > 0 ? entry.at : at,
+  }));
+}