@dsdenes/devboard 0.1.559 → 0.1.562

package/server/state.ts

@@ -0,0 +1,249 @@
+import { readFileSync, readlinkSync, unlinkSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { journalKey } from "./journal";
+
+/**
+ * Durable dashboard state for one host repository. The server writes the whole
+ * state before it broadcasts any event, and a replacement process restores it,
+ * so a graceful stop, a launcher restart, or a SIGKILL loses no state a client
+ * has already seen. One file per repository keyed like the journal keeps two
+ * repositories that share a harness from reading each other's state.
+ */
+
+/** Envelope version. A file with another version is preserved, never read. */
+export const STATE_VERSION = 1;
+
+/** Restored activity is bounded to the first of these limits. */
+export const ACTIVITY_MAX_ENTRIES = 1000;
+export const ACTIVITY_MAX_BYTES = 1024 * 1024;
+
+/** Replaces trimmed lines so the reader knows the log is older than it looks. */
+export const ACTIVITY_TRIMMED_MARKER = "Earlier activity was trimmed.";
+
+/** Total serialized state one repository may keep with every activity bound full. */
+export const STATE_MAX_BYTES = 32 * 1024 * 1024;
+
+/** The 24-hex repository key that names this repository's state file. */
+export const stateKey = journalKey;
+
+export function stateFile(stateDir: string, repoDir: string): string {
+  return join(stateDir, "state", `${stateKey(repoDir)}.json`);
+}
+
+export type StateLoad =
+  | { kind: "missing" }
+  /** The file parsed and named this version; `value` is the envelope's state. */
+  | { kind: "loaded"; value: unknown }
+  /** Unusable bytes; they were preserved aside when the rename succeeded. */
+  | { kind: "damaged"; reason: string; preserved: string | undefined };
+
+/** Moves unusable bytes aside so they are never overwritten or deleted. */
+function preserve(path: string): string | undefined {
+  const aside = `${path}.damaged-${Date.now()}`;
+  try {
+    renameSync(path, aside);
+    return aside;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Moves a state file whose contents cannot be used out of the way, unread. */
+export function preserveStateFile(path: string): string | undefined {
+  return preserve(path);
+}
+
+export function readStateFile(path: string): StateLoad {
+  let source: string;
+  try {
+    source = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { kind: "missing" };
+    return {
+      kind: "damaged",
+      reason: `could not read ${path}: ${error instanceof Error ? error.message : String(error)}`,
+      preserved: preserve(path),
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(source);
+  } catch (error) {
+    return {
+      kind: "damaged",
+      reason: `the state file is not valid JSON: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+      preserved: preserve(path),
+    };
+  }
+
+  if (typeof parsed !== "object" || parsed === null || !("version" in parsed)) {
+    return {
+      kind: "damaged",
+      reason: "the state file is not a state envelope",
+      preserved: preserve(path),
+    };
+  }
+
+  const version = parsed.version;
+  if (version !== STATE_VERSION) {
+    return {
+      kind: "damaged",
+      reason:
+        typeof version === "number"
+          ? `the state file has unsupported version ${version}`
+          : "the state file has no version",
+      preserved: preserve(path),
+    };
+  }
+
+  if (!("state" in parsed)) {
+    return {
+      kind: "damaged",
+      reason: "the state envelope holds no state",
+      preserved: preserve(path),
+    };
+  }
+  const value = parsed.state;
+  if (typeof value !== "object" || value === null) {
+    return {
+      kind: "damaged",
+      reason: "the state envelope holds no state",
+      preserved: preserve(path),
+    };
+  }
+
+  return { kind: "loaded", value };
+}
+
+/**
+ * Replaces the state file atomically: the last complete state stays readable at
+ * every instant, and a crash during the write leaves the previous state.
+ */
+export function writeStateFile(path: string, text: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  // A per-process name keeps two writers for different repositories apart even
+  // when they share one directory.
+  const temporary = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync(temporary, text);
+    renameSync(temporary, path);
+  } catch (error) {
+    try {
+      unlinkSync(temporary);
+    } catch {
+      // The temporary file was never created or is already gone.
+    }
+    throw error;
+  }
+}
+
+function byteLength(text: string): number {
+  return Buffer.byteLength(text, "utf8");
+}
+
+export function activityWithinBounds(store: string[]): boolean {
+  if (store.length > ACTIVITY_MAX_ENTRIES) return false;
+  let bytes = 0;
+  for (const line of store) {
+    bytes += byteLength(line);
+    if (bytes > ACTIVITY_MAX_BYTES) return false;
+  }
+  return true;
+}
+
+/**
+ * Keeps the newest activity entries inside the bound and prefixes one marker so
+ * the trimmed log never looks complete. The newest entry is always kept, even
+ * when it alone exceeds the byte bound.
+ */
+export function trimActivity(store: string[]): void {
+  if (activityWithinBounds(store)) return;
+
+  const markerBytes = byteLength(ACTIVITY_TRIMMED_MARKER);
+  const kept: string[] = [];
+  let bytes = markerBytes;
+  for (let index = store.length - 1; index >= 0; index -= 1) {
+    const line = store[index];
+    if (line === undefined) continue;
+    const size = byteLength(line);
+    const entries = kept.length + 2;
+    if (kept.length > 0 && (entries > ACTIVITY_MAX_ENTRIES || bytes + size > ACTIVITY_MAX_BYTES)) {
+      break;
+    }
+    kept.unshift(line);
+    bytes += size;
+  }
+
+  store.splice(0, store.length, ACTIVITY_TRIMMED_MARKER, ...kept);
+}
+
+/** Records one activity line, or one streamed delta, inside the activity bound. */
+export function appendActivity(store: string[], text: string, append: boolean): void {
+  if (append && store.length > 0) {
+    store[store.length - 1] += text;
+  } else {
+    store.push(text);
+  }
+  trimActivity(store);
+}
+
+/** One ACP child recorded in the state so a replacement can prove and end it. */
+export interface RecordedChild {
+  pid: number;
+  argv: string[];
+  cwd: string;
+}
+
+/** True only when the pid still runs exactly the recorded command in the recorded cwd. */
+export function recordedChildAlive(child: RecordedChild): boolean {
+  try {
+    process.kill(child.pid, 0);
+  } catch {
+    return false;
+  }
+  let cmdline: string;
+  try {
+    cmdline = readFileSync(`/proc/${child.pid}/cmdline`, "utf8");
+  } catch {
+    // Without proof from the process table the child is left alone.
+    return false;
+  }
+  const argv = cmdline.split("\u0000").filter((entry) => entry.length > 0);
+  if (argv.length !== child.argv.length) return false;
+  for (const [index, entry] of child.argv.entries()) {
+    if (argv[index] !== entry) return false;
+  }
+  try {
+    return readlinkSync(`/proc/${child.pid}/cwd`) === child.cwd;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ends every recorded child whose process table entry proves it is the peer the
+ * killed process left behind, and waits until it is gone. A pid that cannot be
+ * proven is never signalled.
+ */
+export async function terminateRecordedChildren(
+  children: RecordedChild[],
+  timeoutMs = 5000,
+): Promise<RecordedChild[]> {
+  const proven = children.filter((child) => recordedChildAlive(child));
+  for (const child of proven) {
+    try {
+      process.kill(child.pid, "SIGKILL");
+    } catch {
+      // It exited between the check and the signal.
+    }
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline && proven.some((child) => recordedChildAlive(child))) {
+    await Bun.sleep(20);
+  }
+  return proven;
+}

package/server/tracker.ts

@@ -0,0 +1,369 @@
+import type { Subprocess } from "bun";
+import {
+  authEnvironment,
+  isAuthFailure,
+  resolveForgeAuth,
+  type Exec,
+  type Forge,
+  type ResolvedAuth,
+} from "../lib/forge-auth.ts";
+import { configuredGiteaToken, giteaBaseUrl, parseForgeRemote } from "../lib/forge";
+import { giteaListIssues } from "../lib/gitea";
+
+export interface OpenEpic {
+  number: number;
+  title: string;
+  url: string;
+}
+
+/**
+ * Reads every open epic on the origin tracker. A lookup may return one epic or
+ * `undefined` for the single-epic callers tests use; the lifecycle normalizes
+ * both shapes with `normalizeEpics`.
+ */
+export type EpicLookup = (
+  repoDir: string,
+) => Promise<OpenEpic[] | OpenEpic | undefined>;
+
+/** Normalizes a tracker answer to the list shape the lifecycle consumes. */
+export function normalizeEpics(value: OpenEpic[] | OpenEpic | undefined): OpenEpic[] {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+interface Remote {
+  forge: Forge;
+  host: string;
+  project: string;
+  baseUrl?: string;
+}
+
+interface CommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+interface LabelEntry {
+  name?: unknown;
+}
+
+interface IssueEntry {
+  number?: unknown;
+  iid?: unknown;
+  title?: unknown;
+  url?: unknown;
+  web_url?: unknown;
+}
+
+function baseEnvironment(): Record<string, string> {
+  const environment: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (typeof value === "string") environment[key] = value;
+  }
+  return {
+    ...environment,
+    GH_PROMPT_DISABLED: "1",
+    GH_NO_UPDATE_NOTIFIER: "1",
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_ASKPASS: "true",
+    NO_COLOR: "1",
+  };
+}
+
+const bunExec: Exec = async (commandName, args, options) => {
+  try {
+    const process = Bun.spawn({
+      cmd: [commandName, ...args],
+      cwd: options.cwd,
+      env: options.env,
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(process.stdout).text(),
+      new Response(process.stderr).text(),
+      process.exited,
+    ]);
+    return { stdout, stderr, code };
+  } catch (error) {
+    return {
+      stdout: "",
+      stderr: error instanceof Error ? error.message : String(error),
+      code: -1,
+      killed: false,
+    };
+  }
+};
+
+async function command(
+  cwd: string,
+  argv: string[],
+  env: Record<string, string> = baseEnvironment(),
+): Promise<CommandResult> {
+  let process: Subprocess<"ignore", "pipe", "pipe">;
+  try {
+    process = Bun.spawn(argv, {
+      cwd,
+      env,
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+  } catch (error) {
+    throw new Error(
+      `Could not run ${argv[0]}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(process.stdout).text(),
+    new Response(process.stderr).text(),
+    process.exited,
+  ]);
+  return { stdout, stderr, exitCode };
+}
+
+async function commandJson<T>(
+  cwd: string,
+  argv: string[],
+  description: string,
+  env?: Record<string, string>,
+): Promise<T> {
+  const result = await command(cwd, argv, env);
+  if (result.exitCode !== 0) {
+    const detail = result.stderr.trim() || result.stdout.trim() || `exit code ${result.exitCode}`;
+    throw new Error(`Could not ${description}: ${detail}`);
+  }
+
+  const source = result.stdout.trim();
+  if (source.length === 0) return [] as T;
+  try {
+    return JSON.parse(source) as T;
+  } catch {
+    throw new Error(`Could not ${description}: unexpected CLI output.`);
+  }
+}
+
+/**
+ * Reads the origin remote from the repository and classifies it. The forge is
+ * decided by the hostname, and the project path keeps any GitLab subgroup.
+ */
+export function classifyRemote(remote: string): Remote | undefined {
+  const parsed = parseForgeRemote(remote);
+  if (parsed === undefined) return undefined;
+  return {
+    forge: parsed.forge,
+    host: parsed.host,
+    project: parsed.project,
+    ...(parsed.forge === "gitea"
+      ? { baseUrl: giteaBaseUrl(parsed) }
+      : {}),
+  };
+}
+
+function toEpic(entry: IssueEntry): OpenEpic | undefined {
+  const number =
+    typeof entry.number === "number"
+      ? entry.number
+      : typeof entry.iid === "number"
+        ? entry.iid
+        : undefined;
+  const title = typeof entry.title === "string" ? entry.title : undefined;
+  const url =
+    typeof entry.url === "string"
+      ? entry.url
+      : typeof entry.web_url === "string"
+        ? entry.web_url
+        : undefined;
+  if (number === undefined || title === undefined) return undefined;
+  return { number, title, url: url ?? "" };
+}
+
+function allEpics(entries: unknown): OpenEpic[] {
+  if (!Array.isArray(entries)) return [];
+  const epics: OpenEpic[] = [];
+  for (const entry of entries) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const epic = toEpic(entry as IssueEntry);
+    if (epic !== undefined) epics.push(epic);
+  }
+  return epics;
+}
+
+async function githubEpics(
+  cwd: string,
+  project: string,
+  env: Record<string, string>,
+): Promise<OpenEpic[]> {
+  const labels = await commandJson<LabelEntry[]>(
+    cwd,
+    ["gh", "label", "list", "--search", "epic", "--limit", "100", "--json", "name"],
+    "list tracker labels",
+    env,
+  );
+  const label = labels.find(
+    (entry) => typeof entry.name === "string" && entry.name.toLowerCase() === "epic",
+  );
+
+  if (label !== undefined && typeof label.name === "string") {
+    const issues = await commandJson<unknown>(
+      cwd,
+      [
+        "gh",
+        "issue",
+        "list",
+        "--label",
+        label.name,
+        "--state",
+        "open",
+        "--json",
+        "number,title,url",
+        "--limit",
+        "100",
+      ],
+      "list open epics",
+      env,
+    );
+    return allEpics(issues);
+  }
+
+  const issues = await commandJson<unknown>(
+    cwd,
+    [
+      "gh",
+      "search",
+      "issues",
+      "--repo",
+      project,
+      "--match",
+      "body",
+      "--state",
+      "open",
+      "devboard-epic",
+      "--json",
+      "number,title,url",
+      "--limit",
+      "100",
+    ],
+    "search open epics",
+    env,
+  );
+  return allEpics(issues);
+}
+
+async function gitlabEpics(cwd: string, env: Record<string, string>): Promise<OpenEpic[]> {
+  const labels = await commandJson<LabelEntry[]>(
+    cwd,
+    ["glab", "label", "list", "--output", "json"],
+    "list tracker labels",
+    env,
+  );
+  const label = labels.find(
+    (entry) => typeof entry.name === "string" && entry.name.toLowerCase() === "epic",
+  );
+
+  if (label !== undefined && typeof label.name === "string") {
+    const issues = await commandJson<unknown>(
+      cwd,
+      ["glab", "issue", "list", "--label", label.name, "--output", "json"],
+      "list open epics",
+      env,
+    );
+    return allEpics(issues);
+  }
+
+  const issues = await commandJson<unknown>(
+    cwd,
+    ["glab", "issue", "list", "--search", "devboard-epic", "--in", "description", "--output", "json"],
+    "search open epics",
+    env,
+  );
+  return allEpics(issues);
+}
+
+async function giteaEpics(remote: Remote): Promise<OpenEpic[]> {
+  if (remote.baseUrl === undefined || remote.baseUrl.length === 0) {
+    throw new Error("The Gitea address is not configured; set DEVBOARD_GITEA_URL.");
+  }
+  const token = configuredGiteaToken(process.env);
+  const issues = await giteaListIssues(
+    {
+      baseUrl: remote.baseUrl,
+      project: remote.project,
+      ...(token === undefined ? {} : { token }),
+    },
+    "open",
+  );
+  return issues
+    .filter(
+      (issue) =>
+        issue.labels.some((label) => label.toLowerCase() === "epic") ||
+        issue.body.includes("devboard-epic"),
+    )
+    .map((issue) => ({ number: issue.number, title: issue.title, url: issue.url }));
+}
+
+const AUTH_CACHE_MS = 60_000;
+const authCache = new Map<string, { auth: ResolvedAuth; expires: number }>();
+
+/**
+ * The lifecycle re-reads the tracker on every lane transition and settle
+ * attempt. Re-probing every account on each read would add seconds and several
+ * API calls, so a successful selection is reused for a short window.
+ */
+async function resolveTrackerAuth(
+  host: string,
+  project: string,
+  forge: Forge,
+  repoDir: string,
+): Promise<ResolvedAuth> {
+  const key = `${forge}:${host}:${project}`;
+  const cached = authCache.get(key);
+  if (cached !== undefined && cached.expires > Date.now()) return cached.auth;
+
+  const auth = await resolveForgeAuth(bunExec, {
+    forge,
+    host,
+    project,
+    cwd: repoDir,
+    required: "read",
+    env: process.env,
+  });
+  if (isAuthFailure(auth)) throw new Error(auth.error);
+  authCache.set(key, { auth, expires: Date.now() + AUTH_CACHE_MS });
+  return auth;
+}
+
+/**
+ * Finds every open epic on the origin tracker. An issue is an epic when it is
+ * open and either carries the label `epic` ignoring case or contains the
+ * `devboard-epic` marker in its body. Only read-only CLI queries run.
+ */
+export async function findOpenEpics(repoDir: string): Promise<OpenEpic[]> {
+  const remote = await command(repoDir, ["git", "remote", "get-url", "origin"]);
+  if (remote.exitCode !== 0) {
+    const detail = remote.stderr.trim() || `exit code ${remote.exitCode}`;
+    throw new Error(`Could not read the origin remote: ${detail}`);
+  }
+
+  const classified = classifyRemote(remote.stdout);
+  if (classified === undefined) {
+    throw new Error("The origin remote does not name a supported repository.");
+  }
+
+  if (classified.forge === "gitea") return await giteaEpics(classified);
+
+  const auth = await resolveTrackerAuth(
+    classified.host,
+    classified.project,
+    classified.forge,
+    repoDir,
+  );
+  const env = authEnvironment(auth);
+
+  return classified.forge === "github"
+    ? await githubEpics(repoDir, classified.project, env)
+    : await gitlabEpics(repoDir, env);
+}