builder-assistant-engineer 0.2.0

package/dist/backends/agent-cli.js

@@ -0,0 +1,174 @@
+import { mkdir, rm } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import { UserError } from "../core/errors.js";
+import { readTextIfExists, writeText } from "../core/fs.js";
+import { asRecord, parseObject } from "../core/json.js";
+import { baePaths } from "../core/paths.js";
+import { runCommand, runInteractive } from "../core/process.js";
+import { t } from "../i18n/index.js";
+const STDIN_INSTRUCTION = "Follow the instructions above exactly.";
+const ERROR_TAIL = 2_000;
+export const AGENT_SPECS = {
+    claude: {
+        name: "claude",
+        command: "claude",
+        headless: (access) => [
+            "-p",
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            "--no-session-persistence",
+            "--permission-prompts",
+            "none",
+            ...(access === "read"
+                ? ["--tools", "Read,Grep,Glob", "--setting-sources", "user"]
+                : ["--permission-mode", "acceptEdits", "--setting-sources", "user,project"]),
+        ],
+        interactive: (instruction) => [instruction],
+        jsonOutput: true,
+        parse: parseClaudeJson,
+    },
+    opencode: {
+        name: "opencode",
+        command: "opencode",
+        headless: (access) => ["run", ...(access === "read" ? ["--agent", "plan"] : [])],
+        interactive: (instruction) => ["--prompt", instruction],
+        parse: (result) => ({
+            text: result.stdout,
+            info: { model: stderrModel(result, /^> \S+ · (.+)$/m) },
+        }),
+    },
+    codex: {
+        name: "codex",
+        command: "codex",
+        headless: (access, outputFile) => [
+            "exec",
+            "--color",
+            "never",
+            "--sandbox",
+            access === "read" ? "read-only" : "workspace-write",
+            ...(access === "read" ? ["--skip-git-repo-check"] : []),
+            "--output-last-message",
+            outputFile,
+            "-",
+        ],
+        interactive: (instruction) => [instruction],
+        readsOutputFile: true,
+        parse: (result) => ({
+            text: result.stdout,
+            info: { model: stderrModel(result, /^model:\s*(.+)$/m) },
+        }),
+    },
+    gemini: {
+        name: "gemini",
+        command: "gemini",
+        headless: (access) => [
+            "--output-format",
+            "text",
+            "--approval-mode",
+            access === "read" ? "plan" : "auto_edit",
+            "--prompt",
+            STDIN_INSTRUCTION,
+        ],
+        interactive: (instruction) => ["--prompt-interactive", instruction],
+    },
+};
+export const defaultRunner = { run: runCommand, interactive: runInteractive };
+export function createAgentBackend(spec, runner = defaultRunner) {
+    return {
+        name: spec.name,
+        run: (prompt, options) => options.interactive
+            ? runSession(spec, runner, prompt, options)
+            : runHeadless(spec, runner, prompt, options),
+    };
+}
+async function runHeadless(spec, runner, prompt, options) {
+    const tmp = baePaths(options.cwd).tmp;
+    const outputFile = join(tmp, `${spec.name}-output.md`);
+    if (spec.readsOutputFile) {
+        await mkdir(tmp, { recursive: true });
+        await rm(outputFile, { force: true });
+    }
+    const args = spec.headless(options.access ?? "read", outputFile);
+    const result = await runner.run(spec.command, args, {
+        cwd: options.cwd,
+        input: prompt,
+        timeoutMs: options.timeoutMs,
+        onStdout: spec.jsonOutput ? undefined : options.stream,
+    });
+    assertSucceeded(spec, result, options.timeoutMs);
+    const parsed = spec.parse?.(result) ?? { text: result.stdout, info: {} };
+    options.onInfo?.(parsed.info);
+    if (spec.jsonOutput)
+        options.stream?.(parsed.text);
+    if (!spec.readsOutputFile)
+        return parsed.text;
+    return (await readTextIfExists(outputFile)) ?? parsed.text;
+}
+function parseClaudeJson(result) {
+    const events = result.stdout.split(/\r?\n/).flatMap((line) => {
+        const event = line.trim().startsWith("{") ? parseObject(line.trim()) : undefined;
+        return event ? [event] : [];
+    });
+    const data = events.filter((event) => event.type === "result").at(-1);
+    if (!data || typeof data.result !== "string")
+        return { text: result.stdout, info: {} };
+    const models = Object.keys(asRecord(data.modelUsage));
+    const cost = typeof data.total_cost_usd === "number" ? data.total_cost_usd : undefined;
+    const truncated = typeof data.stop_reason === "string" ? data.stop_reason === "max_tokens" : undefined;
+    const answer = finalAnswer(events);
+    return {
+        text: answer || data.result,
+        info: { model: models.join(", ") || undefined, costUsd: cost, truncated },
+    };
+}
+function finalAnswer(events) {
+    let tail = [];
+    const seen = new Set();
+    for (const event of events) {
+        if (event.type !== "assistant")
+            continue;
+        const message = asRecord(event.message);
+        const blocks = Array.isArray(message.content) ? message.content : [];
+        for (const block of blocks.map(asRecord)) {
+            if (block.type === "tool_use")
+                tail = [];
+            if (block.type !== "text" || typeof block.text !== "string")
+                continue;
+            const key = `${String(message.id ?? "")}:${block.text}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            tail.push(block.text);
+        }
+    }
+    return tail.join("");
+}
+function stderrModel(result, pattern) {
+    return pattern.exec(stripVTControlCharacters(result.stderr))?.[1]?.trim() || undefined;
+}
+async function runSession(spec, runner, prompt, options) {
+    const promptFile = join(baePaths(options.cwd).tmp, "prompt.md");
+    await writeText(promptFile, prompt);
+    const path = relative(options.cwd, promptFile).split("\\").join("/");
+    const instruction = `Read ${path} and carry out the task it describes. It is your complete task prompt.`;
+    const result = await runner.interactive(spec.command, spec.interactive(instruction), {
+        cwd: options.cwd,
+    });
+    if (result.notFound)
+        throw new UserError(t("backend.notInstalled", { command: spec.command }));
+    return "";
+}
+function assertSucceeded(spec, result, timeoutMs) {
+    if (result.notFound)
+        throw new UserError(t("backend.notInstalled", { command: spec.command }));
+    if (result.timedOut) {
+        const minutes = Math.round((timeoutMs ?? 0) / 60_000);
+        throw new UserError(t("backend.timedOut", { command: spec.command, minutes }));
+    }
+    if (result.exitCode === 0)
+        return;
+    const details = (result.stderr.trim() || result.stdout.trim()).slice(-ERROR_TAIL);
+    throw new UserError(t("backend.failed", { command: spec.command, code: result.exitCode, details }));
+}

package/dist/backends/api.js

@@ -0,0 +1,171 @@
+import { UserError } from "../core/errors.js";
+import { asRecord, parseObject } from "../core/json.js";
+import { t } from "../i18n/index.js";
+import { readSse } from "./sse.js";
+export const DEFAULT_ANTHROPIC_MODEL = "claude-opus-5";
+export const ANTHROPIC_MAX_TOKENS = 64_000;
+const ANTHROPIC_VERSION = "2023-06-01";
+const FALLBACK_BETA = "server-side-fallback-2026-07-01";
+const RETRYABLE = new Set([408, 429, 500, 502, 503, 504, 529]);
+const MAX_RETRIES = 2;
+const MAX_RETRY_DELAY_MS = 30_000;
+const ERROR_TAIL = 1_000;
+const defaultDeps = {
+    env: process.env,
+    fetch: (...args) => fetch(...args),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+export function createApiBackend(overrides = {}) {
+    const deps = { ...defaultDeps, ...overrides };
+    return {
+        name: "api",
+        run: async (prompt, options) => {
+            if (options.interactive)
+                throw new UserError(t("backend.apiInteractive"));
+            const target = resolveApiTarget(deps.env);
+            options.onInfo?.({ model: target.model });
+            return target.provider === "anthropic"
+                ? callAnthropic(target, prompt, options, deps)
+                : callOpenAi(target, prompt, options, deps);
+        },
+    };
+}
+export function resolveApiTarget(env) {
+    const provider = env.BAE_API_PROVIDER ?? inferProvider(env);
+    if (provider === "anthropic") {
+        return {
+            provider,
+            baseUrl: trimSlash(env.ANTHROPIC_BASE_URL ?? "https://api.anthropic.com"),
+            apiKey: env.ANTHROPIC_API_KEY,
+            model: env.BAE_MODEL ?? DEFAULT_ANTHROPIC_MODEL,
+        };
+    }
+    if (provider === "openai") {
+        const baseUrl = trimSlash(env.OPENAI_BASE_URL ?? "https://api.openai.com/v1");
+        if (!env.BAE_MODEL)
+            throw new UserError(t("backend.apiModelRequired", { baseUrl }));
+        return { provider, baseUrl, apiKey: env.OPENAI_API_KEY, model: env.BAE_MODEL };
+    }
+    if (provider === undefined)
+        throw new UserError(t("backend.apiNotConfigured"));
+    throw new UserError(t("backend.apiProviderInvalid", { provider }));
+}
+export function hasApiCredentials(env) {
+    return inferProvider(env) !== undefined;
+}
+function inferProvider(env) {
+    if (env.ANTHROPIC_API_KEY)
+        return "anthropic";
+    if (env.OPENAI_API_KEY || env.OPENAI_BASE_URL)
+        return "openai";
+    return undefined;
+}
+async function callAnthropic(target, prompt, options, deps) {
+    const useFallbacks = target.model === DEFAULT_ANTHROPIC_MODEL;
+    const headers = {
+        "content-type": "application/json",
+        "x-api-key": target.apiKey ?? "",
+        "anthropic-version": ANTHROPIC_VERSION,
+        ...(useFallbacks ? { "anthropic-beta": FALLBACK_BETA } : {}),
+    };
+    const body = {
+        model: target.model,
+        max_tokens: ANTHROPIC_MAX_TOKENS,
+        stream: true,
+        messages: [{ role: "user", content: prompt }],
+        ...(useFallbacks ? { fallbacks: "default" } : {}),
+    };
+    const response = await post(`${target.baseUrl}/v1/messages`, headers, body, "Anthropic", deps);
+    let text = "";
+    let stopReason;
+    for await (const { event, data } of readSse(bodyOf(response))) {
+        const payload = parseObject(data) ?? {};
+        if (event === "error")
+            throw new UserError(apiError("Anthropic", payload));
+        const delta = asRecord(payload.delta);
+        if (payload.type === "content_block_delta" && delta.type === "text_delta") {
+            const chunk = String(delta.text ?? "");
+            text += chunk;
+            options.stream?.(chunk);
+        }
+        if (payload.type === "message_delta")
+            stopReason = delta.stop_reason;
+    }
+    if (stopReason === "refusal")
+        throw new UserError(t("backend.refusal"));
+    if (stopReason === "max_tokens")
+        throw new UserError(t("backend.truncated"));
+    options.onInfo?.({ truncated: false });
+    return text;
+}
+async function callOpenAi(target, prompt, options, deps) {
+    const headers = {
+        "content-type": "application/json",
+        ...(target.apiKey ? { authorization: `Bearer ${target.apiKey}` } : {}),
+    };
+    const body = {
+        model: target.model,
+        stream: true,
+        messages: [{ role: "user", content: prompt }],
+    };
+    const response = await post(`${target.baseUrl}/chat/completions`, headers, body, "OpenAI", deps);
+    let text = "";
+    let finishReason;
+    for await (const { data } of readSse(bodyOf(response))) {
+        if (data.trim() === "[DONE]")
+            break;
+        const payload = parseObject(data) ?? {};
+        if (payload.error)
+            throw new UserError(apiError("OpenAI", payload));
+        const choice = asRecord(Array.isArray(payload.choices) ? payload.choices[0] : undefined);
+        const content = asRecord(choice.delta).content;
+        if (typeof content === "string") {
+            text += content;
+            options.stream?.(content);
+        }
+        finishReason = choice.finish_reason ?? finishReason;
+    }
+    if (finishReason === "length")
+        throw new UserError(t("backend.truncated"));
+    options.onInfo?.({ truncated: false });
+    return text;
+}
+async function post(url, headers, body, provider, deps) {
+    for (let attempt = 0;; attempt++) {
+        const response = await send(url, headers, body, deps);
+        if (response.ok)
+            return response;
+        if (!RETRYABLE.has(response.status) || attempt >= MAX_RETRIES) {
+            const details = (await response.text()).slice(0, ERROR_TAIL);
+            throw new UserError(t("backend.apiHttp", { provider, status: response.status, details }));
+        }
+        await deps.sleep(retryDelay(response, attempt));
+    }
+}
+async function send(url, headers, body, deps) {
+    try {
+        return await deps.fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
+    }
+    catch (error) {
+        const details = error instanceof Error ? error.message : String(error);
+        throw new UserError(t("backend.apiNetwork", { url, details }));
+    }
+}
+function retryDelay(response, attempt) {
+    const header = Number(response.headers.get("retry-after"));
+    const seconds = Number.isFinite(header) && header > 0 ? header : 2 ** (attempt + 1);
+    return Math.min(seconds * 1_000, MAX_RETRY_DELAY_MS);
+}
+function bodyOf(response) {
+    if (!response.body)
+        return (async function* () { })();
+    return response.body;
+}
+function apiError(provider, payload) {
+    const error = asRecord(payload.error);
+    const details = String(error.message ?? JSON.stringify(payload));
+    return t("backend.apiHttp", { provider, status: String(error.type ?? "stream"), details });
+}
+function trimSlash(url) {
+    return url.replace(/\/+$/, "");
+}

package/dist/backends/index.js

@@ -0,0 +1,10 @@
+import { AGENT_SPECS, createAgentBackend, defaultRunner } from "./agent-cli.js";
+import { createApiBackend } from "./api.js";
+import { createManualBackend } from "./manual.js";
+export function createBackend(name, deps = {}) {
+    if (name === "api")
+        return createApiBackend(deps.api);
+    if (name === "manual")
+        return createManualBackend(deps.manual);
+    return createAgentBackend(AGENT_SPECS[name], deps.runner ?? defaultRunner);
+}

package/dist/backends/manual.js

@@ -0,0 +1,52 @@
+import { rm } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { createInterface } from "node:readline";
+import clipboard from "clipboardy";
+import { UserError } from "../core/errors.js";
+import { readTextIfExists, writeText } from "../core/fs.js";
+import { baePaths } from "../core/paths.js";
+import { t } from "../i18n/index.js";
+const defaultIo = {
+    input: process.stdin,
+    output: process.stdout,
+    copy: (text) => clipboard.write(text),
+};
+export function createManualBackend(overrides = {}) {
+    const io = { ...defaultIo, ...overrides };
+    return {
+        name: "manual",
+        run: async (prompt, options) => {
+            const tmp = baePaths(options.cwd).tmp;
+            const promptFile = join(tmp, "prompt.md");
+            const responseFile = join(tmp, "response.md");
+            await writeText(promptFile, prompt);
+            await rm(responseFile, { force: true });
+            const copied = await io.copy(prompt).then(() => true, () => false);
+            const show = (path) => relative(options.cwd, path).split("\\").join("/");
+            io.output.write(`${prompt}\n\n`);
+            io.output.write(`${t(copied ? "manual.copied" : "manual.notCopied", { path: show(promptFile) })}\n`);
+            if (options.interactive) {
+                io.output.write(`${t("manual.awaitingDone")}\n`);
+                await readPasted(io.input);
+                return "";
+            }
+            io.output.write(`${t("manual.awaitingResponse", { path: show(responseFile) })}\n`);
+            const pasted = await readPasted(io.input);
+            const answer = pasted || ((await readTextIfExists(responseFile)) ?? "");
+            if (!answer.trim())
+                throw new UserError(t("manual.emptyResponse", { path: show(responseFile) }));
+            return answer;
+        },
+    };
+}
+async function readPasted(input) {
+    const reader = createInterface({ input, terminal: false });
+    const lines = [];
+    for await (const line of reader) {
+        if (lines.length === 0 && line.trim() === "")
+            break;
+        lines.push(line);
+    }
+    reader.close();
+    return lines.join("\n");
+}

package/dist/backends/sse.js

@@ -0,0 +1,24 @@
+export async function* readSse(body) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for await (const chunk of body) {
+        buffer += decoder.decode(chunk, { stream: true }).replace(/\r\n?/g, "\n");
+        const parts = buffer.split("\n\n");
+        buffer = parts.pop() ?? "";
+        yield* parts.map(parseEvent).filter((event) => event !== undefined);
+    }
+    const last = parseEvent(buffer + decoder.decode());
+    if (last)
+        yield last;
+}
+function parseEvent(block) {
+    let event = "message";
+    const data = [];
+    for (const line of block.split("\n")) {
+        if (line.startsWith("event:"))
+            event = line.slice(6).trim();
+        else if (line.startsWith("data:"))
+            data.push(line.slice(5).replace(/^ /, ""));
+    }
+    return data.length > 0 ? { event, data: data.join("\n") } : undefined;
+}

package/dist/backends/types.js

@@ -0,0 +1 @@
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./cli.js";
+process.exitCode = await main(process.argv, process.cwd());

package/dist/cli.js

@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs";
+import { Command, CommanderError, Option } from "commander";
+import pc from "picocolors";
+import { defaultDeps } from "./commands/context.js";
+import { runInit } from "./commands/init.js";
+import { runNext } from "./commands/next.js";
+import { runPlan } from "./commands/plan.js";
+import { runReplan } from "./commands/replan.js";
+import { runReview } from "./commands/review.js";
+import { runStatus } from "./commands/status.js";
+import { BACKENDS } from "./config/schema.js";
+import { resolveSettings } from "./config/settings.js";
+import { readConfig } from "./config/store.js";
+import { ExitCode, UserError } from "./core/errors.js";
+import { isLang, LANGS, setLang, t } from "./i18n/index.js";
+import { ONLY_GROUPS } from "./plan/filter.js";
+export async function main(argv, cwd, deps = {}) {
+    const config = await readConfig(cwd).catch(() => undefined);
+    setLang(resolveSettings({ lang: scanLang(argv) }, config).lang);
+    try {
+        await buildProgram({ ...defaultDeps(), ...deps }, cwd).parseAsync(argv);
+        return 0;
+    }
+    catch (error) {
+        return report(error);
+    }
+}
+export function buildProgram(deps, cwd) {
+    const context = (command) => ({
+        ...deps,
+        cwd,
+        flags: command.optsWithGlobals(),
+    });
+    const program = new Command("builder-assistant-engineer")
+        .description(t("program.description"))
+        .exitOverride()
+        .version(readVersion(), "-v, --version", t("option.version"))
+        .helpOption("-h, --help", t("option.help"))
+        .helpCommand("help [command]", t("command.help"))
+        .addOption(new Option("--backend <name>", t("option.backend")).choices(BACKENDS))
+        .addOption(new Option("--lang <code>", t("option.lang")).choices(LANGS))
+        .option("--dry-run", t("option.dryRun"))
+        .option("-y, --yes", t("option.yes"));
+    program
+        .command("init")
+        .description(t("command.init"))
+        .option("--brief <paths>", t("option.brief"))
+        .action((options, command) => runInit(context(command), options));
+    program
+        .command("plan")
+        .description(t("command.plan"))
+        .addOption(new Option("--only <group>", t("option.only")).choices(ONLY_GROUPS))
+        .action((options, command) => runPlan(context(command), options));
+    program
+        .command("next")
+        .description(t("command.next"))
+        .option("--headless", t("option.headless"))
+        .option("--accept-finding <id>", t("option.acceptFinding"), collect, [])
+        .option("--allow-skip", t("option.allowSkip"))
+        .action((options, command) => runNext(context(command), options));
+    program
+        .command("status")
+        .description(t("command.status"))
+        .action((_options, command) => runStatus(context(command)));
+    program
+        .command("replan")
+        .description(t("command.replan"))
+        .action((_options, command) => runReplan(context(command)));
+    program
+        .command("review")
+        .description(t("command.review"))
+        .argument("[task]", t("argument.task"))
+        .option("--accept-finding <id>", t("option.acceptFinding"), collect, [])
+        .action((task, options, command) => runReview(context(command), task, options));
+    return program;
+}
+function collect(value, previous) {
+    return [...previous, value];
+}
+export function scanLang(argv) {
+    const index = argv.findIndex((arg) => arg === "--lang" || arg.startsWith("--lang="));
+    if (index === -1)
+        return undefined;
+    const arg = argv[index] ?? "";
+    const value = arg.includes("=") ? arg.slice(arg.indexOf("=") + 1) : argv[index + 1];
+    return isLang(value) ? value : undefined;
+}
+function report(error) {
+    if (error instanceof CommanderError)
+        return error.exitCode;
+    if (error instanceof ExitCode)
+        return error.code;
+    if (error instanceof UserError) {
+        process.stderr.write(`${pc.red(error.message)}\n`);
+        return 1;
+    }
+    process.stderr.write(`${pc.red(t("error.unexpected"))}\n`);
+    process.stderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    return 1;
+}
+function readVersion() {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return pkg.version;
+}

package/dist/commands/context.js

@@ -0,0 +1,12 @@
+import { createBackend } from "../backends/index.js";
+import { createClackPrompter } from "../ui/clack.js";
+export function defaultDeps() {
+    return {
+        prompter: createClackPrompter(),
+        createBackend: (name) => createBackend(name),
+        env: process.env,
+        print: (text) => {
+            process.stdout.write(text);
+        },
+    };
+}