beflow 0.1.0

package/src/core/worktree.ts

@@ -0,0 +1,74 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { spawn } from "bun";
+
+export interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+
+export type Exec = (cmd: string, args: string[]) => Promise<ExecResult>;
+
+export function sanitizeKey(key: string): string {
+    return key
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+
+/** Expand a leading `~` / `~/` to the home directory; other paths pass through. */
+export function expandHome(path: string): string {
+    if (path === "~") {
+        return homedir();
+    }
+    if (path.startsWith("~/")) {
+        return join(homedir(), path.slice(2));
+    }
+    return path;
+}
+
+/** Resolve the worktree base dir: the configured value (~-expanded) or the default. */
+export function resolveWorktreeDir(configured?: string): string {
+    return configured !== undefined ? expandHome(configured) : join(homedir(), ".beflow", "worktrees");
+}
+
+export function worktreePath(baseDir: string, key: string): string {
+    return join(baseDir, sanitizeKey(key));
+}
+
+async function runGit(repoPath: string, args: string[], exec: Exec): Promise<ExecResult> {
+    const fullArgs = ["-C", repoPath, ...args];
+    const result = await exec("git", fullArgs);
+    if (result.code !== 0) {
+        throw new Error(
+            `beflow: git ${fullArgs.join(" ")} failed (exit ${String(result.code)}): ${result.stderr.trim()}`,
+        );
+    }
+    return result;
+}
+
+export async function createWorktree(repoPath: string, key: string, exec: Exec, baseDir: string): Promise<string> {
+    const wtPath = worktreePath(baseDir, key);
+    const branch = `beflow/${sanitizeKey(key)}`;
+    // -B (create-or-reset) rather than -b: createWorktree only runs on the
+    // Non-resume path, so any leftover beflow/<key> branch is a stale orphan
+    // From an interrupted run and must be reset, not collided with.
+    await runGit(repoPath, ["worktree", "add", "-B", branch, wtPath], exec);
+    return wtPath;
+}
+
+export async function removeWorktree(repoPath: string, wtPath: string, exec: Exec): Promise<void> {
+    await runGit(repoPath, ["worktree", "remove", wtPath, "--force"], exec);
+}
+
+export async function bunExec(cmd: string, args: string[]): Promise<ExecResult> {
+    const proc = spawn([cmd, ...args], { stderr: "pipe", stdout: "pipe" });
+    const [stdout, stderr, code] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+    ]);
+    return { code, stderr, stdout };
+}

package/src/core/writeback.ts

@@ -0,0 +1,88 @@
+import type { Report } from "../agent/report.ts";
+import type { Issue, JobKind } from "../model/types.ts";
+import type { Tracker } from "../trackers/tracker.ts";
+
+const BLOCKED_LABEL = "blocked";
+const FAILED_LABEL = "failed";
+const TRIAGED_LABEL = "triaged";
+const NEEDS_INPUT_STATE = "Needs Input";
+
+export interface WritebackResult {
+    movedTo?: string;
+    labeled?: string;
+}
+
+const DONE_STATES: Record<JobKind, string> = {
+    implement: "In Review",
+    spec: "Todo",
+    triage: "Backlog",
+};
+
+export function defaultDoneState(jobKind: JobKind): string {
+    return DONE_STATES[jobKind];
+}
+
+export function buildCommentBody(report: Report, telemetry?: string): string {
+    const parts = [report.summary];
+    if (report.notes !== undefined && report.notes.trim() !== "") {
+        parts.push(report.notes);
+    }
+    if (report.questions !== undefined && report.questions.length > 0) {
+        const list = report.questions.map((q) => `- ${q}`).join("\n");
+        parts.push(`Questions:\n${list}`);
+    }
+    if (telemetry !== undefined && telemetry.trim() !== "") {
+        parts.push(telemetry);
+    }
+    return parts.join("\n\n");
+}
+
+export async function applyReport(
+    tracker: Tracker,
+    issue: Issue,
+    report: Report,
+    jobKind: JobKind,
+    telemetry?: string,
+): Promise<WritebackResult> {
+    if (report.prUrl !== undefined && report.prUrl !== "") {
+        await tracker.linkPR(issue, report.prUrl);
+    }
+
+    await tracker.comment(issue, buildCommentBody(report, telemetry));
+
+    const result: WritebackResult = {};
+
+    switch (report.status) {
+        case "done": {
+            const target = defaultDoneState(jobKind);
+            await tracker.updateState(issue, target);
+            result.movedTo = target;
+            if (jobKind === "triage") {
+                await tracker.addProperty(issue, TRIAGED_LABEL);
+                result.labeled = TRIAGED_LABEL;
+            }
+            break;
+        }
+        case "needs_input": {
+            await tracker.updateState(issue, NEEDS_INPUT_STATE);
+            result.movedTo = NEEDS_INPUT_STATE;
+            break;
+        }
+        case "blocked": {
+            await tracker.addProperty(issue, BLOCKED_LABEL);
+            await tracker.updateState(issue, NEEDS_INPUT_STATE);
+            result.labeled = BLOCKED_LABEL;
+            result.movedTo = NEEDS_INPUT_STATE;
+            break;
+        }
+        case "failed": {
+            await tracker.addProperty(issue, FAILED_LABEL);
+            await tracker.updateState(issue, NEEDS_INPUT_STATE);
+            result.labeled = FAILED_LABEL;
+            result.movedTo = NEEDS_INPUT_STATE;
+            break;
+        }
+    }
+
+    return result;
+}

package/src/index.ts

@@ -0,0 +1,154 @@
+export type { StateGroup, RunMode, JobKind, Issue, IssueMeta, Resolved } from "./model/types.ts";
+
+export {
+    configSchema,
+    fileSchema,
+    registrySchema,
+    projectSchema,
+    agentConfigSchema,
+    type Config,
+    type ConfigFile,
+    type Registry,
+    type Project,
+    type AgentConfig,
+} from "./config/schema.ts";
+
+export { loadConfig, loadRegistry } from "./config/load.ts";
+
+export { parseIssueMeta } from "./resolve/metadata.ts";
+
+export { autoDetectJobKind } from "./resolve/jobkind.ts";
+
+export {
+    cascade,
+    resolve,
+    resolveAgent,
+    resolveRunMode,
+    resolveRepo,
+    resolveJobKind,
+    type ResolveInputs,
+} from "./resolve/precedence.ts";
+
+export type {
+    Tracker,
+    QueueFilter,
+    IntakeItem,
+    BoardTemplate,
+    EnsureBoardResult,
+    Comment,
+} from "./trackers/tracker.ts";
+
+export { BEFLOW_MARKER, withMarker, hasMarker, stripMarker } from "./trackers/marker.ts";
+
+export { PlaneTracker, createPlaneTracker, type PlaneTrackerOptions } from "./trackers/plane/adapter.ts";
+
+export { PlaneClient, type PlaneClientOptions } from "./trackers/plane/client.ts";
+
+export { LinearTracker, createLinearTracker, type LinearTrackerOptions } from "./trackers/linear/adapter.ts";
+
+export { LinearSdkGateway, type LinearGateway, type ListIssuesQuery } from "./trackers/linear/client.ts";
+
+export { createTracker } from "./trackers/factory.ts";
+
+export { extractReport, type Report, type ReportStatus } from "./agent/report.ts";
+
+export { parseAcpLine, reduceAcpStream, type AcpStreamResult, type AcpToolCall } from "./agent/events.ts";
+
+export {
+    AcpxDriver,
+    BunProcessRunner,
+    buildAcpxArgs,
+    buildCancelArgs,
+    type ProcessRunner,
+    type SpawnedProcess,
+} from "./agent/acpx.ts";
+
+export type { AgentDriver, AgentRunResult, RunOptions } from "./agent/driver.ts";
+
+export {
+    PROMPT_NAMES,
+    buildPromptContext,
+    defaultPromptResolveDeps,
+    loadPromptSet,
+    renderContract,
+    renderTask,
+    renderTemplate,
+    type PromptName,
+    type PromptResolveDeps,
+    type PromptSet,
+} from "./core/prompts.ts";
+
+export { applyReport, defaultDoneState, type WritebackResult } from "./core/writeback.ts";
+
+export {
+    createWorktree,
+    removeWorktree,
+    worktreePath,
+    sanitizeKey,
+    bunExec,
+    type Exec,
+    type ExecResult,
+} from "./core/worktree.ts";
+
+export {
+    resolveRun,
+    runIssue,
+    runOpen,
+    runSupervised,
+    defaultOpenIssue,
+    type ResolvedRun,
+    type RunIssueDeps,
+    type RunOpenDeps,
+    type RunResult,
+    type RunSupervisedDeps,
+    type SupervisedResult,
+    type OpenIssue,
+    type OpenLaunch,
+    type Logger,
+    type LaunchInteractive,
+    type InteractiveLaunch,
+    type AskOutcome,
+    type OutcomeAnswer,
+} from "./core/run.ts";
+
+export { beflowBoardTemplate } from "./core/template.ts";
+
+export {
+    assembleContinuation,
+    renderContinuation,
+    type AssembleOptions,
+    type ContinuationContext,
+} from "./core/continuation.ts";
+
+export {
+    loadRecord,
+    saveRecord,
+    deleteRecord,
+    resolveRunsDir,
+    systemClock,
+    nodeRunStoreFs,
+    reportSchema,
+    runRecordSchema,
+    type RunRecord,
+    type RunStoreFs,
+    type Clock,
+} from "./core/runstore.ts";
+
+export { setupProject, type SetupDeps } from "./core/setup.ts";
+
+export { queueView, type QueueRow, type QueueDeps, type QueueOptions } from "./core/queue.ts";
+
+export { acceptIntake, type AcceptDeps } from "./core/accept.ts";
+
+export { doctor, type DoctorCheck, type DoctorDeps, type CheckLevel } from "./core/doctor.ts";
+
+export {
+    watch,
+    watchTick,
+    type WatchDeps,
+    type WatchControl,
+    type WatchAction,
+    type WatchTickResult,
+} from "./core/watch.ts";
+
+export { runCli, defaultCliDeps, type CliDeps, type WatchRunner, type Ping } from "./cli.ts";

package/src/model/types.ts

@@ -0,0 +1,35 @@
+export type StateGroup = "backlog" | "unstarted" | "started" | "completed" | "cancelled";
+
+export type RunMode = "autonomous" | "supervised";
+
+export type JobKind = "triage" | "spec" | "implement";
+
+export interface IssueMeta {
+    agent?: string;
+    repo?: string;
+    runMode?: RunMode;
+    jobKind?: JobKind;
+}
+
+export interface Issue {
+    id: string;
+    key: string;
+    title: string;
+    body: string;
+    type?: string;
+    state: { name: string; group: StateGroup };
+    labels: string[];
+    areas: string[];
+    priority?: string;
+    parentId?: string;
+    meta: IssueMeta;
+    archived?: boolean;
+}
+
+export interface Resolved {
+    agent: string;
+    jobKind: JobKind;
+    repo: string;
+    repoPath: string;
+    runMode: RunMode;
+}

package/src/prompts/defaults/continuation.md

@@ -0,0 +1,9 @@
+This work item is returning to you for continuation — read the context below before continuing.
+
+Prior outcome: {{prior_report}}
+Open PR: {{pr_url}}
+
+New input since your last update:
+{{review_comments}}
+
+Address the input above. If a pull request is already open for this item, UPDATE it — do not open a new one. Then finish the work and emit your report block as usual.

package/src/prompts/defaults/implement.md

@@ -0,0 +1,13 @@
+You are in IMPLEMENT. Do the work in the repository at your working directory and ship it as a reviewable pull request.
+
+Work through it:
+
+- If your environment provides a to-do/task tool, use it: break the work into a checklist before you start and keep it updated as you go, marking each item done the moment it is, so no step is dropped or forgotten.
+- Read and obey that repo's CLAUDE.md — it carries the architecture, conventions, and Definition of Done. The repo holds the bar; follow its existing patterns for structure, naming, error handling, and tests.
+- Make the change, and back EVERY behavioral change with a test. New behavior without a test does not count as done.
+- Run the repo's own test and lint commands and paste their REAL output into the report `summary`/`notes`. Fabricating or paraphrasing results is forbidden — paste what actually ran.
+- ONLY when the gate is green — tests and lint pass on real output — and every item on your to-do list is marked complete (nothing left pending or in progress), commit, push, and open a pull request with `gh`, then put the PR URL in `prUrl`.
+
+If the task is ambiguous, or turns out far larger than described, STOP: do not guess and do not half-do it. Return status `needs_input` with the specific decisions you need in `questions`.
+
+When you are continuing a returning item (a continuation block precedes this task), read the prior PR and the new input, address it, and UPDATE the existing pull request — do not open a new one.

package/src/prompts/defaults/issue-enrich.md

@@ -0,0 +1,30 @@
+You are authoring a new work item by investigating the repository it belongs to.
+
+Investigate the repository READ-ONLY: only read and search files. Do NOT modify, create, or delete any file, and do NOT run commands that change the working tree — beflow-issue-enrich-readonly-author is a strictly observational pass.
+
+Here is what the human supplied through the new-issue form.
+
+Title: {{title}}
+
+Answers:
+{{answers}}
+
+Draft body assembled from the template:
+{{draft}}
+
+The desired body format for this kind of issue:
+{{format}}
+
+Use the answers, the draft, and the desired format together with what you learn from reading the codebase to write one complete, specific, actionable issue. Ground every claim in files you actually read; reference concrete paths and symbols where they help an implementer.
+
+Output ONLY a single fenced code block whose info string is exactly `beflow-issue`, containing one JSON object. Include at least `body`. Optionally include a refined `title`, and suggested `type`, `priority` (one of "urgent", "high", "medium", "low", "none"), and `labels` (an array of strings). Emit nothing after the block.
+
+```beflow-issue
+{
+  "body": "the full issue body in Markdown",
+  "title": "an optional refined title",
+  "type": "an optional suggested type",
+  "priority": "an optional suggested priority",
+  "labels": ["an optional suggested label"]
+}
+```

package/src/prompts/defaults/issues/bug.md

@@ -0,0 +1,35 @@
+---
+name: bug
+description: A reproducible defect — steps, expected vs actual
+type: Bug
+jobKind: implement
+priority: high
+enrich: false
+title: "{{summary}}"
+questions:
+  - { key: summary, label: One-line summary, type: text, required: true }
+  - { key: steps, label: Steps to reproduce, type: longtext, required: true }
+  - { key: expected, label: Expected behaviour, type: text }
+  - { key: actual, label: Actual behaviour, type: text }
+  - { key: severity, label: Severity, type: options, options: [low, medium, high, critical] }
+---
+
+## Summary
+
+{{summary}}
+
+## Steps to reproduce
+
+{{steps}}
+
+## Expected
+
+{{expected}}
+
+## Actual
+
+{{actual}}
+
+## Severity
+
+{{severity}}

package/src/prompts/defaults/issues/feature.md

@@ -0,0 +1,24 @@
+---
+name: feature
+description: A new capability — motivation + acceptance criteria
+type: Feature
+jobKind: spec
+enrich: false
+title: "{{summary}}"
+questions:
+  - { key: summary, label: One-line summary, type: text, required: true }
+  - { key: motivation, label: Why — problem / value, type: longtext, required: true }
+  - { key: criteria, label: Acceptance criteria, type: longtext }
+---
+
+## Summary
+
+{{summary}}
+
+## Motivation
+
+{{motivation}}
+
+## Acceptance criteria
+
+{{criteria}}

package/src/prompts/defaults/issues/generic.md

@@ -0,0 +1,16 @@
+---
+name: generic
+description: A blank issue — summary plus free-form context
+enrich: false
+questions:
+  - { key: summary, label: One-line summary, type: text, required: true }
+  - { key: context, label: Context / details, type: longtext }
+---
+
+## Summary
+
+{{summary}}
+
+## Context
+
+{{context}}

package/src/prompts/defaults/issues/spike.md

@@ -0,0 +1,24 @@
+---
+name: spike
+description: A time-boxed investigation — a question to answer
+type: Spike
+jobKind: triage
+enrich: false
+title: "{{summary}}"
+questions:
+  - { key: summary, label: Question / goal, type: text, required: true }
+  - { key: context, label: Context / background, type: longtext }
+  - { key: outcome, label: Expected outcome / deliverable, type: text }
+---
+
+## Question
+
+{{summary}}
+
+## Context
+
+{{context}}
+
+## Expected outcome
+
+{{outcome}}

package/src/prompts/defaults/report.md

@@ -0,0 +1,20 @@
+End your FINAL message with a fenced code block whose info string is exactly `beflow-report`, containing a single JSON object:
+
+```beflow-report
+{
+  "status": "done" | "needs_input" | "blocked" | "failed",
+  "summary": "one or two sentences on what you did",
+  "prUrl": "https://… (only when you opened a PR)",
+  "questions": ["…"],
+  "notes": "extra detail (required when status is failed)"
+}
+```
+
+Status meanings:
+
+- "done" — the work is complete; if it produced code, a PR is open and its URL is in `prUrl`.
+- "needs_input" — you cannot proceed without a human decision; put the exact decisions you need in `questions`.
+- "blocked" — you are waiting on an external dependency (another party, an upstream change, access you don't have); explain in `notes`.
+- "failed" — you could not complete the work; explain why in `notes`.
+
+Emit exactly one such block, as the last thing in your final message.

package/src/prompts/defaults/review.md

@@ -0,0 +1,34 @@
+You are in REVIEW. A pull request has been opened for work item {{key}} ("{{title}}") in the repository at your working directory. Read the PR and report what you find — you are a REVIEWER, not an author.
+
+Work through it:
+
+- Inspect the changes with `gh pr diff` in the current working directory. Read the surrounding code as needed to judge each change in context.
+- Focus on correctness and bugs, security issues, missing or weak test coverage, and anything that would block a merge. Be specific: point at the file and, where you can, the line.
+- This is a {{type}} work item; weigh the changes against what it set out to do.
+
+You must NOT merge, push, commit, or change anything — no `gh pr merge`, no edits to the working tree, no board changes. Your only output is the review block below.
+
+End your FINAL message with a fenced code block whose info string is exactly `beflow-review`, containing a single JSON object:
+
+```beflow-review
+{
+  "summary": "one or two sentences on the overall state of the PR",
+  "findings": [
+    {
+      "severity": "blocker" | "major" | "minor" | "nit",
+      "comment": "what is wrong and what to do about it",
+      "file": "path/to/file (optional)",
+      "line": 0
+    }
+  ]
+}
+```
+
+Severity meanings:
+
+- "blocker" — must be fixed before merge (correctness, security, data loss).
+- "major" — a real problem that should be addressed.
+- "minor" — a small issue worth fixing.
+- "nit" — a stylistic or cosmetic suggestion.
+
+Emit exactly one such block, as the last thing in your final message. An empty `findings` array is valid when the PR looks clean.

package/src/prompts/defaults/spec.md

@@ -0,0 +1,11 @@
+You are in SPEC. Produce an implementation plan for a structured item — detailed enough that an implementer can execute it and a human can approve or redirect it. This is design ONLY — do NOT implement anything and do NOT open a PR.
+
+Work through it:
+
+- Explore the codebase first: the data model, the surface this touches, existing patterns to follow, and the test conventions. The more you understand, the sharper the plan.
+- Separate the work into what is new, what is modified, and what is affected downstream.
+- Choose ONE opinionated approach. If there are real alternatives, weigh them briefly, then commit to one and say why.
+- List the specific files and functions to touch, in dependency order.
+- Define acceptance criteria, and call out migration, rollout, and risk: can it ship behind a flag, is the migration reversible, what breaks if a deploy half-lands.
+
+Report status `done` when the plan is ready for review; report `needs_input` when a human decision is required first. beflow decides where the item moves.

package/src/prompts/defaults/task.md

@@ -0,0 +1,6 @@
+Work item: {{key}}
+Title: {{title}}
+Type: {{type}}
+
+Description:
+{{description}}

package/src/prompts/defaults/triage.md

@@ -0,0 +1,11 @@
+You are in TRIAGE. Take a raw, unstructured item and turn it into a crisp, structured one a human can act on at a glance. This is investigation and organization ONLY — do NOT write code, do NOT open a PR.
+
+Work through it:
+
+- Restate the real problem in one line. Strip the noise; say what the customer or author actually wants.
+- For a bug: locate the relevant code, establish a concrete reproduction (steps, or note that you could not reproduce), and name the likely root cause down to file and line.
+- For a feature: identify the affected areas of the code (data model, surface, UI), note what already exists to build on, and give a rough effort and risk read.
+- Write tight, testable acceptance criteria — the conditions under which this is "done".
+- Flag open questions, but only genuine human decisions (scope, priority, business calls); resolve the technical ones yourself.
+
+Decide your business questions yourself only where they are technical; surface the rest. Report status `done` when triage is complete and the item is ready to schedule; report `needs_input` when a human decision is required first. beflow decides where the item moves.

package/src/prompts/text-modules.d.ts

@@ -0,0 +1,4 @@
+declare module "*.md" {
+    const content: string;
+    export default content;
+}

package/src/resolve/jobkind.ts

@@ -0,0 +1,11 @@
+import type { JobKind, StateGroup } from "../model/types.ts";
+
+export function autoDetectJobKind(type: string | undefined, stateGroup: StateGroup): JobKind {
+    if (type === "Spike") {
+        return "triage";
+    }
+    if (stateGroup === "backlog") {
+        return "spec";
+    }
+    return "implement";
+}