beflow 0.1.0

package/src/core/doctor.ts

@@ -0,0 +1,223 @@
+import { resolveAcpxCommand } from "../agent/acpx.ts";
+import type { Config, Registry } from "../config/schema.ts";
+
+export type CheckLevel = "pass" | "warn" | "fail";
+
+export interface DoctorCheck {
+    name: string;
+    level: CheckLevel;
+    detail: string;
+}
+
+export interface DoctorDeps {
+    loadConfig: () => Config;
+    loadRegistry: () => Registry;
+    env: NodeJS.ProcessEnv;
+    fileExists: (path: string) => boolean;
+    onPath: (cmd: string) => boolean;
+    ping?: (config: Config, registry: Registry) => Promise<string>;
+    boardChecks?: () => Promise<DoctorCheck[]>;
+}
+
+const API_KEY_HINT =
+    "mint a personal API token (Plane: Profile → Settings → API tokens; Linear: Settings → API → Personal keys) and put it in .env as";
+
+export async function doctor(deps: DoctorDeps): Promise<DoctorCheck[]> {
+    const checks: DoctorCheck[] = [];
+
+    let config: Config | undefined;
+    try {
+        config = deps.loadConfig();
+        checks.push({
+            detail: `loaded; active tracker "${config.tracker}"`,
+            level: "pass",
+            name: "config.json",
+        });
+    } catch (err) {
+        checks.push({
+            detail: err instanceof Error ? err.message : String(err),
+            level: "fail",
+            name: "config.json",
+        });
+    }
+
+    const trackerConfig = config !== undefined ? config.trackers[config.tracker] : undefined;
+    if (config !== undefined) {
+        if (trackerConfig === undefined) {
+            checks.push({
+                detail: `no config for active tracker "${config.tracker}" under "trackers"`,
+                level: "fail",
+                name: "tracker config",
+            });
+        } else {
+            checks.push({
+                detail: `"${config.tracker}" configured`,
+                level: "pass",
+                name: "tracker config",
+            });
+        }
+    } else {
+        checks.push({
+            detail: "skipped — config.json did not load",
+            level: "fail",
+            name: "tracker config",
+        });
+    }
+
+    let registry: Registry | undefined;
+    try {
+        registry = deps.loadRegistry();
+        const count = Object.keys(registry.projects).length;
+        if (count === 0) {
+            checks.push({
+                detail: "loaded but has no projects",
+                level: "fail",
+                name: "projects",
+            });
+            registry = undefined;
+        } else {
+            checks.push({
+                detail: `loaded; ${String(count)} project(s)`,
+                level: "pass",
+                name: "projects",
+            });
+        }
+    } catch (err) {
+        checks.push({
+            detail: err instanceof Error ? err.message : String(err),
+            level: "fail",
+            name: "projects",
+        });
+    }
+
+    let apiKeyOk = false;
+    if (config !== undefined && trackerConfig !== undefined) {
+        const envName = trackerConfig.apiKeyEnv;
+        const value = deps.env[envName];
+        if (value === undefined || value === "") {
+            checks.push({
+                detail: `${envName} is unset — ${API_KEY_HINT} ${envName}=…`,
+                level: "fail",
+                name: "API key",
+            });
+        } else {
+            apiKeyOk = true;
+            checks.push({
+                detail: `${envName} is set`,
+                level: "pass",
+                name: "API key",
+            });
+        }
+    } else {
+        checks.push({
+            detail: "skipped — config or tracker config did not load",
+            level: "fail",
+            name: "API key",
+        });
+    }
+
+    if (registry !== undefined) {
+        const missing: string[] = [];
+        for (const [key, project] of Object.entries(registry.projects)) {
+            if (!deps.fileExists(project.root)) {
+                missing.push(`${key} root ${project.root}`);
+            }
+            for (const [repoName, repoPath] of Object.entries(project.repos)) {
+                if (!deps.fileExists(repoPath)) {
+                    missing.push(`${key} repo ${repoName} ${repoPath}`);
+                }
+            }
+        }
+        if (missing.length > 0) {
+            checks.push({
+                detail: `missing: ${missing.join("; ")}`,
+                level: "fail",
+                name: "repos on disk",
+            });
+        } else {
+            checks.push({
+                detail: "all project roots and repos exist",
+                level: "pass",
+                name: "repos on disk",
+            });
+        }
+    } else {
+        checks.push({
+            detail: "skipped — registry did not load",
+            level: "fail",
+            name: "repos on disk",
+        });
+    }
+
+    const acpxCmd = config !== undefined ? resolveAcpxCommand(config) : ["bunx", "acpx"];
+    const launcher = acpxCmd[0];
+    if (launcher === undefined) {
+        throw new Error("beflow: acpx command resolved to an empty array");
+    }
+    if (deps.onPath(launcher)) {
+        checks.push({
+            detail: `found on PATH (${acpxCmd.join(" ")})`,
+            level: "pass",
+            name: "acpx",
+        });
+    } else {
+        checks.push({
+            detail: `launcher "${launcher}" not on PATH — default is "bunx acpx" (ships with bun); or set tools.acpx, or run: bun add -g acpx`,
+            level: "fail",
+            name: "acpx",
+        });
+    }
+
+    if (deps.onPath("gh")) {
+        checks.push({ detail: "found on PATH", level: "pass", name: "gh" });
+    } else {
+        checks.push({
+            detail: "not on PATH — only needed for the PR step of implement mode",
+            level: "warn",
+            name: "gh",
+        });
+    }
+
+    if (deps.ping !== undefined) {
+        if (config === undefined || trackerConfig === undefined || registry === undefined || !apiKeyOk) {
+            checks.push({
+                detail: "skipped — an earlier check failed",
+                level: "fail",
+                name: "live ping",
+            });
+        } else {
+            try {
+                const detail = await deps.ping(config, registry);
+                checks.push({ detail, level: "pass", name: "live ping" });
+            } catch (err) {
+                checks.push({
+                    detail: err instanceof Error ? err.message : String(err),
+                    level: "fail",
+                    name: "live ping",
+                });
+            }
+        }
+    }
+
+    if (deps.boardChecks !== undefined) {
+        if (config === undefined || trackerConfig === undefined || registry === undefined || !apiKeyOk) {
+            checks.push({
+                detail: "skipped — an earlier check failed",
+                level: "fail",
+                name: "board drift",
+            });
+        } else {
+            try {
+                checks.push(...(await deps.boardChecks()));
+            } catch (err) {
+                checks.push({
+                    detail: err instanceof Error ? err.message : String(err),
+                    level: "fail",
+                    name: "board drift",
+                });
+            }
+        }
+    }
+
+    return checks;
+}

package/src/core/drift.ts

@@ -0,0 +1,59 @@
+import type { BoardTemplate, BoardState, Tracker } from "../trackers/tracker.ts";
+
+// States beflow operationally depends on (queue + writeback targets).
+export const REQUIRED_STATES = ["Backlog", "Todo", "In Progress", "Needs Input", "In Review", "Done"];
+// Labels beflow's writeback creates/uses.
+export const REQUIRED_LABELS = ["blocked", "quarantined", "triaged"];
+
+export interface DriftReport {
+    missingStates: string[]; // In template, absent on tracker
+    missingLabels: string[];
+    missingModules: string[];
+    extraStates: string[]; // On tracker, not in template (helps spot renames)
+}
+
+export function boardDrift(template: BoardTemplate, board: BoardState): DriftReport {
+    const boardStates = new Set(board.states);
+    const boardLabels = new Set(board.labels);
+    const boardModules = new Set(board.modules);
+    const templateStates = new Set(template.states.map((s) => s.name));
+
+    return {
+        extraStates: board.states.filter((name) => !templateStates.has(name)),
+        missingLabels: template.labels.map((l) => l.name).filter((name) => !boardLabels.has(name)),
+        missingModules: template.modules.map((m) => m.name).filter((name) => !boardModules.has(name)),
+        missingStates: template.states.map((s) => s.name).filter((name) => !boardStates.has(name)),
+    };
+}
+
+// Pre-run guard: throws a clear, actionable error if a REQUIRED state/label is
+// Missing. If the board cannot be inspected (network / not implemented), it logs
+// And PROCEEDS (inability to verify is not the same as drift).
+export async function assertBoardReady(projectKey: string, tracker: Tracker, log?: (m: string) => void): Promise<void> {
+    let board: BoardState;
+    try {
+        board = await tracker.inspectBoard(projectKey);
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log?.(`beflow: could not verify board for ${projectKey} (${msg}); proceeding`);
+        return;
+    }
+
+    const missingStates = REQUIRED_STATES.filter((s) => !board.states.includes(s));
+    const missingLabels = REQUIRED_LABELS.filter((l) => !board.labels.includes(l));
+    if (missingStates.length === 0 && missingLabels.length === 0) {
+        return;
+    }
+
+    const parts: string[] = [];
+    if (missingStates.length > 0) {
+        parts.push(`state(s): ${missingStates.join(", ")}`);
+    }
+    if (missingLabels.length > 0) {
+        parts.push(`label(s): ${missingLabels.join(", ")}`);
+    }
+
+    throw new Error(
+        `beflow: board for ${projectKey} has drifted — missing ${parts.join("; ")} (present states: ${board.states.join(", ")}). Run \`beflow update ${projectKey}\` to reconcile.`,
+    );
+}

package/src/core/gc.ts

@@ -0,0 +1,223 @@
+import { readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { listRecords, nodeRunStoreFs, systemClock } from "./runstore.ts";
+import type { Clock, RunStoreFs } from "./runstore.ts";
+import { removeWorktree, sanitizeKey } from "./worktree.ts";
+import type { Exec } from "./worktree.ts";
+
+export interface GcFs {
+    listDirs(dir: string): string[];
+    mtimeMs(path: string): number;
+    removeDir(path: string): void;
+}
+
+export const nodeGcFs: GcFs = {
+    listDirs(dir) {
+        try {
+            return readdirSync(dir, { withFileTypes: true })
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name);
+        } catch {
+            return [];
+        }
+    },
+    mtimeMs(path) {
+        try {
+            return statSync(path).mtimeMs;
+        } catch {
+            return 0;
+        }
+    },
+    removeDir(path) {
+        rmSync(path, { force: true, recursive: true });
+    },
+};
+
+export interface OrphanWorktree {
+    name: string;
+    path: string;
+    repoPath?: string;
+    dirty: boolean;
+    unpushed: boolean;
+    ageDays: number;
+    safe: boolean;
+    heldReason?: string;
+}
+
+const MS_PER_DAY = 86_400_000;
+
+function clockMs(clock: Clock): number {
+    const parsed = Date.parse(clock());
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+// Parses `git worktree list --porcelain` and returns the FIRST `worktree <path>`
+// line, which is always the source (main) repository. undefined when the output
+// has no such line.
+function parseSourceRepo(stdout: string): string | undefined {
+    for (const line of stdout.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            return line.slice("worktree ".length).trim();
+        }
+    }
+    return undefined;
+}
+
+async function inspectOrphan(path: string, ageDays: number, git: Exec): Promise<OrphanWorktree> {
+    const name = path.slice(path.lastIndexOf("/") + 1);
+
+    const listed = await git("git", ["-C", path, "worktree", "list", "--porcelain"]);
+    const repoPath = listed.code === 0 ? parseSourceRepo(listed.stdout) : undefined;
+    if (repoPath === undefined) {
+        return {
+            ageDays,
+            dirty: false,
+            heldReason: "unregistered/broken worktree",
+            name,
+            path,
+            safe: false,
+            unpushed: false,
+        };
+    }
+
+    const status = await git("git", ["-C", path, "status", "--porcelain"]);
+    const dirty = status.code !== 0 || status.stdout.trim().length > 0;
+
+    const revList = await git("git", ["-C", path, "rev-list", "HEAD", "--not", "--remotes"]);
+    const unpushed = revList.code !== 0 || revList.stdout.trim().length > 0;
+
+    const reason = dirty ? "uncommitted changes" : unpushed ? "unpushed commits" : undefined;
+    return {
+        ageDays,
+        dirty,
+        name,
+        path,
+        repoPath,
+        safe: !dirty && !unpushed,
+        unpushed,
+        ...(reason !== undefined ? { heldReason: reason } : {}),
+    };
+}
+
+export async function collectOrphans(opts: {
+    worktreesDir: string;
+    runsDir: string;
+    git: Exec;
+    fs?: GcFs;
+    runsFs?: RunStoreFs;
+    clock?: Clock;
+}): Promise<OrphanWorktree[]> {
+    const fs = opts.fs ?? nodeGcFs;
+    const runsFs = opts.runsFs ?? nodeRunStoreFs;
+    const clock = opts.clock ?? systemClock;
+    const now = clockMs(clock);
+
+    const recorded = new Set(listRecords(opts.runsDir, runsFs).map((r) => sanitizeKey(r.key)));
+
+    const orphans: OrphanWorktree[] = [];
+    for (const name of fs.listDirs(opts.worktreesDir)) {
+        if (recorded.has(name)) {
+            continue;
+        }
+        const path = join(opts.worktreesDir, name);
+        const ageDays = (now - fs.mtimeMs(path)) / MS_PER_DAY;
+        orphans.push(await inspectOrphan(path, ageDays, opts.git));
+    }
+    return orphans;
+}
+
+export interface GcPlan {
+    pruned: OrphanWorktree[];
+    held: OrphanWorktree[];
+    skippedByAge: OrphanWorktree[];
+}
+
+async function removeOrphan(orphan: OrphanWorktree, git: Exec, fs: GcFs): Promise<void> {
+    if (orphan.repoPath !== undefined) {
+        try {
+            await removeWorktree(orphan.repoPath, orphan.path, git);
+            return;
+        } catch {
+            // `git worktree remove` failed (e.g. locked/corrupt); fall back to
+            // a raw recursive delete plus a best-effort prune of the dangling
+            // administrative entry in the source repo.
+        }
+    }
+    fs.removeDir(orphan.path);
+    if (orphan.repoPath !== undefined) {
+        await git("git", ["-C", orphan.repoPath, "worktree", "prune"]);
+    }
+}
+
+export async function runGc(opts: {
+    worktreesDir: string;
+    runsDir: string;
+    git: Exec;
+    fs?: GcFs;
+    runsFs?: RunStoreFs;
+    clock?: Clock;
+    prune?: boolean;
+    force?: boolean;
+    olderThanDays?: number;
+    log?: (m: string) => void;
+}): Promise<GcPlan> {
+    const fs = opts.fs ?? nodeGcFs;
+    const log =
+        opts.log ??
+        ((): void => {
+            /* no-op: logging disabled */
+        });
+    const collectOpts: Parameters<typeof collectOrphans>[0] = {
+        git: opts.git,
+        runsDir: opts.runsDir,
+        worktreesDir: opts.worktreesDir,
+        ...(opts.fs !== undefined ? { fs: opts.fs } : {}),
+        ...(opts.runsFs !== undefined ? { runsFs: opts.runsFs } : {}),
+        ...(opts.clock !== undefined ? { clock: opts.clock } : {}),
+    };
+    const orphans = await collectOrphans(collectOpts);
+
+    const plan: GcPlan = { held: [], pruned: [], skippedByAge: [] };
+    const force = opts.force === true;
+    const prune = opts.prune === true;
+
+    for (const orphan of orphans) {
+        if (opts.olderThanDays !== undefined && orphan.ageDays < opts.olderThanDays) {
+            plan.skippedByAge.push(orphan);
+            continue;
+        }
+        const isTarget = force || orphan.safe;
+        if (isTarget) {
+            plan.pruned.push(orphan);
+        } else {
+            plan.held.push(orphan);
+        }
+    }
+
+    if (prune) {
+        for (const orphan of plan.pruned) {
+            await removeOrphan(orphan, opts.git, fs);
+            log(`gc: removed orphan worktree ${orphan.path}`);
+        }
+    } else {
+        for (const orphan of plan.pruned) {
+            log(`gc: would remove orphan worktree ${orphan.path}`);
+        }
+    }
+
+    for (const orphan of plan.held) {
+        log(`gc: held ${orphan.path} — ${orphan.heldReason ?? "not safe"} (re-run with --force to remove)`);
+    }
+    for (const orphan of plan.skippedByAge) {
+        log(`gc: skipped ${orphan.path} — newer than threshold`);
+    }
+
+    log(
+        `gc: ${String(orphans.length)} orphan worktree(s) — ${String(plan.pruned.length)} ${
+            prune ? "pruned" : "to prune"
+        }, ${String(plan.held.length)} held (use --force), ${String(plan.skippedByAge.length)} too new`,
+    );
+
+    return plan;
+}

package/src/core/inputquality.ts

@@ -0,0 +1,30 @@
+import type { Config, Registry } from "../config/schema.ts";
+
+export const THIN_ISSUE_MESSAGE =
+    "This work item was moved to Needs Input because its description looks too thin for an agent to act on safely. Please add a clear description — what needs to change, and how you'll know it's done — then leave a comment, and beflow will pick it up automatically.";
+
+const ENTITIES: Record<string, string> = {
+    "&amp;": "&",
+    "&gt;": ">",
+    "&lt;": "<",
+    "&nbsp;": " ",
+};
+
+/**
+ * Plane bodies are `description_html`, so a raw `.length` over-counts markup. Strip
+ * tags, decode the few common entities, collapse whitespace runs, and trim, so the
+ * returned length reflects the actual human-visible text.
+ */
+export function visibleBodyLength(body: string): number {
+    const stripped = body.replace(/<[^>]*>/g, "");
+    const decoded = stripped.replace(/&nbsp;|&amp;|&lt;|&gt;/g, (m) => ENTITIES[m] ?? m);
+    return decoded.replace(/\s+/g, " ").trim().length;
+}
+
+export function isThinIssue(body: string, minBodyChars: number): boolean {
+    return minBodyChars > 0 && visibleBodyLength(body) < minBodyChars;
+}
+
+export function resolveMinBodyChars(config: Config, registry: Registry, projectKey: string): number {
+    return registry.projects[projectKey]?.inputQuality?.minBodyChars ?? config.defaults.inputQuality?.minBodyChars ?? 0;
+}