beflow 0.1.0

package/src/core/runstore.ts

@@ -0,0 +1,144 @@
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { z } from "zod";
+
+import { expandHome, sanitizeKey } from "./worktree.ts";
+
+export const reportSchema = z.object({
+    notes: z.string().optional(),
+    prUrl: z.string().optional(),
+    questions: z.array(z.string()).optional(),
+    status: z.enum(["done", "needs_input", "blocked", "failed"]),
+    summary: z.string(),
+});
+
+export const usageSchema = z.object({
+    cacheReadTokens: z.number().optional(),
+    cacheWriteTokens: z.number().optional(),
+    costUsd: z.number().optional(),
+    inputTokens: z.number().optional(),
+    outputTokens: z.number().optional(),
+    totalTokens: z.number().optional(),
+});
+
+export const runRecordSchema = z.object({
+    agent: z.string(),
+    attempts: z.number().optional(),
+    branch: z.string().optional(),
+    ciAttempts: z.number().optional(),
+    ciReworkSha: z.string().optional(),
+    cwd: z.string(),
+    escalatedAt: z.string().optional(),
+    heldReason: z.enum(["decision", "quarantine"]).optional(),
+    jobKind: z.enum(["triage", "spec", "implement"]),
+    key: z.string(),
+    prUrl: z.string().optional(),
+    repoPath: z.string().optional(),
+    report: reportSchema.optional(),
+    reviewedSha: z.string().optional(),
+    runMode: z.enum(["autonomous", "supervised"]),
+    sessionName: z.string(),
+    status: z.enum(["in_progress", "done", "needs_input", "blocked", "failed"]),
+    tracker: z.enum(["plane", "linear"]).optional(),
+    updatedAt: z.string(),
+    usage: usageSchema.optional(),
+});
+
+export type RunRecord = z.infer<typeof runRecordSchema>;
+
+/** Resolve the run-record base dir: the configured value (~-expanded) or the default. */
+export function resolveRunsDir(configured?: string): string {
+    return configured !== undefined ? expandHome(configured) : join(homedir(), ".beflow", "runs");
+}
+
+function recordPath(runsDir: string, key: string): string {
+    return join(runsDir, `${sanitizeKey(key)}.json`);
+}
+
+export interface RunStoreFs {
+    read(path: string): string | null;
+    write(path: string, data: string): void;
+    remove(path: string): void;
+    list(dir: string): string[];
+}
+
+export const nodeRunStoreFs: RunStoreFs = {
+    list(dir) {
+        try {
+            return readdirSync(dir);
+        } catch {
+            return [];
+        }
+    },
+    read(path) {
+        try {
+            return readFileSync(path, "utf8");
+        } catch {
+            return null;
+        }
+    },
+    remove(path) {
+        rmSync(path, { force: true });
+    },
+    write(path, data) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, data, "utf8");
+    },
+};
+
+export type Clock = () => string;
+
+export function systemClock(): string {
+    return new Date().toISOString();
+}
+
+export function loadRecord(runsDir: string, key: string, fs: RunStoreFs = nodeRunStoreFs): RunRecord | null {
+    const raw = fs.read(recordPath(runsDir, key));
+    if (raw === null) {
+        return null;
+    }
+
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        return null;
+    }
+
+    const result = runRecordSchema.safeParse(parsed);
+    return result.success ? result.data : null;
+}
+
+export function listRecords(runsDir: string, fs: RunStoreFs = nodeRunStoreFs): RunRecord[] {
+    const records: RunRecord[] = [];
+    for (const name of fs.list(runsDir)) {
+        if (!name.endsWith(".json")) {
+            continue;
+        }
+        const raw = fs.read(join(runsDir, name));
+        if (raw === null) {
+            continue;
+        }
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(raw);
+        } catch {
+            continue;
+        }
+        const result = runRecordSchema.safeParse(parsed);
+        if (result.success) {
+            records.push(result.data);
+        }
+    }
+    return records;
+}
+
+export function saveRecord(runsDir: string, record: RunRecord, fs: RunStoreFs = nodeRunStoreFs): void {
+    fs.write(recordPath(runsDir, record.key), `${JSON.stringify(record, null, 2)}\n`);
+}
+
+export function deleteRecord(runsDir: string, key: string, fs: RunStoreFs = nodeRunStoreFs): void {
+    fs.remove(recordPath(runsDir, key));
+}

package/src/core/runsview.ts

@@ -0,0 +1,111 @@
+import type { Usage } from "../agent/events.ts";
+import type { Config, Registry } from "../config/schema.ts";
+import type { RunRecord } from "./runstore.ts";
+
+// Project-over-default-over-false resolution of the per-project telemetry-in-comment
+// Toggle. Returns false when neither layer opts in.
+export function resolveTelemetryInComment(config: Config, registry: Registry, projectKey: string): boolean {
+    return registry.projects[projectKey]?.telemetry?.inComment ?? config.defaults.telemetry?.inComment ?? false;
+}
+
+// The token count beflow reports: prefer an explicit total, else derive it from
+// Input+output when both are present. Returns undefined when neither is derivable.
+export function totalTokensOf(usage: Usage): number | undefined {
+    if (usage.totalTokens !== undefined) {
+        return usage.totalTokens;
+    }
+    if (usage.inputTokens !== undefined && usage.outputTokens !== undefined) {
+        return usage.inputTokens + usage.outputTokens;
+    }
+    return undefined;
+}
+
+// Compact one-line telemetry suffix for the writeback comment. Degrade-safe:
+// Returns undefined when usage carries neither a token count nor a cost, so the
+// Caller writes no line. The token segment is omitted when no count is derivable;
+// The cost segment is appended only when the event reported a cost.
+export function formatTelemetryLine(
+    usage: Usage,
+    model: string | undefined,
+    attempts: number | undefined,
+): string | undefined {
+    const tokens = totalTokensOf(usage);
+    if (tokens === undefined && usage.costUsd === undefined) {
+        return undefined;
+    }
+    const segments: string[] = [];
+    if (tokens !== undefined) {
+        segments.push(`${String(tokens)} tok`);
+    }
+    segments.push(`model ${model ?? "default"}`);
+    segments.push(`attempt ${attempts !== undefined ? String(attempts) : "n"}`);
+    let line = `beflow: ${segments.join(" · ")}`;
+    if (usage.costUsd !== undefined) {
+        line += ` · ~$${usage.costUsd.toFixed(4)}`;
+    }
+    return line;
+}
+
+function tokensLabel(usage: Usage | undefined): string {
+    if (usage === undefined) {
+        return "-";
+    }
+    const tokens = totalTokensOf(usage);
+    return tokens !== undefined ? `${String(tokens)} tok` : "-";
+}
+
+// One compact line per record for the list view: key, status, attempts, tokens.
+export function formatRunListLine(record: RunRecord): string {
+    const attempts = record.attempts ?? 0;
+    return `${record.key}  ${record.status}  attempts=${String(attempts)}  ${tokensLabel(record.usage)}`;
+}
+
+export function formatRunList(records: RunRecord[]): string[] {
+    if (records.length === 0) {
+        return ["beflow: no run records"];
+    }
+    return [...records].sort((a, b) => a.key.localeCompare(b.key)).map(formatRunListLine);
+}
+
+// Multi-line detail view for a single record. `model` is resolved by the caller
+// (it lives in config, not the record) and may be undefined.
+export function formatRunDetail(record: RunRecord, model: string | undefined): string[] {
+    const lines: string[] = [
+        `key: ${record.key}`,
+        `status: ${record.status}`,
+        `attempts: ${String(record.attempts ?? 0)}`,
+        `agent: ${record.agent}`,
+        `model: ${model ?? "default"}`,
+        `jobKind: ${record.jobKind}`,
+        `runMode: ${record.runMode}`,
+    ];
+    if (record.usage !== undefined) {
+        const tokens = totalTokensOf(record.usage);
+        if (tokens !== undefined) {
+            lines.push(`tokens: ${String(tokens)}`);
+        }
+        if (record.usage.inputTokens !== undefined) {
+            lines.push(`  input: ${String(record.usage.inputTokens)}`);
+        }
+        if (record.usage.outputTokens !== undefined) {
+            lines.push(`  output: ${String(record.usage.outputTokens)}`);
+        }
+        if (record.usage.cacheReadTokens !== undefined) {
+            lines.push(`  cacheRead: ${String(record.usage.cacheReadTokens)}`);
+        }
+        if (record.usage.cacheWriteTokens !== undefined) {
+            lines.push(`  cacheWrite: ${String(record.usage.cacheWriteTokens)}`);
+        }
+        if (record.usage.costUsd !== undefined) {
+            lines.push(`cost: ~$${record.usage.costUsd.toFixed(4)}`);
+        }
+    }
+    if (record.prUrl !== undefined) {
+        lines.push(`prUrl: ${record.prUrl}`);
+    }
+    if (record.reviewedSha !== undefined) {
+        lines.push(`reviewedSha: ${record.reviewedSha}`);
+    }
+    lines.push(`updatedAt: ${record.updatedAt}`);
+    return lines;
+}

package/src/core/setup.ts

@@ -0,0 +1,203 @@
+import { cancel, confirm, isCancel, select, text } from "@clack/prompts";
+
+import { addProject } from "../config/persist.ts";
+import type { Project, Registry } from "../config/schema.ts";
+import type {
+    EnsureBoardResult,
+    ModuleChange,
+    ModuleChangeAction,
+    ProjectCreateSpec,
+    ResolveModuleChanges,
+    Tracker,
+} from "../trackers/tracker.ts";
+import type { Logger } from "./run.ts";
+import { beflowBoardTemplate } from "./template.ts";
+
+// The interactive create boundary: given the missing key + active tracker, gather
+// a project-create spec plus the config entry to write back. Injected so the
+// orchestration core stays unit-testable without a TTY.
+export type AskProjectSpec = (ctx: {
+    key: string;
+    tracker: string;
+}) => Promise<{ spec: ProjectCreateSpec; entry: Project }>;
+
+export interface SetupDeps {
+    tracker: Tracker;
+    trackerName: string;
+    registry: Registry;
+    agents: string[];
+    prune?: boolean;
+    log?: Logger;
+    resolveModuleChanges?: ResolveModuleChanges;
+    askProjectSpec?: AskProjectSpec;
+    persist?: (dir: string, key: string, project: Project) => void;
+    dir?: string;
+}
+
+async function defaultResolveModuleChanges(change: ModuleChange): Promise<Record<string, ModuleChangeAction>> {
+    const out: Record<string, ModuleChangeAction> = {};
+    const available = [...change.added];
+    for (const orphan of change.removed) {
+        // Config is the source of truth: a module that is no longer in config was
+        // Either renamed to one of the new modules or removed. "Keep" is not offered —
+        // It would deliberately re-create the drift beflow exists to reconcile. Ctrl+C
+        // Bails the whole reconcile (nothing changes).
+        const options = [
+            ...available.map((name) => ({
+                hint: "keep the module and its issues",
+                label: `Rename → ${name}`,
+                value: `rename:${name}`,
+            })),
+            { hint: "delete; its issues become module-less", label: "Remove it", value: "remove" },
+        ];
+        const choice = await select({ message: `Module "${orphan}" is no longer in config — what is it?`, options });
+        if (isCancel(choice)) {
+            cancel(`beflow: module reconcile cancelled — nothing changed for "${orphan}"`);
+            throw new Error("beflow: module reconcile cancelled");
+        }
+        if (typeof choice === "string" && choice.startsWith("rename:")) {
+            const to = choice.slice("rename:".length);
+            out[orphan] = { kind: "rename", to };
+            const idx = available.indexOf(to);
+            if (idx !== -1) {
+                available.splice(idx, 1);
+            }
+        } else {
+            out[orphan] = { kind: "remove" };
+        }
+    }
+    return out;
+}
+
+// Shared cancel path for the create prompts: a Ctrl-C aborts cleanly so no
+// project is created or written back. Like the defaults above, not unit-tested.
+function cancelledCreate(): never {
+    cancel("Cancelled.");
+    throw new Error("beflow: project creation cancelled");
+}
+
+async function askText(message: string, opts?: { defaultValue?: string }): Promise<string> {
+    const value = await text({
+        message,
+        validate: (v: string | undefined): string | undefined => ((v ?? "").trim() === "" ? "Required" : undefined),
+        ...(opts?.defaultValue !== undefined
+            ? { defaultValue: opts.defaultValue, placeholder: opts.defaultValue }
+            : {}),
+    });
+    if (isCancel(value)) {
+        cancelledCreate();
+    }
+    return value.trim();
+}
+
+async function askYes(message: string): Promise<boolean> {
+    const value = await confirm({ message });
+    if (isCancel(value)) {
+        cancelledCreate();
+    }
+    return value;
+}
+
+// The clack-backed default asker: prompts for the project name + identifier, the
+// repo map (default repo + extras), and optional module→repo entries, then
+// returns the create spec plus the config entry (the orchestrator fills
+// plane_project_id after the tracker create).
+export async function defaultAskProjectSpec(ctx: {
+    key: string;
+    tracker: string;
+}): Promise<{ spec: ProjectCreateSpec; entry: Project }> {
+    const name = await askText("Project name");
+    const identifier = await askText("Project identifier", { defaultValue: ctx.key });
+    const root = await askText("Project root (absolute path)");
+
+    const defaultRepoKey = await askText("Default repo key");
+    const repos: Record<string, string> = {
+        [defaultRepoKey]: await askText(`Absolute path for repo "${defaultRepoKey}"`),
+    };
+    while (await askYes("Add another repo?")) {
+        const repoKey = await askText("Repo key");
+        repos[repoKey] = await askText(`Absolute path for repo "${repoKey}"`);
+    }
+
+    const repoKeys = Object.keys(repos);
+    const moduleRepoMap: Record<string, string> = {};
+    while (await askYes("Add a module → repo mapping?")) {
+        const moduleName = await askText("Module name");
+        const repoKey = await text({
+            message: `Repo key for module "${moduleName}"`,
+            validate: (v: string | undefined): string | undefined => {
+                const trimmed = (v ?? "").trim();
+                if (trimmed === "") {
+                    return "Required";
+                }
+                return repoKeys.includes(trimmed) ? undefined : `Unknown repo key — one of: ${repoKeys.join(", ")}`;
+            },
+        });
+        if (isCancel(repoKey)) {
+            cancelledCreate();
+        }
+        moduleRepoMap[moduleName] = repoKey.trim();
+    }
+
+    return {
+        entry: {
+            default_repo: defaultRepoKey,
+            module_repo_map: moduleRepoMap,
+            name,
+            repos,
+            root,
+        },
+        spec: { identifier, name },
+    };
+}
+
+export async function setupProject(projectKey: string, deps: SetupDeps): Promise<EnsureBoardResult> {
+    const log =
+        deps.log ??
+        ((): void => {
+            /* no-op: logging disabled */
+        });
+    if (deps.registry.projects[projectKey] === undefined) {
+        const ask = deps.askProjectSpec ?? (process.stdin.isTTY ? defaultAskProjectSpec : undefined);
+        if (ask === undefined) {
+            throw new Error(
+                `beflow: project "${projectKey}" is not in config.json; run setup in an interactive terminal to create it`,
+            );
+        }
+        const { entry, spec } = await ask({ key: projectKey, tracker: deps.trackerName });
+        const { trackerProjectId } = await deps.tracker.createProject(spec);
+        if (deps.trackerName === "plane" && trackerProjectId !== undefined) {
+            entry.plane_project_id = trackerProjectId;
+        }
+        (deps.persist ?? addProject)(deps.dir ?? process.cwd(), projectKey, entry);
+        // The tracker holds a reference to this same registry object; mutate it in
+        // place so ensureBoard below sees the freshly created project.
+        deps.registry.projects[projectKey] = entry;
+        log(`beflow: created project ${projectKey} (${spec.identifier}) in ${deps.trackerName}`);
+    }
+
+    const template = beflowBoardTemplate(deps.registry, projectKey, deps.agents);
+    const resolveModuleChanges =
+        deps.resolveModuleChanges ?? (process.stdin.isTTY ? defaultResolveModuleChanges : undefined);
+    const result = await deps.tracker.ensureBoard(projectKey, template, {
+        prune: deps.prune,
+        ...(resolveModuleChanges !== undefined ? { resolveModuleChanges } : {}),
+    });
+
+    log(
+        `beflow: setup ${projectKey} — ${String(result.created.length)} created, ${String(result.updated.length)} updated, ${String(result.skipped.length)} skipped, ${String(result.pruned.length)} pruned`,
+    );
+    for (const warning of result.warnings) {
+        log(`beflow: warning: ${warning}`);
+    }
+
+    if (deps.prune !== true && result.orphans.length > 0) {
+        for (const orphan of result.orphans) {
+            log(
+                `beflow: orphan ${orphan} exists in Plane but not in config; run 'beflow update ${projectKey} --prune' to remove it`,
+            );
+        }
+    }
+
+    return result;
+}

package/src/core/sla.ts

@@ -0,0 +1,39 @@
+import type { Config, Registry } from "../config/schema.ts";
+import type { RunRecord } from "./runstore.ts";
+
+export interface SlaThresholds {
+    inReviewMinutes?: number;
+    needsInputMinutes?: number;
+}
+
+export function resolveSla(config: Config, registry: Registry, projectKey: string): SlaThresholds {
+    const projectSla = registry.projects[projectKey]?.sla;
+    const globalSla = config.defaults.sla;
+    const inReviewMinutes = projectSla?.inReviewMinutes ?? globalSla?.inReviewMinutes;
+    const needsInputMinutes = projectSla?.needsInputMinutes ?? globalSla?.needsInputMinutes;
+    return {
+        ...(inReviewMinutes !== undefined ? { inReviewMinutes } : {}),
+        ...(needsInputMinutes !== undefined ? { needsInputMinutes } : {}),
+    };
+}
+
+export function ageMinutes(nowIso: string, sinceIso: string): number {
+    return (Date.parse(nowIso) - Date.parse(sinceIso)) / 60000;
+}
+
+export function formatAge(minutes: number): string {
+    if (minutes < 60) {
+        return `${String(Math.round(minutes))}m`;
+    }
+    if (minutes < 1440) {
+        return `${String(Math.round(minutes / 60))}h`;
+    }
+    return `${String(Math.round(minutes / 1440))}d`;
+}
+
+export function shouldRemind(nowIso: string, record: RunRecord, thresholdMinutes: number): boolean {
+    if (ageMinutes(nowIso, record.updatedAt) < thresholdMinutes) {
+        return false;
+    }
+    return record.escalatedAt === undefined || ageMinutes(nowIso, record.escalatedAt) >= thresholdMinutes;
+}

package/src/core/template.ts

@@ -0,0 +1,65 @@
+import type { Registry } from "../config/schema.ts";
+import type { BoardTemplate } from "../trackers/tracker.ts";
+
+const STATES: BoardTemplate["states"] = [
+    { color: "#60646C", group: "backlog", name: "Backlog", sequence: 15000 },
+    { color: "#60646C", group: "unstarted", name: "Todo", sequence: 25000 },
+    { color: "#F59E0B", group: "started", name: "In Progress", sequence: 35000 },
+    { color: "#EC4899", group: "started", name: "Needs Input", sequence: 37500 },
+    { color: "#3B82F6", group: "started", name: "In Review", sequence: 40000 },
+    { color: "#46A758", group: "completed", name: "Done", sequence: 45000 },
+    { color: "#9AA4BC", group: "cancelled", name: "Cancelled", sequence: 55000 },
+];
+
+const TYPES: BoardTemplate["types"] = [
+    {
+        description: "A defect with a known or to-be-found root cause. Ready to fix.",
+        name: "Bug",
+    },
+    {
+        description: "New capability. May start as an idea, gets specced before build.",
+        name: "Feature",
+    },
+    {
+        description: "Refactor, dependency update, maintenance. No new behavior.",
+        name: "Chore",
+    },
+    {
+        description: "Time-boxed investigation. Output is findings/decision, not shipped code.",
+        name: "Spike",
+    },
+];
+
+// Functional/manual labels plus the runMode "picker" labels. The agent:<name>
+// Pickers are appended per-project from the configured agent list.
+const LABELS: BoardTemplate["labels"] = [
+    { color: "#EF4444", name: "blocked" },
+    { color: "#B91C1C", name: "failed" },
+    { color: "#6B7280", name: "quarantined" },
+    { color: "#14B8A6", name: "triaged" },
+    { color: "#F59E0B", name: "needs-decision" },
+    { color: "#8B5CF6", name: "customer-reported" },
+    { color: "#F97316", name: "changes-requested" },
+    { color: "#F59E0B", name: "run:autonomous" },
+    { color: "#3B82F6", name: "run:supervised" },
+    { color: "#A78BFA", name: "jobkind:triage" },
+    { color: "#A78BFA", name: "jobkind:spec" },
+    { color: "#A78BFA", name: "jobkind:implement" },
+];
+
+export function beflowBoardTemplate(registry: Registry, projectKey: string, agents: string[]): BoardTemplate {
+    const project = registry.projects[projectKey];
+    if (project === undefined) {
+        const known = Object.keys(registry.projects).join(", ");
+        throw new Error(`beflow: unknown project key "${projectKey}" (known: ${known})`);
+    }
+
+    const modules: BoardTemplate["modules"] = Object.keys(project.module_repo_map).map((name) => ({ name }));
+
+    const labels: BoardTemplate["labels"] = [
+        ...LABELS,
+        ...agents.map((name) => ({ color: "#10B981", name: `agent:${name}` })),
+    ];
+
+    return { labels, modules, states: STATES, types: TYPES };
+}