@dsdenes/devboard 0.1.560 → 0.1.562

package/issues/scout/preflight.ts

@@ -0,0 +1,277 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { homedir } from "node:os";
+import {
+  findOnPath,
+  originForge,
+  rootProblem,
+} from "../repository";
+import { configuredGiteaToken, giteaBaseUrl } from "../../lib/forge";
+import { giteaRepository, type FetchLike } from "../../lib/gitea";
+
+/**
+ * Everything Start must prove before it spawns a scout: the checkout is the
+ * canonical root of a GitHub origin, the state directory is inside it, the
+ * agent tools exist, the scan command is installed, and the credential can
+ * push. A refusal names the missing fact and spawns no peer and no scan.
+ */
+
+export type ScoutPreflightResult = { ok: true; repository: string } | { ok: false; message: string };
+
+export interface ScoutPreflightOptions {
+  repoDir: string;
+  stateDir: string;
+  environment?: Record<string, string | undefined>;
+  /** Injected for tests; defaults to the operator's `gh`. */
+  run?: (argv: string[]) => Promise<{ code: number; stdout: string; stderr: string }>;
+  /** Injected transport for the Gitea API. */
+  giteaFetch?: FetchLike;
+}
+
+export interface ScoutCommandOutcome {
+  code: number;
+  stdout: string;
+  stderr: string;
+  /** The child was asked to stop at the deadline or on abort. */
+  killed?: boolean;
+}
+
+export interface ScoutCommandOptions {
+  /** Kill the child when this many milliseconds elapse. */
+  timeoutMs?: number;
+  /** Kill the child when this signal aborts. */
+  signal?: AbortSignal;
+  /** Working directory; inherits the worker's when omitted. */
+  cwd?: string;
+}
+
+/** How long a child may ignore SIGTERM before it is sent SIGKILL. */
+const TERMINATE_GRACE_MS = 200;
+
+/**
+ * Runs one child under an optional deadline. A child that ignores SIGTERM is
+ * killed with SIGKILL after a short grace, so a stalled command always
+ * settles and always reports a non-zero exit.
+ */
+export async function runCommand(
+  command: string[],
+  environment?: Record<string, string | undefined>,
+  options: ScoutCommandOptions = {},
+): Promise<ScoutCommandOutcome> {
+  if (options.signal?.aborted === true) {
+    return { code: 1, stdout: "", stderr: "the command was cancelled", killed: true };
+  }
+  let child: Bun.Subprocess<"ignore", "pipe", "pipe">;
+  try {
+    child = Bun.spawn({
+      cmd: command,
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+      env: environment ?? process.env,
+      ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+    });
+  } catch (error) {
+    return { code: 1, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+  }
+
+  let killed = false;
+  let grace: Timer | undefined;
+  const terminate = (): void => {
+    if (killed) return;
+    killed = true;
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      // The child already exited.
+    }
+    grace = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // It exited inside the grace period.
+      }
+    }, TERMINATE_GRACE_MS);
+    grace.unref?.();
+  };
+
+  const timer =
+    options.timeoutMs === undefined
+      ? undefined
+      : setTimeout(terminate, Math.max(1, options.timeoutMs));
+  timer?.unref?.();
+  const onAbort = (): void => terminate();
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ]);
+    const diagnostic = killed
+      ? `${stderr.length === 0 ? "" : `${stderr}\n`}the command did not finish before its deadline`
+      : stderr;
+    // A child killed at the deadline never counts as a successful command,
+    // even when it happened to exit 0 while the signal was being delivered.
+    return { code: killed && code === 0 ? 1 : code, stdout, stderr: diagnostic, killed };
+  } finally {
+    clearTimeout(timer);
+    clearTimeout(grace);
+    options.signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+export async function ghCommand(
+  argv: string[],
+  environment?: Record<string, string | undefined>,
+  options: ScoutCommandOptions = {},
+): Promise<ScoutCommandOutcome> {
+  return await runCommand(
+    ["gh", ...argv],
+    {
+      ...(environment ?? process.env),
+      GH_PROMPT_DISABLED: "1",
+      GH_NO_UPDATE_NOTIFIER: "1",
+      GIT_TERMINAL_PROMPT: "0",
+      NO_COLOR: "1",
+    },
+    options,
+  );
+}
+
+function firstLine(text: string): string | undefined {
+  return text
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => line.length > 0);
+}
+
+/** True when `stateDir` resolves inside `repoDir` (or is the root itself is refused). */
+export function stateInsideRepository(repoDir: string, stateDir: string): boolean {
+  const root = resolve(repoDir);
+  const state = resolve(stateDir);
+  const path = relative(root, state);
+  if (path.length === 0) return false;
+  return !path.startsWith("..") && !isAbsolute(path);
+}
+
+/**
+ * The installed `/scout-recommendations` command, in the checkout first and
+ * then the operator's omp command directories.
+ */
+export function scoutCommandPaths(
+  repoDir: string,
+  environment: Record<string, string | undefined> = process.env,
+): string[] {
+  const home = environment.HOME ?? homedir();
+  return [
+    join(resolve(repoDir), ".omp", "commands", "scout-recommendations.md"),
+    join(home, ".omp", "commands", "scout-recommendations.md"),
+    join(home, ".omp", "agent", "commands", "scout-recommendations.md"),
+  ];
+}
+
+export async function preflightScout(options: ScoutPreflightOptions): Promise<ScoutPreflightResult> {
+  const environment = options.environment ?? process.env;
+  const root = rootProblem(options.repoDir);
+  if (root !== undefined) return { ok: false, message: root };
+
+  const remote = originForge(options.repoDir, environment);
+  if (remote === undefined) {
+    return { ok: false, message: "the checkout's origin does not name a supported repository" };
+  }
+  if (remote.forge === "gitlab") {
+    return {
+      ok: false,
+      message: `the scout supports a GitHub or Gitea origin, not a GitLab one: ${remote.host}`,
+    };
+  }
+  const repository = remote.project;
+
+  if (!stateInsideRepository(options.repoDir, options.stateDir)) {
+    return {
+      ok: false,
+      message:
+        `STATE_DIR ${resolve(options.stateDir)} is not inside REPO_DIR ${resolve(options.repoDir)}; ` +
+        "the scout keeps its state beside the checkout",
+    };
+  }
+
+  if (findOnPath("omp", environment) === undefined) {
+    return { ok: false, message: "missing prerequisite: omp is not on PATH" };
+  }
+  if (remote.forge === "github" && findOnPath("gh", environment) === undefined) {
+    return { ok: false, message: "missing prerequisite: gh is not on PATH" };
+  }
+
+  const commandPaths = scoutCommandPaths(options.repoDir, environment);
+  if (!commandPaths.some((path) => existsSync(path))) {
+    return {
+      ok: false,
+      message:
+        "missing prerequisite: the /scout-recommendations command is not installed for omp " +
+        `(looked in ${commandPaths.join(", ")})`,
+    };
+  }
+
+  if (remote.forge === "gitea") {
+    const baseUrl = giteaBaseUrl(remote, environment);
+    if (baseUrl === undefined) {
+      return {
+        ok: false,
+        message:
+          "missing prerequisite: the Gitea address is not configured " +
+          "(set DEVBOARD_GITEA_URL or use an HTTP(S) origin)",
+      };
+    }
+    const token = configuredGiteaToken(environment);
+    if (token === undefined) {
+      return { ok: false, message: "missing prerequisite: GITEA_TOKEN is not set" };
+    }
+    try {
+      const document = await giteaRepository(
+        { baseUrl, project: repository, token },
+        options.giteaFetch,
+      );
+      const permissions =
+        typeof document.permissions === "object" && document.permissions !== null
+          ? document.permissions
+          : {};
+      const writable =
+        ("push" in permissions && permissions.push === true) ||
+        ("admin" in permissions && permissions.admin === true);
+      if (!writable) {
+        return {
+          ok: false,
+          message:
+            `missing prerequisite: the Gitea token cannot write to ${repository} on ${baseUrl}`,
+        };
+      }
+    } catch (error) {
+      return {
+        ok: false,
+        message:
+          `missing prerequisite: the Gitea repository ${repository} could not be read: ` +
+          (error instanceof Error ? error.message : String(error)),
+      };
+    }
+    return { ok: true, repository };
+  }
+
+  const execute = options.run ?? ((argv: string[]) => ghCommand(argv, environment));
+  const permission = await execute(["api", `repos/${repository}`, "--jq", ".permissions.push"]);
+  if (permission.code !== 0 || permission.stdout.trim() !== "true") {
+    const detail =
+      firstLine(permission.stderr) ??
+      firstLine(permission.stdout) ??
+      `gh exited with code ${permission.code}`;
+    return {
+      ok: false,
+      message:
+        `missing prerequisite: 'gh api repos/${repository} --jq .permissions.push' ` +
+        `did not return true: ${detail}`,
+    };
+  }
+
+  return { ok: true, repository };
+}

package/issues/scout/recommendation.ts

@@ -0,0 +1,400 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { isAbsolute, resolve, sep } from "node:path";
+import { isInteger } from "../guards";
+import {
+  CATEGORIES,
+  EXCLUDED_ROOTS,
+  SIGNIFICANCE_MAX,
+  SIGNIFICANCE_MIN,
+  type ScoutCategory,
+} from "./paths";
+
+/**
+ * The scan contract's answer: every recommendation the agent produced, checked
+ * against the repository before anything is filed. Validation is atomic — one
+ * malformed item rejects the whole answer, so a partial or invented result can
+ * never become an issue.
+ */
+
+export const TITLE_MAX = 200;
+const ID_LENGTH = 16;
+const MAX_SUMMARY = 4000;
+const MAX_QUOTE = 2000;
+const MAX_SIGNIFICANCE_REASON = 2000;
+
+export interface ScoutEvidence {
+  /** Repository-relative path, `/` separators. */
+  path: string;
+  /** `N` or `N-M`, inside the file's line count. */
+  lines: string;
+  quote?: string;
+}
+
+export interface ScoutRecommendation {
+  /** First 16 hex characters of the finding's identity hash. */
+  id: string;
+  category: ScoutCategory;
+  title: string;
+  summary: string;
+  impact: string;
+  evidence: ScoutEvidence[];
+  proposedChange: string;
+  files: string[];
+  acceptanceCriteria: string[];
+  /** 1–5; only a 4 or a 5 earns an issue. */
+  significance: number;
+  significanceReason: string;
+}
+
+export type ScanResult =
+  | { ok: true; items: ScoutRecommendation[]; shortfall: string | null }
+  | { ok: false; error: string };
+
+export function isCategory(value: unknown): value is ScoutCategory {
+  return typeof value === "string" && (CATEGORIES as readonly string[]).includes(value);
+}
+
+/** Lowercase, whitespace-collapsed, trimmed: the one title identity everywhere. */
+export function normalizeTitle(title: string): string {
+  return title.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+/**
+ * The `## Category` line of an issue body, for an issue Auto Scout adopted
+ * rather than filed. A missing heading or a blank value yields null.
+ */
+export function categoryFromBody(body: string): string | null {
+  const lines = body.split(/\r?\n/);
+  const heading = lines.findIndex((line) => line.trim().toLowerCase() === "## category");
+  if (heading < 0) return null;
+  for (let index = heading + 1; index < lines.length; index += 1) {
+    const value = lines[index]!.trim();
+    if (value.length === 0) continue;
+    if (value.startsWith("#")) return null;
+    return value.length <= 40 ? value : null;
+  }
+  return null;
+}
+
+/**
+ * The same finding produced twice keeps its id: the hash covers the category,
+ * the sorted evidence paths, and the normalized title, and nothing that a new
+ * scan may legitimately change, such as the summary or the significance score.
+ */
+export function recommendationId(
+  category: ScoutCategory,
+  evidencePaths: string[],
+  title: string,
+): string {
+  const paths = [...new Set(evidencePaths)].sort().join("\n");
+  return createHash("sha256")
+    .update([category, paths, normalizeTitle(title)].join("\u0000"))
+    .digest("hex")
+    .slice(0, ID_LENGTH);
+}
+
+/** Normalizes a repository-relative path for display and comparison. */
+export function normalizePath(value: string): string {
+  return value.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+function excluded(relativePath: string): boolean {
+  const segments = relativePath.split("/");
+  for (const root of EXCLUDED_ROOTS) {
+    const parts = root.split("/");
+    if (parts.length === 1) {
+      if (segments.includes(root)) return true;
+      continue;
+    }
+    for (let index = 0; index + parts.length <= segments.length; index += 1) {
+      let matched = true;
+      for (const [offset, part] of parts.entries()) {
+        if (segments[index + offset] !== part) {
+          matched = false;
+          break;
+        }
+      }
+      if (matched) return true;
+    }
+  }
+  return false;
+}
+
+export interface EvidenceCheck {
+  ok: boolean;
+  /** Repository-relative path when the check passed. */
+  path: string;
+  detail?: string;
+}
+
+const LINE_SPAN = /^(\d+)(?:-(\d+))?$/;
+
+/**
+ * Resolves one cited path inside the repository and checks the cited lines
+ * against the file's real length. A path escape, a missing or non-file target,
+ * an excluded tree, and an out-of-range span are all refusals.
+ */
+export function checkEvidencePath(repoDir: string, rawPath: string, lines: string): EvidenceCheck {
+  const path = normalizePath(rawPath);
+  if (path.length === 0) return { ok: false, path, detail: "the evidence path is empty" };
+  if (path.includes("\u0000")) return { ok: false, path, detail: "the evidence path is malformed" };
+  if (isAbsolute(path)) return { ok: false, path, detail: `${path} is absolute` };
+  const segments = path.split("/");
+  if (segments.includes("..")) return { ok: false, path, detail: `${path} escapes the repository` };
+  if (excluded(path)) {
+    return { ok: false, path, detail: `${path} is inside an excluded tree` };
+  }
+
+  let root: string;
+  try {
+    root = realpathSync(repoDir);
+  } catch {
+    return { ok: false, path, detail: `${repoDir} is not readable` };
+  }
+  const absolute = resolve(repoDir, path);
+  if (absolute !== root && !absolute.startsWith(`${root}${sep}`)) {
+    return { ok: false, path, detail: `${path} escapes the repository` };
+  }
+
+  let real: string;
+  try {
+    real = realpathSync(absolute);
+  } catch {
+    return { ok: false, path, detail: `${path} does not exist` };
+  }
+  if (real !== root && !real.startsWith(`${root}${sep}`)) {
+    return { ok: false, path, detail: `${path} escapes the repository` };
+  }
+  let stats;
+  try {
+    stats = lstatSync(real);
+  } catch {
+    return { ok: false, path, detail: `${path} does not exist` };
+  }
+  if (!stats.isFile()) return { ok: false, path, detail: `${path} is not a regular file` };
+
+  const span = LINE_SPAN.exec(lines.trim());
+  if (span === null) {
+    return { ok: false, path, detail: `${path}:${lines} is not a line span` };
+  }
+  const first = Number(span[1]);
+  const last = span[2] === undefined ? first : Number(span[2]);
+  let count: number;
+  try {
+    const text = readFileSync(real, "utf8");
+    count = text.length === 0 ? 0 : text.replace(/\n$/, "").split("\n").length;
+  } catch {
+    return { ok: false, path, detail: `${path} is not readable` };
+  }
+  if (first < 1 || last < first || last > count) {
+    return {
+      ok: false,
+      path,
+      detail: `${path}:${lines} is outside the file's ${count} line(s)`,
+    };
+  }
+  return { ok: true, path };
+}
+
+function boundedText(
+  value: unknown,
+  field: string,
+  limit: number,
+  label: string,
+): { ok: true; value: string } | { ok: false; error: string } {
+  if (typeof value !== "string") return { ok: false, error: `${label} has no ${field}` };
+  const text = value.trim();
+  if (text.length === 0) return { ok: false, error: `${label} has an empty ${field}` };
+  if (text.length > limit) {
+    return { ok: false, error: `${label} has a ${field} longer than ${limit} characters` };
+  }
+  return { ok: true, value: text };
+}
+
+function stringList(
+  value: unknown,
+  field: string,
+  label: string,
+): { ok: true; value: string[] } | { ok: false; error: string } {
+  if (!Array.isArray(value) || value.length === 0) {
+    return { ok: false, error: `${label} has no ${field}` };
+  }
+  const items: string[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "string" || entry.trim().length === 0) {
+      return { ok: false, error: `${label} has a blank ${field} entry` };
+    }
+    items.push(entry.trim());
+  }
+  return { ok: true, value: items };
+}
+
+function validateItem(
+  value: unknown,
+  index: number,
+  repoDir: string,
+): { ok: true; item: ScoutRecommendation } | { ok: false; error: string } {
+  const fallback = `item ${index + 1}`;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { ok: false, error: `${fallback} is not an object` };
+  }
+  const source = value as Record<string, unknown>;
+  const rawTitle = source.title;
+  const label =
+    typeof rawTitle === "string" && rawTitle.trim().length > 0
+      ? `item ${index + 1} ("${rawTitle.trim().slice(0, TITLE_MAX)}")`
+      : fallback;
+
+  if (!isCategory(source.category)) {
+    return { ok: false, error: `${label} has no valid category` };
+  }
+  const category = source.category;
+
+  const title = boundedText(rawTitle, "title", TITLE_MAX, label);
+  if (!title.ok) return title;
+  if (/[\r\n]/.test(rawTitle as string)) {
+    return { ok: false, error: `${label} has a title that spans more than one line` };
+  }
+
+  const summary = boundedText(source.summary, "summary", MAX_SUMMARY, label);
+  if (!summary.ok) return summary;
+  const proposedChange = boundedText(source.proposedChange, "proposed change", MAX_SUMMARY, label);
+  if (!proposedChange.ok) return proposedChange;
+
+  let impact = "";
+  if (source.impact !== undefined) {
+    const checked = boundedText(source.impact, "impact", MAX_SUMMARY, label);
+    if (!checked.ok) return checked;
+    impact = checked.value;
+  }
+
+  const significance = source.significance;
+  if (
+    !isInteger(significance) ||
+    significance < SIGNIFICANCE_MIN ||
+    significance > SIGNIFICANCE_MAX
+  ) {
+    return {
+      ok: false,
+      error: `${label} has no significance score from ${SIGNIFICANCE_MIN} to ${SIGNIFICANCE_MAX}`,
+    };
+  }
+  const reason = boundedText(
+    source.significanceReason,
+    "significance reason",
+    MAX_SIGNIFICANCE_REASON,
+    label,
+  );
+  if (!reason.ok) return reason;
+
+  if (!Array.isArray(source.evidence) || source.evidence.length === 0) {
+    return { ok: false, error: `${label} cites no evidence` };
+  }
+  const evidence: ScoutEvidence[] = [];
+  for (const [position, entry] of source.evidence.entries()) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      return { ok: false, error: `${label} evidence ${position + 1} is not an object` };
+    }
+    const record = entry as Record<string, unknown>;
+    if (typeof record.path !== "string") {
+      return { ok: false, error: `${label} evidence ${position + 1} has no path` };
+    }
+    if (typeof record.lines !== "string") {
+      return { ok: false, error: `${label} evidence ${position + 1} has no line span` };
+    }
+    if (record.quote !== undefined && typeof record.quote !== "string") {
+      return { ok: false, error: `${label} evidence ${position + 1} has a non-text quote` };
+    }
+    const check = checkEvidencePath(repoDir, record.path, record.lines);
+    if (!check.ok) return { ok: false, error: `${label} evidence: ${check.detail}` };
+    const quote =
+      typeof record.quote === "string" && record.quote.trim().length > 0
+        ? record.quote.trim().slice(0, MAX_QUOTE)
+        : undefined;
+    evidence.push({
+      path: check.path,
+      lines: record.lines.trim(),
+      ...(quote === undefined ? {} : { quote }),
+    });
+  }
+
+  const files = stringList(source.files, "file list", label);
+  if (!files.ok) return files;
+  const cited = new Set(evidence.map((entry) => entry.path));
+  const normalizedFiles = files.value.map(normalizePath);
+  for (const file of normalizedFiles) {
+    if (!cited.has(file)) {
+      return { ok: false, error: `${label} lists ${file}, which its evidence does not cite` };
+    }
+  }
+
+  const criteria = stringList(source.acceptanceCriteria, "acceptance criteria", label);
+  if (!criteria.ok) return criteria;
+
+  return {
+    ok: true,
+    item: {
+      id: recommendationId(category, evidence.map((entry) => entry.path), title.value),
+      category,
+      title: title.value,
+      summary: summary.value,
+      impact,
+      evidence,
+      proposedChange: proposedChange.value,
+      files: [...new Set(normalizedFiles)],
+      acceptanceCriteria: criteria.value,
+      significance,
+      significanceReason: reason.value,
+    },
+  };
+}
+
+/**
+ * Parses `<scan-dir>/recommendations.json`. A result may carry at most the
+ * count the request asked for; anything else fails the whole scan.
+ */
+export function parseScanResult(
+  value: unknown,
+  options: { requested: number; repoDir: string },
+): ScanResult {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { ok: false, error: "the result is not a JSON object" };
+  }
+  const source = value as Record<string, unknown>;
+  if (!Array.isArray(source.recommendations)) {
+    return { ok: false, error: "the result has no recommendations array" };
+  }
+  if (source.recommendations.length > options.requested) {
+    return {
+      ok: false,
+      error:
+        `the result carried ${source.recommendations.length} recommendations, ` +
+        `more than the ${options.requested} requested`,
+    };
+  }
+
+  const items: ScoutRecommendation[] = [];
+  const ids = new Map<string, number>();
+  for (const [index, entry] of source.recommendations.entries()) {
+    const checked = validateItem(entry, index, options.repoDir);
+    if (!checked.ok) return { ok: false, error: checked.error };
+    const seen = ids.get(checked.item.id);
+    if (seen !== undefined) {
+      return {
+        ok: false,
+        error:
+          `item ${index + 1} ("${checked.item.title}") repeats the id of item ${seen + 1}: ` +
+          checked.item.id,
+      };
+    }
+    ids.set(checked.item.id, index);
+    items.push(checked.item);
+  }
+
+  const shortfall =
+    typeof source.shortfall === "string" && source.shortfall.trim().length > 0
+      ? source.shortfall.trim()
+      : null;
+  return { ok: true, items, shortfall };
+}