@dsdenes/devboard 0.1.560 → 0.1.563

package/issues/repository.ts

@@ -0,0 +1,203 @@
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { parseForgeRemote, type ForgeRemote } from "../lib/forge";
+
+/**
+ * Checkout facts the issues worker and its dashboard discover at runtime.
+ * Nothing here names a host, a user, or a repository: every value comes from
+ * git, the caller, or the runtime environment.
+ */
+
+export interface CommandOutcome {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+export function git(directory: string, ...args: string[]): CommandOutcome {
+  try {
+    const result = Bun.spawnSync({
+      cmd: ["git", "-C", directory, ...args],
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    return {
+      code: result.exitCode ?? 1,
+      stdout: result.stdout.toString().trim(),
+      stderr: result.stderr.toString().trim(),
+    };
+  } catch (error) {
+    return { code: 1, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** The checkout root containing `directory`, or undefined outside a checkout. */
+export function topLevel(directory: string): string | undefined {
+  const result = git(directory, "rev-parse", "--show-toplevel");
+  return result.code === 0 && result.stdout.length > 0 ? result.stdout : undefined;
+}
+
+/** True when the checkout at `root` is a linked worktree, not the canonical one. */
+export function isLinkedWorktree(root: string): boolean {
+  const absolute = git(root, "rev-parse", "--absolute-git-dir");
+  const common = git(root, "rev-parse", "--path-format=absolute", "--git-common-dir");
+  if (absolute.code !== 0 || common.code !== 0) return false;
+  return absolute.stdout.length > 0 && absolute.stdout !== common.stdout;
+}
+
+const REPOSITORY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+
+/** `owner/name` from any git remote URL form, or undefined. */
+export function repositoryFromUrl(url: string): string | undefined {
+  const trimmed = url.trim();
+  const scp = /^[A-Za-z0-9_.-]+@[^:/]+:(.+)$/.exec(trimmed);
+  const path = scp !== null ? scp[1]! : trimmed.replace(/^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^/]+\//, "");
+  const segments = path.split("/").filter((segment) => segment.length > 0);
+  if (segments.length < 2) return undefined;
+  const name = segments[segments.length - 1]!.replace(/\.git$/, "");
+  const owner = segments[segments.length - 2]!;
+  const repository = `${owner}/${name}`;
+  return REPOSITORY.test(repository) ? repository : undefined;
+}
+
+/** The remote URL of `origin`, if the checkout has one. */
+export function originRemoteUrl(root: string): string | undefined {
+  const remote = git(root, "remote", "get-url", "origin");
+  return remote.code === 0 && remote.stdout.length > 0 ? remote.stdout : undefined;
+}
+
+/**
+ * True only for a GitHub remote. GitLab, a local path, and an unreadable URL
+ * are all refused: this harness supports one tracker and adds no webhook.
+ */
+export function isGitHubRemote(url: string): boolean {
+  const trimmed = url.trim();
+  const scp = /^[A-Za-z0-9_.-]+@([^:/]+):/.exec(trimmed);
+  if (scp !== null) return scp[1]!.toLowerCase() === "github.com";
+  try {
+    const parsed = new URL(trimmed);
+    return parsed.hostname.toLowerCase() === "github.com";
+  } catch {
+    return false;
+  }
+}
+
+/** The forge the checkout's origin names, or undefined outside a supported remote. */
+export function originForge(
+  root: string,
+  environment: Record<string, string | undefined> = process.env,
+): ForgeRemote | undefined {
+  // A directory below a checkout must not inherit that checkout's remote: the
+  // caller's root is the host, and only its own top level names the origin.
+  const top = git(root, "rev-parse", "--show-toplevel");
+  if (top.code !== 0) return undefined;
+  const found = resolve(top.stdout);
+  if (found !== resolve(root)) return undefined;
+  const remote = originRemoteUrl(root);
+  return remote === undefined ? undefined : parseForgeRemote(remote, environment);
+}
+
+/** The `owner/name` the checkout's origin names, or undefined. */
+export function originRepository(root: string): string | undefined {
+  const url = originRemoteUrl(root);
+  return url === undefined ? undefined : repositoryFromUrl(url);
+}
+
+/**
+ * A live `owner/name` lookup for a process that outlives the origin's setup.
+ * A remote can be added or re-pointed while a dashboard runs, so the answer
+ * is re-read at most every `ttlMs` instead of frozen at startup. The reads
+ * are cached: a dashboard polls its snapshot far more often than an origin
+ * can change.
+ */
+export function cachedRepository(
+  root: string,
+  ttlMs = 10_000,
+): () => string | null {
+  let value: string | null = originRepository(root) ?? null;
+  let checkedAt = Date.now();
+  return () => {
+    const now = Date.now();
+    if (now - checkedAt >= ttlMs) {
+      value = originRepository(root) ?? null;
+      checkedAt = now;
+    }
+    return value;
+  };
+}
+
+export function isRepositoryName(value: string): boolean {
+  return REPOSITORY.test(value);
+}
+
+/** The harness directory a canonical checkout carries. */
+export function harnessDirectory(root: string): string {
+  return join(root, ".devboard");
+}
+
+/**
+ * Validates a root exactly as the removed orchestrator did: a git checkout at
+ * that exact path, not a linked worktree, carrying `.devboard/`.
+ */
+export function rootProblem(root: string): string | undefined {
+  const absolute = resolve(root);
+  if (!existsSync(absolute)) return `${absolute} does not exist`;
+  const top = topLevel(absolute);
+  if (top === undefined) return `${absolute} is not a git checkout`;
+  if (resolve(top) !== absolute) return `${absolute} is not the checkout root (${top} is)`;
+  if (isLinkedWorktree(absolute)) {
+    return `${absolute} is a linked git worktree, not the canonical checkout`;
+  }
+  if (!existsSync(harnessDirectory(absolute))) {
+    return `${absolute} has no .devboard directory`;
+  }
+  return undefined;
+}
+
+/** Resolves symlinks so a worker started from a link sees the real harness. */
+export function realDirectory(path: string): string | undefined {
+  try {
+    return realpathSync(path);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Finds an executable the way a shell would, using the supplied environment. */
+export function findOnPath(
+  name: string,
+  environment: Record<string, string | undefined> = process.env,
+): string | undefined {
+  const path = environment.PATH ?? "";
+  for (const directory of path.split(":")) {
+    if (directory.length === 0) continue;
+    const candidate = join(directory, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+/** Every directory an omp command may be installed in, checkout first. */
+export function ompCommandPaths(
+  root: string,
+  environment: Record<string, string | undefined> = process.env,
+): string[] {
+  const home = environment.HOME ?? homedir();
+  return [
+    join(resolve(root), ".omp", "commands"),
+    join(resolve(root), ".omp", "agent", "commands"),
+    join(home, ".omp", "commands"),
+    join(home, ".omp", "agent", "commands"),
+  ];
+}
+
+/** Every directory an omp extension may be installed in, checkout first. */
+export function ompExtensionPaths(
+  root: string,
+  environment: Record<string, string | undefined> = process.env,
+): string[] {
+  const home = environment.HOME ?? homedir();
+  return [join(resolve(root), ".omp", "extensions"), join(home, ".omp", "extensions")];
+}

package/issues/scout/actions.ts

@@ -0,0 +1,255 @@
+import { join } from "node:path";
+import {
+  authEnvironment,
+  isAuthFailure,
+  resolveForgeAuth,
+  type Exec,
+} from "../../lib/forge-auth";
+import { configuredGiteaToken, giteaBaseUrl, type Forge } from "../../lib/forge";
+import {
+  giteaCreateIssue,
+  giteaEnsureLabel,
+  type FetchLike,
+} from "../../lib/gitea";
+import { originForge } from "../repository";
+import { ghCommand, runCommand } from "./preflight";
+import { issueBodyDirectory } from "./paths";
+import { writeAtomic } from "./state";
+import type { ScoutRecommendation } from "./recommendation";
+
+/**
+ * Filing one recommendation as one issue in the host origin. It is called only
+ * from the detached worker, and a failure throws so the scan records the reason
+ * and files nothing else.
+ */
+
+export interface GhRunner {
+  (argv: string[], environment: Record<string, string>): Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+  }>;
+}
+
+export const SCOUT_LABEL = "scout";
+
+const LABEL_DESCRIPTION = "Significant improvement recommendation from Auto Scout";
+
+function firstLine(text: string): string {
+  return (
+    text
+      .split("\n")
+      .map((line) => line.trim())
+      .find((line) => line.length > 0) ?? "no diagnostic"
+  );
+}
+
+function evidenceLine(entry: ScoutRecommendation["evidence"][number]): string {
+  const quote =
+    entry.quote === undefined ? "" : `\n  > ${entry.quote.replace(/\n/g, "\n  > ")}`;
+  return `- \`${entry.path}:${entry.lines}\`${quote}`;
+}
+
+/** The issue body: everything the implementer needs, and nothing else. */
+export function issueBody(recommendation: ScoutRecommendation): string {
+  return [
+    `## Category`,
+    "",
+    recommendation.category,
+    "",
+    "## Summary",
+    "",
+    recommendation.summary,
+    "",
+    ...(recommendation.impact.length === 0
+      ? []
+      : ["## Impact", "", recommendation.impact, ""]),
+    "## Significance",
+    "",
+    `${recommendation.significance}/5`,
+    "",
+    recommendation.significanceReason,
+    "",
+    "## Evidence",
+    "",
+    ...recommendation.evidence.map(evidenceLine),
+    "",
+    "## Proposed change",
+    "",
+    recommendation.proposedChange,
+    "",
+    "## Files",
+    "",
+    ...recommendation.files.map((file) => `- \`${file}\``),
+    "",
+    "## Acceptance criteria",
+    "",
+    ...recommendation.acceptanceCriteria.map((criterion) => `- ${criterion}`),
+    "",
+    "---",
+    "",
+    "Filed by Auto Scout. Implement this issue the way any other open issue is implemented.",
+    "",
+  ].join("\n");
+}
+
+export interface FileIssueOptions {
+  repoDir: string;
+  /** The host origin's `owner/name`. */
+  repository: string;
+  recommendation: ScoutRecommendation;
+  environment?: Record<string, string | undefined>;
+  /** Injectable forge commands; defaults to the operator's `gh`. */
+  run?: GhRunner;
+  exec?: Exec;
+  now?: () => Date;
+  /**
+   * Absolute epoch deadline for the whole filing. Every probe and command is
+   * killed when it elapses; commands before it are bounded by what remains.
+   */
+  deadline?: number;
+  /** Aborting cancels an in-flight probe or command. */
+  signal?: AbortSignal;
+  /** Overrides origin forge detection; tests use it. */
+  forge?: Forge;
+  /** Gitea HTTP origin. */
+  baseUrl?: string;
+  /** Injectable transport for the Gitea API. */
+  giteaFetch?: FetchLike;
+}
+
+const bunExec: Exec = async (commandName, args, options) => {
+  const result = await runCommand([commandName, ...args], options.env, {
+    cwd: options.cwd,
+    ...(options.timeout === undefined ? {} : { timeoutMs: options.timeout }),
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+  });
+  return {
+    stdout: result.stdout,
+    stderr: result.stderr,
+    code: result.code,
+    killed: result.killed ?? false,
+  };
+};
+
+async function fileGiteaIssue(
+  options: FileIssueOptions,
+  environment: Record<string, string | undefined>,
+): Promise<{ url: string; number: number }> {
+  const remote = originForge(options.repoDir, environment);
+  const baseUrl = options.baseUrl ?? giteaBaseUrl(remote, environment);
+  if (baseUrl === undefined || baseUrl.length === 0) {
+    throw new Error("filing a Gitea issue needs DEVBOARD_GITEA_URL");
+  }
+  const token = configuredGiteaToken(environment);
+  if (token === undefined) throw new Error("filing a Gitea issue needs GITEA_TOKEN");
+  const target = { baseUrl, project: options.repository, token };
+  const label = await giteaEnsureLabel(
+    target,
+    SCOUT_LABEL,
+    "0e8a16",
+    LABEL_DESCRIPTION,
+    options.giteaFetch,
+  );
+  const issue = await giteaCreateIssue(
+    target,
+    {
+      title: options.recommendation.title,
+      body: issueBody(options.recommendation),
+      labels: [label],
+    },
+    options.giteaFetch,
+  );
+  return { url: issue.url, number: issue.number };
+}
+
+/**
+ * Files one issue for one staged recommendation. The label is created when it
+ * is absent, the body is passed as a file, and the returned URL is the only
+ * fact recorded in the decisions.
+ */
+export async function fileScoutIssue(options: FileIssueOptions): Promise<{ url: string; number: number }> {
+  const environment = options.environment ?? process.env;
+  const remote = originForge(options.repoDir, environment);
+  const forge = options.forge ?? remote?.forge ?? "github";
+  if (forge === "gitea") {
+    return await fileGiteaIssue(options, environment);
+  }
+  const auth = await resolveForgeAuth(options.exec ?? bunExec, {
+    forge,
+    host: remote?.host ?? "github.com",
+    project: options.repository,
+    cwd: options.repoDir,
+    required: "write",
+    env: environment,
+    ...(options.deadline === undefined ? {} : { deadline: options.deadline }),
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+  });
+  if (isAuthFailure(auth)) throw new Error(auth.error.split("\n")[0] ?? auth.error);
+  const forgeEnvironment = authEnvironment(auth, environment);
+  const run =
+    options.run ??
+    ((argv, env) =>
+      ghCommand(argv, env, {
+        ...(options.deadline === undefined
+          ? {}
+          : { timeoutMs: Math.max(1, options.deadline - Date.now()) }),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+      }));
+
+  const existing = await run(["api", `repos/${options.repository}/labels/${SCOUT_LABEL}`], forgeEnvironment);
+  if (existing.code !== 0) {
+    const created = await run(
+      [
+        "label",
+        "create",
+        SCOUT_LABEL,
+        "--repo",
+        options.repository,
+        "--description",
+        LABEL_DESCRIPTION,
+        "--color",
+        "0e8a16",
+      ],
+      forgeEnvironment,
+    );
+    if (created.code !== 0) {
+      throw new Error(`could not create the scout label: ${firstLine(created.stderr)}`);
+    }
+  }
+
+  const stamp = (options.now ?? (() => new Date()))().toISOString().replace(/[:.]/g, "-");
+  const bodyPath = join(issueBodyDirectory(options.repoDir), `${options.recommendation.id}-${stamp}.md`);
+  writeAtomic(bodyPath, issueBody(options.recommendation));
+
+  const created = await run(
+    [
+      "issue",
+      "create",
+      "--repo",
+      options.repository,
+      "--title",
+      options.recommendation.title,
+      "--body-file",
+      bodyPath,
+      "--label",
+      SCOUT_LABEL,
+    ],
+    forgeEnvironment,
+  );
+  if (created.code !== 0) {
+    throw new Error(`could not file the issue: ${firstLine(created.stderr)}`);
+  }
+  const url = created.stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => /^https?:\/\//.test(line));
+  if (url === undefined) {
+    throw new Error("the issue was created without a URL");
+  }
+  const number = /\/issues\/(\d+)\/?$/.exec(url);
+  if (number === null) {
+    throw new Error("the issue was created without an issue number");
+  }
+  return { url, number: Number(number[1]) };
+}

package/issues/scout/control.ts

@@ -0,0 +1,80 @@
+import { mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isRecord } from "../guards";
+import { isValidLimit } from "./state";
+
+/**
+ * The dashboard-to-scout 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. Only Stop and a limits change remain:
+ * filing needs no command.
+ */
+
+export type ScoutCommand =
+  | { type: "stop" }
+  | { type: "limits"; maxPerHour: number; maxPending: number };
+
+let sequence = 0;
+
+export function writeCommand(directory: string, command: ScoutCommand): 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;
+}
+
+export function parseCommand(text: string): ScoutCommand | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(parsed)) return undefined;
+  switch (parsed.type) {
+    case "stop":
+      return { type: "stop" };
+    case "limits":
+      if (!isValidLimit(parsed.maxPerHour) || !isValidLimit(parsed.maxPending)) return undefined;
+      return {
+        type: "limits",
+        maxPerHour: parsed.maxPerHour,
+        maxPending: parsed.maxPending,
+      };
+    default:
+      return undefined;
+  }
+}
+
+/** Reads and consumes every pending command in name order. */
+export function takeCommands(directory: string): ScoutCommand[] {
+  let names: string[];
+  try {
+    names = readdirSync(directory).filter((name) => name.endsWith(".json")).sort();
+  } catch {
+    return [];
+  }
+  const commands: ScoutCommand[] = [];
+  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;
+}