beflow 0.1.0

package/src/core/newissue.ts

@@ -0,0 +1,343 @@
+import { cancel, confirm, isCancel, multiselect, note, select, text } from "@clack/prompts";
+
+import type { AgentDriver } from "../agent/driver.ts";
+import { extractIssueFence, type IssueFence } from "../agent/issuefence.ts";
+import type { Issue } from "../model/types.ts";
+import type { IssueDraft, Tracker } from "../trackers/tracker.ts";
+import {
+    listIssueTemplates,
+    loadIssueTemplate,
+    renderIssueBody,
+    type IssueTemplate,
+    type IssueTemplateResolveDeps,
+    type Question,
+} from "./issuetemplate.ts";
+import { renderTemplate } from "./prompts.ts";
+import type { Logger } from "./run.ts";
+
+// Injected IO boundaries; the clack-backed defaults below are the TTY edge, so the
+// orchestration core stays fully unit-testable without a TTY.
+export type AskTemplate = (templates: { name: string; description: string }[]) => Promise<string>;
+export type AskQuestions = (questions: Question[]) => Promise<Record<string, string>>;
+export type AskConfirm = (preview: string) => Promise<boolean>;
+
+// The agent-enrich boundary: given the form answers + the seed draft, an agent
+// investigates the repo READ-ONLY and returns a complete issue (or null to fall
+// back to the form draft). Injected so the core stays unit-testable.
+export interface EnrichInput {
+    template: IssueTemplate;
+    answers: Record<string, string>;
+    seedTitle: string;
+    seedBody: string;
+}
+export type EnrichIssue = (input: EnrichInput) => Promise<IssueFence | null>;
+
+function formatAnswers(answers: Record<string, string>): string {
+    return Object.entries(answers)
+        .map(([key, value]) => `${key}: ${value}`)
+        .join("\n");
+}
+
+// Builds the default agent-backed enrich function: it runs the authoring agent
+// one-shot and READ-ONLY (acpx `exec` + `--approve-reads` +
+// `--non-interactive-permissions deny`) in the project's repo, then extracts the
+// `beflow-issue` block. Any driver error degrades to null so enrich never crashes
+// issue creation.
+export function defaultEnrichIssue(opts: {
+    driver: AgentDriver;
+    resolveAcp: (agent: string) => string;
+    enrichPrompt: string;
+    repoPath: string;
+    defaultAgent: string;
+    log?: Logger;
+}): EnrichIssue {
+    return async (input: EnrichInput): Promise<IssueFence | null> => {
+        const agent = input.template.agent ?? opts.defaultAgent;
+        const acpCommand = opts.resolveAcp(agent);
+        const task = renderTemplate("issue-enrich", opts.enrichPrompt, {
+            answers: formatAnswers(input.answers),
+            draft: input.seedBody,
+            format: input.template.body,
+            title: input.seedTitle,
+        });
+        try {
+            const result = await opts.driver.run({
+                acpCommand,
+                cwd: opts.repoPath,
+                nonInteractive: "deny",
+                oneShot: true,
+                runMode: "supervised",
+                sessionKey: "beflow-new",
+                task,
+            });
+            return extractIssueFence(result.stream.assistantText);
+        } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            opts.log?.(`beflow: enrich agent failed (${msg}); using the form draft`);
+            return null;
+        }
+    };
+}
+
+// Shared cancel path for every clack prompt: a Ctrl-C aborts cleanly so nothing is
+// created. Like defaultAskOutcome in run.ts, these defaults are NOT unit-tested.
+function cancelled(): never {
+    cancel("Cancelled.");
+    throw new Error("beflow: issue creation cancelled");
+}
+
+export async function defaultAskTemplate(templates: { name: string; description: string }[]): Promise<string> {
+    const choice = await select({
+        message: "Pick an issue template",
+        options: templates.map((t) => ({ hint: t.description, label: t.name, value: t.name })),
+    });
+    if (isCancel(choice)) {
+        cancelled();
+    }
+    return choice;
+}
+
+export async function defaultAskQuestions(questions: Question[]): Promise<Record<string, string>> {
+    const answers: Record<string, string> = {};
+    for (const question of questions) {
+        const { required } = question;
+        switch (question.type) {
+            case "text": {
+                const value = await text({
+                    message: question.label,
+                    ...(required
+                        ? {
+                              validate: (v: string | undefined): string | undefined =>
+                                  (v ?? "").trim() === "" ? "Required" : undefined,
+                          }
+                        : {}),
+                });
+                if (isCancel(value)) {
+                    cancelled();
+                }
+                answers[question.key] = value;
+                break;
+            }
+            case "longtext": {
+                // clack has no native multiline input, so longtext is a single-line
+                // text prompt; Enter submits. Multi-paragraph bodies aren't supported
+                // here — author them in a template file instead.
+                const value = await text({
+                    message: question.label,
+                    placeholder: "single line — Enter submits",
+                    ...(required
+                        ? {
+                              validate: (v: string | undefined): string | undefined =>
+                                  (v ?? "").trim() === "" ? "Required" : undefined,
+                          }
+                        : {}),
+                });
+                if (isCancel(value)) {
+                    cancelled();
+                }
+                answers[question.key] = value;
+                break;
+            }
+            case "bool": {
+                const value = await confirm({ message: question.label });
+                if (isCancel(value)) {
+                    cancelled();
+                }
+                answers[question.key] = value ? "Yes" : "No";
+                break;
+            }
+            case "number": {
+                const value = await text({
+                    message: question.label,
+                    validate: (v: string | undefined): string | undefined => {
+                        const trimmed = (v ?? "").trim();
+                        if (trimmed !== "" && Number.isNaN(Number(trimmed))) {
+                            return "Must be a number";
+                        }
+                        return required && trimmed === "" ? "Required" : undefined;
+                    },
+                });
+                if (isCancel(value)) {
+                    cancelled();
+                }
+                answers[question.key] = value.trim();
+                break;
+            }
+            case "options": {
+                // The schema guarantees options is non-empty for this type.
+                const value = await select({
+                    message: question.label,
+                    options: (question.options ?? []).map((o) => ({ label: o, value: o })),
+                });
+                if (isCancel(value)) {
+                    cancelled();
+                }
+                answers[question.key] = value;
+                break;
+            }
+            case "multiselect": {
+                const value = await multiselect({
+                    message: question.label,
+                    options: (question.options ?? []).map((o) => ({ label: o, value: o })),
+                    required,
+                });
+                if (isCancel(value)) {
+                    cancelled();
+                }
+                answers[question.key] = value.join(", ");
+                break;
+            }
+        }
+    }
+    return answers;
+}
+
+export async function defaultAskConfirm(preview: string): Promise<boolean> {
+    note(preview, "New issue");
+    const ok = await confirm({ message: "Create this work item?" });
+    if (isCancel(ok)) {
+        cancelled();
+    }
+    return ok;
+}
+
+export interface NewIssueDeps {
+    tracker: Tracker;
+    templateDeps: IssueTemplateResolveDeps;
+    askTemplate: AskTemplate;
+    askQuestions: AskQuestions;
+    askConfirm: AskConfirm;
+    enrich?: EnrichIssue;
+    log?: Logger;
+    defaultState?: string;
+}
+
+const DEFAULT_STATE = "Backlog";
+
+function fillAnswers(questions: Question[], raw: Record<string, string>): Record<string, string> {
+    const answers: Record<string, string> = {};
+    for (const q of questions) {
+        answers[q.key] = raw[q.key] ?? "";
+    }
+    return answers;
+}
+
+function deriveTitle(template: IssueTemplate, answers: Record<string, string>): string {
+    const raw =
+        template.title !== undefined
+            ? renderTemplate(`issue:${template.name}:title`, template.title, answers)
+            : (answers.title ?? answers.summary ?? answers[template.questions[0]?.key ?? ""] ?? "");
+    const title = raw.trim();
+    if (title === "") {
+        throw new Error(
+            `beflow: issue template "${template.name}" produced an empty title — add a "title" pattern or a "title"/"summary" question`,
+        );
+    }
+    return title;
+}
+
+function mapLabels(template: IssueTemplate, extra: string[] = []): string[] {
+    const labels = [...(template.labels ?? [])];
+    if (template.agent !== undefined) {
+        labels.push(`agent:${template.agent}`);
+    }
+    if (template.runMode !== undefined) {
+        labels.push(`run:${template.runMode}`);
+    }
+    if (template.jobKind !== undefined) {
+        labels.push(`jobkind:${template.jobKind}`);
+    }
+    labels.push(...extra);
+    const seen = new Set<string>();
+    const deduped: string[] = [];
+    for (const label of labels) {
+        if (!seen.has(label)) {
+            seen.add(label);
+            deduped.push(label);
+        }
+    }
+    return deduped;
+}
+
+function buildPreview(draft: IssueDraft): string {
+    return [
+        `Title:  ${draft.title}`,
+        `State:  ${draft.state ?? DEFAULT_STATE}`,
+        `Type:   ${draft.type ?? "—"}`,
+        `Labels: ${draft.labels !== undefined && draft.labels.length > 0 ? draft.labels.join(", ") : "—"}`,
+        "─────────────────────────────",
+        draft.body,
+    ].join("\n");
+}
+
+export async function newIssue(
+    project: string,
+    templateName: string | undefined,
+    deps: NewIssueDeps,
+): Promise<Issue | null> {
+    const log =
+        deps.log ??
+        ((): void => {
+            /* no-op: logging disabled */
+        });
+
+    let template: IssueTemplate;
+    if (templateName !== undefined) {
+        template = loadIssueTemplate(templateName, deps.templateDeps);
+    } else {
+        const list = listIssueTemplates(deps.templateDeps);
+        if (list.length === 0) {
+            throw new Error("beflow: no issue templates available to choose from");
+        }
+        const chosen = await deps.askTemplate(list);
+        template = loadIssueTemplate(chosen, deps.templateDeps);
+    }
+
+    const raw = await deps.askQuestions(template.questions);
+    const answers = fillAnswers(template.questions, raw);
+
+    let title = deriveTitle(template, answers);
+    let body = renderIssueBody(template, answers);
+
+    // Template values stay authoritative; enrich only fills what the template
+    // leaves unset. Enrich is skipped for enrich:false templates and on the form
+    // path (deps.enrich undefined).
+    let type: string | undefined = template.type;
+    let priority: string | undefined = template.priority;
+    let extraLabels: string[] = [];
+    if (template.enrich && deps.enrich !== undefined) {
+        const fence = await deps.enrich({ answers, seedBody: body, seedTitle: title, template });
+        if (fence !== null) {
+            body = fence.body;
+            if (fence.title !== undefined && fence.title.trim() !== "") {
+                title = fence.title.trim();
+            }
+            type = template.type ?? fence.type;
+            priority = template.priority ?? fence.priority;
+            extraLabels = fence.labels ?? [];
+        } else {
+            log("beflow: enrich produced no issue block; using the form draft");
+        }
+    }
+
+    const labels = mapLabels(template, extraLabels);
+
+    const draft: IssueDraft = {
+        body,
+        state: template.state ?? deps.defaultState ?? DEFAULT_STATE,
+        title,
+        ...(type !== undefined ? { type } : {}),
+        ...(priority !== undefined ? { priority } : {}),
+        ...(labels.length > 0 ? { labels } : {}),
+    };
+
+    const ok = await deps.askConfirm(buildPreview(draft));
+    if (!ok) {
+        log("beflow: issue creation cancelled");
+        return null;
+    }
+
+    const issue = await deps.tracker.createIssue(project, draft);
+    log(`beflow: created ${issue.key}`);
+    return issue;
+}

package/src/core/notify.ts

@@ -0,0 +1,151 @@
+export type NotifyFormat = "discord" | "generic" | "slack";
+
+export type NotifyReason = "needs_input" | "blocked" | "failed" | "reminder" | "resolved";
+
+function parseHost(url: string): string | null {
+    try {
+        const { host } = new URL(url);
+        return host;
+    } catch {
+        return null;
+    }
+}
+
+export function detectFormat(url: string): NotifyFormat {
+    const host = parseHost(url);
+    if (host === null) {
+        return "generic";
+    }
+    if (host.includes("hooks.slack.com")) {
+        return "slack";
+    }
+    if (host.includes("discord.com") || host.includes("discordapp.com")) {
+        return "discord";
+    }
+    return "generic";
+}
+
+export interface NotifyEvent {
+    detail?: string;
+    key: string;
+    reason: NotifyReason;
+    title: string;
+}
+
+export interface Notifier {
+    notify: (evt: NotifyEvent) => Promise<void>;
+}
+
+/** Minimal fetch signature used for injection / testing. */
+export type FetchFn = (url: string, init: RequestInit) => Promise<Response>;
+
+export const noopNotifier: Notifier = {
+    notify: async (): Promise<void> => {
+        /* No-op: notification disabled */
+    },
+};
+
+export class WebhookNotifier implements Notifier {
+    private readonly fetchImpl?: FetchFn;
+    private readonly format: NotifyFormat;
+    private readonly log: (m: string) => void;
+    private readonly url: string;
+
+    public constructor(opts: { fetchImpl?: FetchFn; format?: NotifyFormat; log?: (m: string) => void; url: string }) {
+        this.fetchImpl = opts.fetchImpl;
+        this.format = opts.format ?? detectFormat(opts.url);
+        this.log =
+            opts.log ??
+            ((): void => {
+                /* No-op */
+            });
+        this.url = opts.url;
+    }
+
+    private buildBody(evt: NotifyEvent, message: string): Record<string, unknown> {
+        if (this.format === "slack") {
+            return { text: message };
+        }
+        if (this.format === "discord") {
+            const content = message.length > 2000 ? `${message.slice(0, 1999)}…` : message;
+            return { content };
+        }
+        return {
+            ...(evt.detail !== undefined ? { detail: evt.detail } : {}),
+            event: "beflow.escalation",
+            issue: { key: evt.key, title: evt.title },
+            reason: evt.reason,
+            text: message,
+        };
+    }
+
+    public async notify(evt: NotifyEvent): Promise<void> {
+        const phrases: Record<NotifyReason, string> = {
+            blocked: "is blocked",
+            failed: "failed",
+            needs_input: "needs input",
+            reminder: "is still waiting",
+            resolved: "is resolved",
+        };
+        const phrase = phrases[evt.reason];
+        const headline = `🔔 beflow: ${evt.key} ${phrase} — ${evt.title}`;
+        const message = headline + (evt.detail !== undefined ? `\n${evt.detail}` : "");
+
+        const body: Record<string, unknown> = this.buildBody(evt, message);
+
+        const fetchFn: FetchFn = this.fetchImpl ?? fetch;
+        try {
+            const res = await fetchFn(this.url, {
+                body: JSON.stringify(body),
+                headers: { "Content-Type": "application/json" },
+                method: "POST",
+            });
+            if (!res.ok) {
+                this.log(`beflow: webhook notify failed (${String(res.status)} ${res.statusText})`);
+            }
+        } catch (err) {
+            this.log(`beflow: webhook notify error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+
+export function createNotifier(opts: {
+    fetchImpl?: FetchFn;
+    format?: NotifyFormat;
+    log?: (m: string) => void;
+    webhookUrl?: string;
+}): Notifier {
+    if (opts.webhookUrl !== undefined && opts.webhookUrl !== "") {
+        return new WebhookNotifier({
+            fetchImpl: opts.fetchImpl,
+            ...(opts.format !== undefined ? { format: opts.format } : {}),
+            log: opts.log,
+            url: opts.webhookUrl,
+        });
+    }
+    return noopNotifier;
+}
+
+export function escalationDetail(report: { questions?: string[]; summary: string }): string {
+    if (report.questions !== undefined && report.questions.length > 0) {
+        return report.questions.map((q) => `- ${q}`).join("\n");
+    }
+    return report.summary;
+}
+
+export async function notifyEscalation(
+    notifier: Notifier | undefined,
+    issue: { key: string; title: string },
+    reason: NotifyReason,
+    detail?: string,
+): Promise<void> {
+    if (notifier === undefined) {
+        return;
+    }
+    await notifier.notify({
+        ...(detail !== undefined ? { detail } : {}),
+        key: issue.key,
+        reason,
+        title: issue.title,
+    });
+}

package/src/core/prompts.ts

@@ -0,0 +1,165 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { Issue, JobKind } from "../model/types.ts";
+import continuationDefault from "../prompts/defaults/continuation.md" with { type: "text" };
+import implementDefault from "../prompts/defaults/implement.md" with { type: "text" };
+import issueEnrichDefault from "../prompts/defaults/issue-enrich.md" with { type: "text" };
+import reportDefault from "../prompts/defaults/report.md" with { type: "text" };
+import reviewDefault from "../prompts/defaults/review.md" with { type: "text" };
+import specDefault from "../prompts/defaults/spec.md" with { type: "text" };
+import taskDefault from "../prompts/defaults/task.md" with { type: "text" };
+import triageDefault from "../prompts/defaults/triage.md" with { type: "text" };
+import type { IssueContext } from "../trackers/tracker.ts";
+
+export const PROMPT_NAMES = ["triage", "spec", "implement", "report", "task", "continuation", "review"] as const;
+export type PromptName = (typeof PROMPT_NAMES)[number];
+
+export interface PromptSet {
+    triage: string;
+    spec: string;
+    implement: string;
+    report: string;
+    task: string;
+    continuation: string;
+    review: string;
+}
+
+const COMPILED_DEFAULTS: PromptSet = {
+    continuation: continuationDefault,
+    implement: implementDefault,
+    report: reportDefault,
+    review: reviewDefault,
+    spec: specDefault,
+    task: taskDefault,
+    triage: triageDefault,
+};
+
+// Injectable IO so the cascade is testable without touching the real filesystem.
+export interface PromptResolveDeps {
+    configDir: string;
+    promptsDir?: string;
+    home: string;
+    exists: (p: string) => boolean;
+    read: (p: string) => string;
+}
+
+export function defaultPromptResolveDeps(configDir: string, promptsDir?: string): PromptResolveDeps {
+    return {
+        configDir,
+        exists: existsSync,
+        home: homedir(),
+        read: (p) => readFileSync(p, "utf8"),
+        ...(promptsDir !== undefined ? { promptsDir } : {}),
+    };
+}
+
+function expandHome(p: string, home: string): string {
+    return p.startsWith("~") ? join(home, p.slice(1)) : p;
+}
+
+// Override cascade candidate paths for a `<basename>.md`, highest priority first:
+// project-local (beside config.json), the configured prompts.dir, then
+// ~/.beflow/prompts.
+function promptCandidates(basename: string, deps: PromptResolveDeps): string[] {
+    const candidates: string[] = [join(deps.configDir, "prompts", `${basename}.md`)];
+    if (deps.promptsDir !== undefined) {
+        candidates.push(join(expandHome(deps.promptsDir, deps.home), `${basename}.md`));
+    }
+    candidates.push(join(deps.home, ".beflow", "prompts", `${basename}.md`));
+    return candidates;
+}
+
+// Override cascade, highest priority first: first readable file from
+// promptCandidates wins; otherwise the compiled-in default.
+function resolvePrompt(name: PromptName, deps: PromptResolveDeps): string {
+    for (const path of promptCandidates(name, deps)) {
+        if (deps.exists(path)) {
+            return deps.read(path);
+        }
+    }
+    return COMPILED_DEFAULTS[name];
+}
+
+// The issue-authoring enrich prompt. It rides the SAME override cascade as the
+// threaded PromptSet but is loaded on demand (only `beflow new --enrich` needs
+// it), so it stays out of PromptSet/PROMPT_NAMES.
+export function loadEnrichPrompt(deps: PromptResolveDeps): string {
+    for (const path of promptCandidates("issue-enrich", deps)) {
+        if (deps.exists(path)) {
+            return deps.read(path);
+        }
+    }
+    return issueEnrichDefault;
+}
+
+export function loadPromptSet(deps: PromptResolveDeps): PromptSet {
+    return {
+        continuation: resolvePrompt("continuation", deps),
+        implement: resolvePrompt("implement", deps),
+        report: resolvePrompt("report", deps),
+        review: resolvePrompt("review", deps),
+        spec: resolvePrompt("spec", deps),
+        task: resolvePrompt("task", deps),
+        triage: resolvePrompt("triage", deps),
+    };
+}
+
+const PLACEHOLDER = /\{\{\s*(\w+)\s*\}\}/g;
+
+export function renderTemplate(name: string, tpl: string, ctx: Record<string, string>): string {
+    return tpl.replace(PLACEHOLDER, (_match, key: string) => {
+        if (!Object.prototype.hasOwnProperty.call(ctx, key)) {
+            throw new Error(`beflow: unknown placeholder "{{${key}}}" in ${name} prompt`);
+        }
+        return ctx[key] ?? "";
+    });
+}
+
+export function buildPromptContext(issue: Issue, repo: string): Record<string, string> {
+    const type = issue.type ?? "Unspecified";
+    const description = issue.body.trim() === "" ? "(no description provided)" : issue.body;
+    return {
+        description,
+        key: issue.key,
+        repo,
+        title: issue.title,
+        type,
+    };
+}
+
+export function renderTask(set: PromptSet, issue: Issue, repo: string): string {
+    return renderTemplate("task", set.task, buildPromptContext(issue, repo));
+}
+
+export function renderContract(set: PromptSet, jobKind: JobKind, issue: Issue, repo: string): string {
+    const ctx = buildPromptContext(issue, repo);
+    return `${renderTemplate(jobKind, set[jobKind], ctx)}\n\n${renderTemplate("report", set.report, ctx)}`;
+}
+
+export function renderReviewContract(set: PromptSet, issue: Issue, repo: string): string {
+    return renderTemplate("review", set.review, buildPromptContext(issue, repo));
+}
+
+// Render the linked context (parent epic + attachments) appended to the agent
+// Task. Pure and deterministic; returns "" when there is nothing to inline.
+export function renderLinkedContext(ctx: IssueContext): string {
+    const { attachments, parent } = ctx;
+    if (parent === undefined && attachments.length === 0) {
+        return "";
+    }
+
+    let out = "\n\n## Linked context\n";
+    if (parent !== undefined) {
+        const label = parent.type ?? "item";
+        out += `\nParent ${label} ${parent.key} "${parent.title}":\n${parent.body || "(no description)"}\n`;
+    }
+    if (attachments.length > 0) {
+        out += "\nAttachments (download URLs are temporary):\n";
+        for (const a of attachments) {
+            out += a.url !== "" ? `- ${a.name} (${a.url})\n` : `- ${a.name} (no direct download link)\n`;
+        }
+    }
+    return out;
+}