builder-assistant-engineer 0.2.0

package/dist/next/start.js

@@ -0,0 +1,179 @@
+import { saveCommands } from "../commands/shared.js";
+import { bashPath } from "../core/bash.js";
+import { ExitCode } from "../core/errors.js";
+import { gitPaths, headCommit, isGitRepo } from "../core/git.js";
+import { ensureGitignore } from "../core/gitignore.js";
+import { isTestFile } from "../digest/baseline.js";
+import { clearActive, prepareCapture, readActive, readCapture, saveCapture, } from "../gates/capture.js";
+import { checkContract, collectProtected, restoreContract } from "../gates/contract.js";
+import { enforceContract } from "../gates/enforce.js";
+import { refusal } from "../gates/gate.js";
+import { captureIgnore } from "../gates/ignore-rules.js";
+import { baselineFrom, runSuite, suiteCommands, unusableBaseline, } from "../gates/regression.js";
+import { readSources, testRunners } from "../gates/runners.js";
+import { guardState } from "../gates/state-guard.js";
+import { t } from "../i18n/index.js";
+import { capturedTask } from "../review/run.js";
+import { scopePaths } from "../review/scope.js";
+import { recordAttempt } from "../tasks/attempts.js";
+import { verificationCommands, verificationScript } from "../tasks/schema.js";
+import { setTaskStatus } from "../tasks/status.js";
+export function checksFor(task, config) {
+    return {
+        commands: verificationCommands(task.body),
+        script: verificationScript(task.body),
+        suite: suiteCommands(config),
+    };
+}
+export async function recoverInterrupted(ctx, acceptance) {
+    const id = await readActive(ctx.cwd);
+    if (!id)
+        return;
+    const capture = await readCapture(ctx.cwd, id);
+    if (!capture) {
+        await clearActive(ctx.cwd);
+        return;
+    }
+    const contract = await enforceContract(ctx, capture, acceptance);
+    await setTaskStatus(ctx.cwd, capturedTask(capture), "in_progress");
+    await clearActive(ctx.cwd);
+    if (contract.blocked)
+        ctx.prompter.warn(t("contract.recovered", { id }));
+}
+export async function withSuiteCommands(ctx, config) {
+    if (config.gates.regression === "off" || config.commands.test || config.commands.lint) {
+        return config;
+    }
+    const commands = await saveCommands(ctx);
+    if (!commands.test && !commands.lint)
+        ctx.prompter.info(t("regression.noCommands"));
+    return { ...config, commands };
+}
+export async function start(ctx, config, task, options) {
+    const bash = await bashPath();
+    const refused = refusal(checksFor(task, config), {
+        unattended: options.unattended,
+        allow: config.verify.allow,
+        ...(bash ? { bash } : {}),
+    });
+    if (refused) {
+        await blockBeforeAgent(ctx, task, refused);
+        return undefined;
+    }
+    await ensureGitignore(ctx.cwd);
+    const previous = await readCapture(ctx.cwd, task.meta.id);
+    const reuse = previous && !previous.finished ? previous : undefined;
+    const skips = [...(reuse?.skips ?? [])];
+    const allow = (message) => allowOrStop(ctx, options, skips, message);
+    if (!reuse && task.meta.status === "in_progress")
+        allow(t("capture.lateStop", { id: task.meta.id }));
+    if (!reuse && !(await isGitRepo(ctx.cwd)))
+        allow(t("capture.noGit"));
+    if (reuse?.base && reuse.base !== (await headCommit(ctx.cwd))) {
+        ctx.prompter.warn(t("capture.headMoved", { id: task.meta.id }));
+    }
+    const excluded = new Set(reuse?.baseline?.excluded ?? []);
+    const fresh = !(await hasTestFiles(ctx.cwd));
+    const unrecognized = fresh
+        ? []
+        : (await unrecognizedTests(ctx.cwd, config)).filter((command) => !excluded.has(command));
+    for (const command of unrecognized)
+        allow(t("regression.unknownRunner", { command }));
+    let baseline = reuse?.baseline;
+    if (config.gates.regression === "full" && baseline === undefined) {
+        if (reuse)
+            allow(t("regression.lateStop", { id: task.meta.id }));
+        baseline = await recordBaseline(ctx, config, task, { ...options, unrecognized, fresh }, skips);
+    }
+    const started = await setTaskStatus(ctx.cwd, task, "in_progress");
+    const capture = await prepareCapture(ctx.cwd, config, started);
+    const late = !reuse && task.meta.status === "in_progress";
+    Object.assign(capture, { skips, ...(baseline ? { baseline } : {}), ...(late ? { late } : {}) });
+    await saveCapture(ctx.cwd, capture);
+    return capture;
+}
+async function unrecognizedTests(cwd, config) {
+    const sources = await readSources(cwd);
+    return suiteCommands(config)
+        .filter((item) => item.key === "test" && testRunners(item.command, sources).length === 0)
+        .map((item) => item.command);
+}
+async function recordBaseline(ctx, config, task, options, skips) {
+    const suite = suiteCommands(config).filter((item) => !options.unrecognized.includes(item.command));
+    if (suite.length === 0)
+        return baselineFrom([], options.unrecognized);
+    ctx.prompter.note(suite.map((item) => `$ ${item.command}`).join("\n"), t("regression.baselineTitle"));
+    if (!ctx.flags.yes && !(await ctx.prompter.confirm(t("regression.confirm"), true))) {
+        allowOrStop(ctx, options, skips, t("regression.declinedStop"));
+        return { skipped: true, commands: {}, excluded: [] };
+    }
+    const guard = await guardState(ctx.cwd);
+    const before = await collectProtected(ctx.cwd, {
+        suite: suite.map((item) => item.command),
+        verification: verificationCommands(task.body),
+        own: scopePaths(task),
+    });
+    const results = await runSuite(ctx.cwd, suite, ctx.print, config.gates.timeoutMinutes * 60_000);
+    const tampered = await guard.verify();
+    const changed = await checkContract(ctx.cwd, {
+        ...before,
+        ignore: await captureIgnore(ctx.cwd),
+        taskPath: task.path,
+    });
+    if (tampered.length > 0 || changed.length > 0) {
+        await restoreContract(ctx.cwd, changed);
+        const files = [...tampered, ...changed.map((change) => change.path)].join(", ");
+        ctx.prompter.warn(t("regression.baselineTampered", { files }));
+        ctx.prompter.outro(t("skip.stopped"));
+        throw new ExitCode(1);
+    }
+    for (const result of results.filter((item) => item.exitCode !== 0)) {
+        ctx.prompter.warn(t("regression.preexisting", { command: result.command, code: result.exitCode }));
+    }
+    const found = unusableBaseline(results, task.meta.tests === "fix");
+    const absent = options.fresh
+        ? found.filter((result) => result.key === "test" && result.exitCode !== -1)
+        : [];
+    const unusable = found.filter((result) => !absent.includes(result));
+    for (const result of absent) {
+        ctx.prompter.info(t("regression.noTestsYet", { command: result.command }));
+    }
+    for (const result of unusable)
+        allowOrStop(ctx, options, skips, unusableMessage(result));
+    return baselineFrom(results, [...options.unrecognized, ...unusable.map((result) => result.command)], absent.map((result) => result.command));
+}
+async function hasTestFiles(cwd) {
+    const files = (await gitPaths(cwd, ["ls-files", "--cached", "--others", "--exclude-standard"])) ?? [];
+    return files.some((path) => isTestFile(path));
+}
+function unusableMessage(result) {
+    const vars = { command: result.command, code: result.exitCode };
+    if (result.unrecognized)
+        return t("regression.unknownRunner", vars);
+    if (result.key === "test" && result.exitCode === 0)
+        return t("regression.noCounts", vars);
+    return t("regression.unusable", vars);
+}
+function allowOrStop(ctx, options, skips, message) {
+    if (!options.allowSkip) {
+        ctx.prompter.warn(message);
+        ctx.prompter.outro(t("skip.stopped"));
+        throw new ExitCode(1);
+    }
+    skips.push(message);
+    ctx.prompter.warn(t("skip.used", { what: message }));
+}
+async function blockBeforeAgent(ctx, task, reason) {
+    ctx.prompter.warn(reason);
+    await setTaskStatus(ctx.cwd, task, "blocked");
+    await recordAttempt(ctx.cwd, task.meta.id, {
+        startedAt: new Date().toISOString(),
+        durationMs: 0,
+        headless: false,
+        outcome: "blocked",
+        stage: "refused",
+        regressions: [],
+        reason,
+    });
+    ctx.prompter.outro(t("next.refusedBlocked", { id: task.meta.id }));
+}

package/dist/plan/continuation.js

@@ -0,0 +1,40 @@
+import { MARKER } from "./parser.js";
+export function rawBlocks(text) {
+    const blocks = [];
+    let open;
+    for (const match of text.matchAll(MARKER)) {
+        const marker = match[1] ?? "";
+        const index = match.index ?? 0;
+        if (marker.startsWith("END ")) {
+            if (open && marker.slice(4) === kindOf(open.marker)) {
+                const end = index + match[0].length;
+                blocks.push({ key: open.marker, raw: text.slice(open.start, end).trim(), closed: true });
+            }
+            open = undefined;
+        }
+        else if (!open) {
+            open = { marker, start: index };
+        }
+    }
+    if (open)
+        blocks.push({ key: open.marker, raw: text.slice(open.start).trim(), closed: false });
+    return blocks;
+}
+export function findTruncation(text) {
+    const last = rawBlocks(text).at(-1);
+    if (!last || last.closed)
+        return undefined;
+    const complete = rawBlocks(text)
+        .filter((block) => block.closed)
+        .map((block) => block.raw)
+        .join("\n\n");
+    return { complete, marker: `<<<${last.key}>>>` };
+}
+export function mergeContinuation(complete, continuation) {
+    const seen = new Set(rawBlocks(complete).map((block) => block.key));
+    const extra = rawBlocks(continuation).filter((block) => !seen.has(block.key));
+    return [complete, ...extra.map((block) => block.raw)].filter(Boolean).join("\n\n");
+}
+function kindOf(marker) {
+    return marker.startsWith("FILE:") ? "FILE" : marker;
+}

package/dist/plan/evidence.js

@@ -0,0 +1,239 @@
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import { readTextIfExists } from "../core/fs.js";
+import { baseName, extensionOf, languageOf } from "../digest/files.js";
+import { scanFiles } from "../digest/walk.js";
+import { sectionText } from "../tasks/schema.js";
+const CODE_SPAN = /`([^`\n]+)`([ \t]*\((?:new|nuevo|nueva)\))?/gi;
+const NEW_INSIDE = /^(.+?)\s+\((?:new|nuevo|nueva)\)$/i;
+const PATH_TOKEN = /^(?:\.\/)?([\w@.-]+(?:\/[\w@.[\]()-]+)*)\/?(?::(\d+)(?::\d+)?(?:-(\d+))?|#L(\d+)(?:-L?(\d+))?)?$/;
+const DOMAIN = /^[a-z0-9-]+(\.[a-z0-9-]+)+$/i;
+const EVIDENCE_FILES = [
+    /^docs\/plan\/02-architecture\.md$/,
+    /^docs\/plan\/03-decisions\/[^/]+\.md$/,
+];
+const EXTENSIONS = new Set("md mdx json jsonc yaml yml toml ini cfg conf env txt lock xml gradle mod sum csv properties example sample template tmpl mk"
+    .split(" ")
+    .map((extension) => `.${extension}`));
+const GENERATED_ROOTS = new Set([
+    "dist",
+    "build",
+    "out",
+    "target",
+    "coverage",
+    "node_modules",
+    "vendor",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".next",
+    ".nuxt",
+]);
+const KNOWN_FILES = new Set([
+    "Dockerfile",
+    "Makefile",
+    "Procfile",
+    "Jenkinsfile",
+    "Gemfile",
+    "Rakefile",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "package.json",
+    "tsconfig.json",
+    "pyproject.toml",
+    "requirements.txt",
+    "setup.py",
+    "go.mod",
+    "go.sum",
+    "Cargo.toml",
+    "composer.json",
+    "pom.xml",
+    "build.gradle",
+    ".env.example",
+    ".gitignore",
+    ".gitattributes",
+    ".editorconfig",
+    ".dockerignore",
+    ".nvmrc",
+    ".npmrc",
+    ".python-version",
+    ".tool-versions",
+]);
+const TS_SOURCES = {
+    ".js": [".ts", ".tsx"],
+    ".jsx": [".tsx"],
+    ".mjs": [".mts"],
+    ".cjs": [".cts"],
+};
+const MAX_BARE_CANDIDATES = 20;
+export async function findUnverified(cwd, plan) {
+    return (await checkCitations(cwd, plan)).unverified;
+}
+export async function checkCitations(cwd, plan) {
+    const repo = await indexRepo(cwd);
+    const planned = plannedPaths(plan.files);
+    const written = new Map([
+        ...plan.files.map((file) => [file.path, file.content]),
+        ...plan.tasks.map((task) => [task.path, task.text]),
+    ]);
+    const roots = new Set([...repo.roots, ...[...planned].map((path) => path.split("/")[0] ?? "")]);
+    const unverified = [];
+    const seen = new Set();
+    for (const { source, text } of evidenceSources(plan)) {
+        for (const citation of extractCitations(text, source, roots)) {
+            const key = `${source}|${citation.path}|${citation.line ?? ""}|${citation.endLine ?? ""}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const problem = await verify(cwd, citation, repo, planned, written);
+            if (problem)
+                unverified.push(problem);
+        }
+    }
+    return { checked: seen.size, unverified };
+}
+export function evidenceSources(plan) {
+    return [
+        ...plan.files
+            .filter((file) => EVIDENCE_FILES.some((pattern) => pattern.test(file.path)))
+            .map((file) => ({ source: file.path, text: file.content })),
+        ...plan.tasks.map((task) => ({
+            source: task.path,
+            text: sectionText(task.body, "context") ?? "",
+        })),
+    ];
+}
+export function extractCitations(text, source, roots) {
+    const citations = [];
+    for (const match of text.matchAll(CODE_SPAN)) {
+        const span = (match[1] ?? "").trim();
+        if (match[2] || NEW_INSIDE.test(span))
+            continue;
+        const citation = toCitation(span, roots);
+        if (citation)
+            citations.push({ source, ...citation });
+    }
+    return citations;
+}
+export function plannedPaths(files) {
+    const planned = new Set(files.map((file) => file.path));
+    for (const file of files) {
+        for (const match of file.content.matchAll(CODE_SPAN)) {
+            const span = (match[1] ?? "").trim();
+            const inside = NEW_INSIDE.exec(span)?.[1];
+            const path = normalize(match[2] ? span : inside);
+            if (path)
+                planned.add(path);
+        }
+    }
+    return planned;
+}
+export function describeUnverified(item) {
+    const detail = item.lines === undefined ? "" : ` (the file has ${item.lines} lines)`;
+    return `\`${item.text}\` in ${item.source}${detail}`;
+}
+function toCitation(span, roots) {
+    if (/[\s*$<>{}|]|:\/\//.test(span))
+        return undefined;
+    const match = PATH_TOKEN.exec(span);
+    const path = match?.[1];
+    if (!match || !path)
+        return undefined;
+    const segments = path.split("/");
+    const first = segments[0] ?? "";
+    const skipped = segments.some((segment) => segment === "." || segment === "..") ||
+        GENERATED_ROOTS.has(first) ||
+        (segments.length > 1 && DOMAIN.test(first));
+    if (skipped)
+        return undefined;
+    const start = match[2] ?? match[4];
+    const end = match[3] ?? match[5];
+    const line = start ? Number(start) : undefined;
+    const endLine = end ? Number(end) : undefined;
+    const checked = segments.length === 1
+        ? KNOWN_FILES.has(path) || (line !== undefined && hasFileExtension(path))
+        : hasFileExtension(path) || roots.has(first);
+    if (!checked)
+        return undefined;
+    return {
+        text: span,
+        path,
+        ...(line !== undefined ? { line } : {}),
+        ...(endLine !== undefined ? { endLine } : {}),
+    };
+}
+function hasFileExtension(path) {
+    return languageOf(path) !== undefined || EXTENSIONS.has(extensionOf(path));
+}
+function normalize(span) {
+    const path = span
+        ?.replace(/^\.\//, "")
+        .replace(/\/$/, "")
+        .replace(/:\d+(-\d+)?$/, "");
+    return path && !/\s/.test(path) ? path : undefined;
+}
+async function verify(cwd, citation, repo, planned, written) {
+    const bare = !citation.path.includes("/");
+    const own = written.get(citation.path);
+    if (citation.line !== undefined && own !== undefined) {
+        const lines = own.split(/\r?\n/).length - (own.endsWith("\n") ? 1 : 0);
+        const last = citation.endLine ?? citation.line;
+        return citation.line >= 1 && last >= citation.line && last <= lines
+            ? undefined
+            : { ...citation, lines };
+    }
+    if (citation.line !== undefined)
+        return verifyLines(cwd, citation, repo, bare);
+    const path = await existing(cwd, citation.path);
+    if (path || (bare && repo.names.has(citation.path)))
+        return undefined;
+    const isPlanned = planned.has(citation.path) ||
+        [...planned].some((item) => item.startsWith(`${citation.path}/`) || (bare && baseName(item) === citation.path));
+    return isPlanned ? undefined : citation;
+}
+async function verifyLines(cwd, citation, repo, bare) {
+    const line = citation.line ?? 0;
+    const last = citation.endLine ?? line;
+    if (line < 1 || last < line)
+        return citation;
+    const direct = await existing(cwd, citation.path);
+    const candidates = direct
+        ? [direct]
+        : bare
+            ? (repo.names.get(citation.path) ?? []).slice(0, MAX_BARE_CANDIDATES)
+            : [];
+    if (candidates.length === 0)
+        return citation;
+    const counts = await Promise.all(candidates.map((path) => lineCount(cwd, path)));
+    const lines = Math.max(...counts);
+    return last <= lines ? undefined : { ...citation, lines };
+}
+async function existing(cwd, path) {
+    for (const candidate of [path, ...sourceAlternatives(path)]) {
+        if (await stat(join(cwd, ...candidate.split("/"))).catch(() => undefined))
+            return candidate;
+    }
+    return undefined;
+}
+function sourceAlternatives(path) {
+    const extension = extensionOf(path);
+    const stem = path.slice(0, path.length - extension.length);
+    return (TS_SOURCES[extension] ?? []).map((replacement) => `${stem}${replacement}`);
+}
+async function lineCount(cwd, path) {
+    const target = join(cwd, ...path.split("/"));
+    if (!(await stat(target).catch(() => undefined))?.isFile())
+        return 0;
+    const text = (await readTextIfExists(target)) ?? "";
+    return text.split(/\r?\n/).length - (text.endsWith("\n") ? 1 : 0);
+}
+async function indexRepo(cwd) {
+    const { files } = await scanFiles(cwd);
+    const names = new Map();
+    for (const file of files) {
+        const name = baseName(file.path);
+        names.set(name, [...(names.get(name) ?? []), file.path]);
+    }
+    return { names, roots: new Set(files.map((file) => file.path.split("/")[0] ?? "")) };
+}

package/dist/plan/filter.js

@@ -0,0 +1,20 @@
+export const ONLY_GROUPS = ["plan", "agents", "memory"];
+const MEMORY_FILES = new Set(["AGENTS.md", "CLAUDE.md", "GEMINI.md"]);
+export function groupOf(path) {
+    if (MEMORY_FILES.has(path))
+        return "memory";
+    return path.startsWith("docs/plan/") ? "plan" : "agents";
+}
+export function isTargeted(path, targets) {
+    if (path === "CLAUDE.md" || path.startsWith(".claude/"))
+        return targets.includes("claude-code");
+    if (path === "GEMINI.md")
+        return targets.includes("gemini");
+    if (path.startsWith(".opencode/"))
+        return targets.includes("opencode");
+    return true;
+}
+export function selectFiles(files, selection) {
+    return files.filter((file) => isTargeted(file.path, selection.targets) &&
+        (selection.only === undefined || groupOf(file.path) === selection.only));
+}