@dsdenes/devboard 0.1.560 → 0.1.563

package/watchdog/main.ts

@@ -0,0 +1,106 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { runCycle } from "./coordinator";
+import { acquireLock } from "./lock";
+
+/**
+ * `bun run watchdog -- --once` runs one cycle; `--collect --dry-run` prints the
+ * cycle's report and changes nothing. The systemd oneshot service runs the
+ * former. Both respect the machine-wide lock.
+ */
+
+const usage = `Usage: bun run watchdog [options]
+
+Runs one watchdog cycle over the last ten minutes of dashboard evidence and
+files one GitHub issue per distinct signal.
+
+  --once             Discover, collect, and file. The default.
+  --collect          Collect and print the report; requires --dry-run.
+  --dry-run          Print the report without filing, writing, or changing anything.
+  --root <path>      Explicit canonical repository root.
+  -h, --help         Show this text.
+`;
+
+const args = process.argv.slice(2);
+let once = false;
+let collect = false;
+let dryRun = false;
+let rootOption: string | undefined;
+
+for (let index = 0; index < args.length; index += 1) {
+  const argument = args[index];
+  if (argument === "--once") once = true;
+  else if (argument === "--collect") collect = true;
+  else if (argument === "--dry-run") dryRun = true;
+  else if (argument === "--root") {
+    rootOption = args[index + 1];
+    index += 1;
+    if (rootOption === undefined) {
+      console.error("watchdog: --root needs a path");
+      process.exit(2);
+    }
+  } else if (argument === "-h" || argument === "--help") {
+    console.log(usage);
+    process.exit(0);
+  } else {
+    console.error(`watchdog: unknown option ${argument}`);
+    console.error(usage);
+    process.exit(2);
+  }
+}
+
+if (collect && !dryRun) {
+  console.error("watchdog: --collect runs with --dry-run");
+  process.exit(2);
+}
+
+if (once && (collect || dryRun)) {
+  console.error("watchdog: --once and --dry-run are exclusive");
+  process.exit(2);
+}
+
+function gitTopLevel(): string {
+  const result = Bun.spawnSync({
+    cmd: ["git", "-C", dirname(import.meta.dir), "rev-parse", "--show-toplevel"],
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const top = result.stdout.toString().trim();
+  if (result.exitCode !== 0 || top.length === 0) {
+    console.error("watchdog: the harness is not inside a git checkout");
+    process.exit(2);
+  }
+  return top;
+}
+
+const root = resolve(rootOption ?? gitTopLevel());
+if (!existsSync(join(root, ".devboard"))) {
+  console.error(`watchdog: missing prerequisite: ${join(root, ".devboard")} does not exist`);
+  process.exit(2);
+}
+
+const lock = acquireLock(join(root, ".devboard", ".tmp", "watchdog", "lock"));
+if (!lock.acquired) {
+  console.log(
+    `watchdog: already running${lock.owner === undefined ? "" : ` (pid ${lock.owner})`}`,
+  );
+  process.exit(0);
+}
+
+let exitCode = 0;
+try {
+  const result = await runCycle({ root, dryRun: dryRun || collect });
+  if (dryRun || collect) {
+    console.log(JSON.stringify(result.report, null, 2));
+  }
+  exitCode = result.exitCode;
+} catch (error) {
+  const detail = error instanceof Error ? error.stack ?? error.message : String(error);
+  console.error(`watchdog: ${detail}`);
+  exitCode = 1;
+} finally {
+  lock.release();
+}
+
+process.exit(exitCode);

package/watchdog/status.ts

@@ -0,0 +1,71 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { latestWatchdogCycle, readWatchdogCycles, type WatchdogCycle } from "./history";
+import { loadLedger } from "./ledger";
+
+/**
+ * The read-only watchdog view the dashboard serves. It is derived from the
+ * newest cycle report, the retained run directories, and the ledger, and it
+ * never carries an environment value: only the action, the counts, and the
+ * issue URLs.
+ */
+
+export interface WatchdogIssue {
+  url: string;
+  category: string;
+  line: string;
+  filedAt: string;
+}
+
+export interface WatchdogStatus {
+  /** The newest cycle's start, UTC ISO 8601, or null before the first cycle. */
+  cycle: string | null;
+  action: string;
+  reason?: string;
+  /** Findings in the newest cycle. */
+  findings: number;
+  /** Every issue the watchdog filed, newest first. */
+  issues: WatchdogIssue[];
+  /** Fingerprints still waiting for a successful filing. */
+  pending: number;
+  /** The retained cycles, newest first; empty before the first cycle. */
+  cycles: WatchdogCycle[];
+}
+
+export function readWatchdogStatus(watchdogDir: string): WatchdogStatus {
+  let latest: Record<string, unknown> = {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(join(watchdogDir, "latest.json"), "utf8"));
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+      latest = parsed as Record<string, unknown>;
+    }
+  } catch {
+    // No cycle has run yet.
+  }
+  const ledger = loadLedger(watchdogDir);
+  const issues = Object.values(ledger.findings)
+    .filter(
+      (entry): entry is typeof entry & { url: string } =>
+        entry.disposition.startsWith("filed:") && typeof entry.url === "string",
+    )
+    .map((entry) => ({
+      url: entry.url,
+      category: entry.category,
+      line: entry.line,
+      filedAt: entry.filedAt ?? entry.firstSeen,
+    }))
+    .sort((left, right) => right.filedAt.localeCompare(left.filedAt) || left.url.localeCompare(right.url));
+  return {
+    cycle: typeof latest.cycle === "string" ? latest.cycle : null,
+    action: typeof latest.action === "string" ? latest.action : "none",
+    ...(typeof latest.reason === "string" ? { reason: latest.reason } : {}),
+    findings: Array.isArray(latest.findings) ? latest.findings.length : 0,
+    issues,
+    pending: ledger.pendingFiling.length,
+    cycles: readWatchdogCycles(
+      watchdogDir,
+      latestWatchdogCycle(latest, (fingerprint) => ledger.findings[fingerprint]?.url),
+      (fingerprint) => ledger.findings[fingerprint]?.url,
+    ),
+  };
+}

package/watchdog/systemd.ts

@@ -0,0 +1,96 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * The systemd user adapter. It is the only part of the watchdog that writes
+ * outside the repository: two unit files and the timer's enable symlink.
+ */
+
+export const TIMER_NAME = "devboard-watchdog.timer";
+export const SERVICE_NAME = "devboard-watchdog.service";
+
+export interface UnitPaths {
+  directory: string;
+  service: string;
+  timer: string;
+  enableLink: string;
+}
+
+export function unitPaths(): UnitPaths {
+  const directory = join(homedir(), ".config", "systemd", "user");
+  return {
+    directory,
+    service: join(directory, SERVICE_NAME),
+    timer: join(directory, TIMER_NAME),
+    enableLink: join(directory, "timers.target.wants", TIMER_NAME),
+  };
+}
+
+export interface CommandResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+export function systemctl(...arguments_: string[]): CommandResult {
+  const result = Bun.spawnSync({
+    cmd: ["systemctl", "--user", ...arguments_],
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return {
+    code: result.exitCode ?? 1,
+    stdout: result.stdout.toString().trim(),
+    stderr: result.stderr.toString().trim(),
+  };
+}
+
+export function runCommand(argv: string[]): CommandResult {
+  const result = Bun.spawnSync({
+    cmd: argv,
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return {
+    code: result.exitCode ?? 1,
+    stdout: result.stdout.toString().trim(),
+    stderr: result.stderr.toString().trim(),
+  };
+}
+
+/** Refuses a non-`yes` Linger before anything is installed. */
+export function requireLinger(): string {
+  const result = runCommand(["loginctl", "show-user", userInfo().username, "-p", "Linger"]);
+  if (result.code === 0 && /Linger=yes/.test(result.stdout)) return "Linger=yes";
+  throw new Error(
+    "missing prerequisite: systemd user lingering is off. " +
+      `Run 'loginctl enable-linger ${userInfo().username}' and rerun the installer.`,
+  );
+}
+
+export function renderUnit(source: string, values: Record<string, string>): string {
+  let text = readFileSync(source, "utf8");
+  for (const [key, value] of Object.entries(values)) {
+    text = text.split(`@${key}@`).join(value);
+  }
+  return text;
+}
+
+export function writeUnit(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+}
+
+export function uniqueDirectories(paths: Array<string | undefined>): string {
+  const directories = new Set<string>();
+  for (const path of paths) {
+    if (path === undefined || path.length === 0) continue;
+    const directory = dirname(path);
+    if (directory.length > 0) directories.add(directory);
+  }
+  for (const fallback of ["/usr/local/bin", "/usr/bin", "/bin"]) directories.add(fallback);
+  return [...directories].join(":");
+}

package/watchdog/uninstall.ts

@@ -0,0 +1,30 @@
+import { existsSync, unlinkSync } from "node:fs";
+import { systemctl, unitPaths } from "./systemd";
+
+/**
+ * Stops and removes the user timer. It touches no repository file, so an
+ * uninstall leaves the harness exactly as it was.
+ */
+
+const paths = unitPaths();
+systemctl("stop", "devboard-watchdog.timer");
+systemctl("stop", "devboard-watchdog.service");
+systemctl("disable", "devboard-watchdog.timer");
+for (const path of [paths.service, paths.timer, paths.enableLink]) {
+  if (!existsSync(path)) continue;
+  try {
+    unlinkSync(path);
+  } catch (error) {
+    console.error(
+      `watchdog:uninstall: could not remove ${path}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}
+const reload = systemctl("daemon-reload");
+if (reload.code !== 0) {
+  console.error(`watchdog:uninstall: daemon-reload failed: ${reload.stderr || reload.stdout}`);
+  process.exit(1);
+}
+console.log("watchdog:uninstall: timer stopped, disabled, and removed");

package/watchdog/units/devboard-watchdog.service

@@ -0,0 +1,9 @@
+[Unit]
+Description=Devboard watchdog: heal harness failures from the last ten minutes
+
+[Service]
+Type=oneshot
+WorkingDirectory=@HARNESS@
+ExecStart=@BUN@ run watchdog -- --once --root @ROOT@
+Environment=PATH=@PATH@
+TimeoutStartSec=3600

package/watchdog/units/devboard-watchdog.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Run the Devboard watchdog every ten minutes
+
+[Timer]
+OnCalendar=*:0/10
+Persistent=true
+Unit=devboard-watchdog.service
+
+[Install]
+WantedBy=timers.target