beflow 0.1.0

package/src/core/issuetemplate.ts

@@ -0,0 +1,175 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+
+import bugDefault from "../prompts/defaults/issues/bug.md" with { type: "text" };
+import featureDefault from "../prompts/defaults/issues/feature.md" with { type: "text" };
+import genericDefault from "../prompts/defaults/issues/generic.md" with { type: "text" };
+import spikeDefault from "../prompts/defaults/issues/spike.md" with { type: "text" };
+import { renderTemplate } from "./prompts.ts";
+
+const COMPILED_DEFAULTS: Record<string, string> = {
+    bug: bugDefault,
+    feature: featureDefault,
+    generic: genericDefault,
+    spike: spikeDefault,
+};
+
+const questionSchema = z
+    .object({
+        key: z.string(),
+        label: z.string(),
+        options: z.array(z.string()).optional(),
+        required: z.boolean().default(false),
+        type: z.enum(["text", "longtext", "bool", "number", "options", "multiselect"]),
+    })
+    .superRefine((q, ctx) => {
+        if ((q.type === "options" || q.type === "multiselect") && (q.options === undefined || q.options.length === 0)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `question "${q.key}" of type "${q.type}" requires a non-empty "options" array`,
+                path: ["options"],
+            });
+        }
+    });
+
+export type Question = z.infer<typeof questionSchema>;
+
+export const issueTemplateSchema = z
+    .object({
+        agent: z.string().optional(),
+        description: z.string(),
+        enrich: z.boolean().default(false),
+        jobKind: z.enum(["triage", "spec", "implement"]).optional(),
+        labels: z.array(z.string()).optional(),
+        name: z.string(),
+        priority: z.enum(["urgent", "high", "medium", "low", "none"]).optional(),
+        questions: z.array(questionSchema).default([]),
+        runMode: z.enum(["autonomous", "supervised"]).optional(),
+        state: z.string().optional(),
+        title: z.string().optional(),
+        type: z.string().optional(),
+    })
+    .superRefine((tpl, ctx) => {
+        const seen = new Set<string>();
+        for (const q of tpl.questions) {
+            if (seen.has(q.key)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `duplicate question key "${q.key}"`,
+                    path: ["questions"],
+                });
+            }
+            seen.add(q.key);
+        }
+    });
+
+type IssueTemplateFrontmatter = z.infer<typeof issueTemplateSchema>;
+
+export type IssueTemplate = IssueTemplateFrontmatter & { body: string };
+
+// Injectable IO so the cascade is testable without touching the real filesystem.
+export interface IssueTemplateResolveDeps {
+    configDir: string;
+    promptsDir?: string;
+    home: string;
+    exists: (p: string) => boolean;
+    listDir: (dir: string) => string[];
+    read: (p: string) => string;
+}
+
+export function defaultIssueTemplateResolveDeps(configDir: string, promptsDir?: string): IssueTemplateResolveDeps {
+    return {
+        configDir,
+        exists: existsSync,
+        home: homedir(),
+        listDir: (dir) => (existsSync(dir) ? readdirSync(dir) : []),
+        read: (p) => readFileSync(p, "utf8"),
+        ...(promptsDir !== undefined ? { promptsDir } : {}),
+    };
+}
+
+function expandHome(p: string, home: string): string {
+    return p.startsWith("~") ? join(home, p.slice(1)) : p;
+}
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+
+export function parseFrontmatter(raw: string): { frontmatter: unknown; body: string } {
+    const match = FRONTMATTER.exec(raw);
+    if (match === null) {
+        throw new Error("beflow: issue template has no YAML frontmatter block (must start with '---')");
+    }
+    return { body: match[2] ?? "", frontmatter: parseYaml(match[1] ?? "") };
+}
+
+function parseTemplate(name: string, raw: string): IssueTemplate {
+    const { body, frontmatter } = parseFrontmatter(raw);
+    const result = issueTemplateSchema.safeParse(frontmatter);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const detail = issue !== undefined ? `${issue.path.join(".")}: ${issue.message}` : result.error.message;
+        throw new Error(`beflow: invalid issue template "${name}" (${detail})`);
+    }
+    return { ...result.data, body };
+}
+
+// Candidate dirs, highest priority first: project-local (beside config.json),
+// the configured prompts.dir/issues, then ~/.beflow/prompts/issues.
+function candidateDirs(deps: IssueTemplateResolveDeps): string[] {
+    const dirs: string[] = [join(deps.configDir, "prompts", "issues")];
+    if (deps.promptsDir !== undefined) {
+        dirs.push(join(expandHome(deps.promptsDir, deps.home), "issues"));
+    }
+    dirs.push(join(deps.home, ".beflow", "prompts", "issues"));
+    return dirs;
+}
+
+export function loadIssueTemplate(name: string, deps: IssueTemplateResolveDeps): IssueTemplate {
+    for (const dir of candidateDirs(deps)) {
+        const path = join(dir, `${name}.md`);
+        if (deps.exists(path)) {
+            return parseTemplate(name, deps.read(path));
+        }
+    }
+    const compiled = COMPILED_DEFAULTS[name];
+    if (compiled !== undefined) {
+        return parseTemplate(name, compiled);
+    }
+    const available = listIssueTemplates(deps)
+        .map((t) => t.name)
+        .join(", ");
+    throw new Error(`beflow: unknown issue template "${name}" (available: ${available})`);
+}
+
+export function listIssueTemplates(deps: IssueTemplateResolveDeps): { name: string; description: string }[] {
+    // Union of names across cascade dirs (highest priority first) + compiled
+    // defaults; first occurrence of a name wins for its description.
+    const names: string[] = [];
+    for (const dir of candidateDirs(deps)) {
+        for (const file of deps.listDir(dir)) {
+            if (file.endsWith(".md")) {
+                names.push(file.slice(0, -".md".length));
+            }
+        }
+    }
+    names.push(...Object.keys(COMPILED_DEFAULTS));
+
+    const seen = new Set<string>();
+    const entries: { name: string; description: string }[] = [];
+    for (const name of names) {
+        if (seen.has(name)) {
+            continue;
+        }
+        seen.add(name);
+        entries.push({ description: loadIssueTemplate(name, deps).description, name });
+    }
+    return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function renderIssueBody(template: IssueTemplate, answers: Record<string, string>): string {
+    return renderTemplate(`issue:${template.name}`, template.body, answers);
+}

package/src/core/mcp.ts

@@ -0,0 +1,191 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { z } from "zod";
+
+// ACP McpServer shapes beflow forwards to acpx via `.acpxrc.json`. The stdio
+// Variant is the untagged union member: it carries NO `type` field. http/sse
+// Are tagged and carry a URL plus optional name/value header pairs.
+export interface McpStdioServer {
+    name: string;
+    command: string;
+    args: string[];
+    env: { name: string; value: string }[];
+}
+
+export interface McpHttpServer {
+    type: "http";
+    name: string;
+    url: string;
+    headers?: { name: string; value: string }[];
+}
+
+export interface McpSseServer {
+    type: "sse";
+    name: string;
+    url: string;
+    headers?: { name: string; value: string }[];
+}
+
+export type McpServer = McpHttpServer | McpSseServer | McpStdioServer;
+
+// The user-authored `.mcp.json` map (oh-my-pi / Claude format): a record of
+// Name → entry. `type` defaults to stdio; stdio needs `command`, http/sse need
+// `url`. superRefine enforces those per-variant requirements.
+const mcpEntrySchema = z
+    .object({
+        args: z.array(z.string()).optional(),
+        command: z.string().optional(),
+        env: z.record(z.string(), z.string()).optional(),
+        headers: z.record(z.string(), z.string()).optional(),
+        type: z.enum(["http", "sse", "stdio"]).optional(),
+        url: z.string().optional(),
+    })
+    .superRefine((entry, ctx) => {
+        const type = entry.type ?? "stdio";
+        if (type === "stdio") {
+            if (entry.command === undefined) {
+                ctx.addIssue({ code: z.ZodIssueCode.custom, message: "stdio MCP server requires `command`" });
+            }
+        } else if (entry.url === undefined) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: `${type} MCP server requires \`url\`` });
+        }
+    });
+
+export type McpEntry = z.infer<typeof mcpEntrySchema>;
+
+export const mcpFileSchema = z.object({
+    mcpServers: z.record(z.string(), mcpEntrySchema),
+});
+
+export interface McpResolveDeps {
+    configDir: string;
+    home: string;
+    exists: (p: string) => boolean;
+    read: (p: string) => string;
+}
+
+export function defaultMcpDeps(configDir: string): McpResolveDeps {
+    return {
+        configDir,
+        exists: existsSync,
+        home: homedir(),
+        read: (p) => readFileSync(p, "utf8"),
+    };
+}
+
+function toHeaderPairs(headers: Record<string, string>): { name: string; value: string }[] {
+    return Object.entries(headers).map(([name, value]) => ({ name, value }));
+}
+
+// Translate a validated `.mcp.json` entry into the ACP McpServer shape.
+function translate(name: string, entry: McpEntry): McpServer {
+    const type = entry.type ?? "stdio";
+    if (type === "http" || type === "sse") {
+        const url = entry.url ?? "";
+        return {
+            name,
+            type,
+            url,
+            ...(entry.headers !== undefined ? { headers: toHeaderPairs(entry.headers) } : {}),
+        };
+    }
+    return {
+        args: entry.args ?? [],
+        command: entry.command ?? "",
+        env: Object.entries(entry.env ?? {}).map(([envName, value]) => ({ name: envName, value })),
+        name,
+    };
+}
+
+function loadMap(path: string, deps: McpResolveDeps): Record<string, McpEntry> {
+    if (!deps.exists(path)) {
+        return {};
+    }
+    const parsed: unknown = JSON.parse(deps.read(path));
+    return mcpFileSchema.parse(parsed).mcpServers;
+}
+
+function expandHome(p: string, home: string): string {
+    return p.startsWith("~") ? join(home, p.slice(1)) : p;
+}
+
+// Load + merge the `.mcp.json` cascade and translate it to ACP McpServer shapes.
+// Cascade (project wins per server NAME): GLOBAL `<home>/.beflow/.mcp.json`,
+// Then PROJECT `<configDir>/.mcp.json`. Missing files are skipped. Returns `[]`
+// When nothing is configured.
+export function loadMcpServers(deps: McpResolveDeps): McpServer[] {
+    const globalPath = join(expandHome("~/.beflow", deps.home), ".mcp.json");
+    const projectPath = join(deps.configDir, ".mcp.json");
+    const merged: Record<string, McpEntry> = {
+        ...loadMap(globalPath, deps),
+        ...loadMap(projectPath, deps),
+    };
+    return Object.entries(merged).map(([name, entry]) => translate(name, entry));
+}
+
+export interface McpFs {
+    exists(p: string): boolean;
+    read(p: string): string;
+    write(p: string, data: string): void;
+    remove(p: string): void;
+}
+
+export const nodeMcpFs: McpFs = {
+    exists: (p) => existsSync(p),
+    read: (p) => readFileSync(p, "utf8"),
+    remove: (p) => {
+        rmSync(p, { force: true });
+    },
+    write: (p, data) => {
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, data, "utf8");
+    },
+};
+
+// Write a managed `.acpxrc.json` at `<cwd>/.acpxrc.json` setting `mcpServers`,
+// Preserving any other keys from a pre-existing file, and return a CLEANUP that
+// Restores the exact prior content (or removes the file when there was none).
+// Empty `servers` is a no-op returning a no-op cleanup. Cleanup never throws.
+export function injectAcpxMcp(cwd: string, servers: McpServer[], fs: McpFs): () => void {
+    if (servers.length === 0) {
+        return (): void => {
+            /* no-op: nothing was injected */
+        };
+    }
+
+    const path = join(cwd, ".acpxrc.json");
+    const prior: string | null = fs.exists(path) ? fs.read(path) : null;
+
+    const base: Record<string, unknown> = {};
+    if (prior !== null) {
+        try {
+            const parsed: unknown = JSON.parse(prior);
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                for (const [k, v] of Object.entries(parsed)) {
+                    base[k] = v;
+                }
+            }
+        } catch {
+            // Unparseable prior: start from {} for the merge, but the exact prior
+            // String is still captured above for an exact restore on cleanup.
+        }
+    }
+
+    base.mcpServers = servers;
+    fs.write(path, `${JSON.stringify(base, null, 2)}\n`);
+
+    return (): void => {
+        try {
+            if (prior === null) {
+                fs.remove(path);
+            } else {
+                fs.write(path, prior);
+            }
+        } catch {
+            // Best-effort restore, mirroring the worktree-removal pattern: a failure
+            // To restore must never mask the run's own outcome.
+        }
+    };
+}