@toolbaux/guardian 0.1.0

package/dist/commands/feature-context.js

@@ -0,0 +1,116 @@
+/**
+ * `specguard feature-context` — generate a filtered, self-contained context packet
+ * for implementing a single feature.
+ *
+ * Analogous to `chapter-context` in the book workflow: given a feature spec YAML,
+ * outputs only the endpoints, models, enums, and patterns relevant to that feature —
+ * plus one-hop neighbours (endpoints that share a model with the declared ones).
+ *
+ * Reads:  feature spec YAML + codebase-intelligence.json
+ * Writes: specs-out/machine/feature-context/<spec-name>.json (or --output)
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { parseFeatureSpec } from "../schema/feature-spec.js";
+import { loadCodebaseIntelligence } from "../extract/codebase-intel.js";
+import { getOutputLayout } from "../output-layout.js";
+export async function runFeatureContext(options) {
+    const specPath = path.resolve(options.spec);
+    const specsDir = path.resolve(options.specs);
+    const layout = getOutputLayout(specsDir);
+    // Load and validate feature spec
+    const raw = await fs.readFile(specPath, "utf8");
+    const parsed = yaml.load(raw);
+    const spec = parseFeatureSpec(parsed);
+    // Load codebase intelligence
+    const intelPath = path.join(layout.machineDir, "codebase-intelligence.json");
+    const intel = await loadCodebaseIntelligence(intelPath).catch(() => {
+        throw new Error(`Could not load codebase-intelligence.json from ${intelPath}. Run \`specguard intel --specs ${options.specs}\` first.`);
+    });
+    // Build filtered context
+    const context = buildFeatureContext(spec, intel);
+    // Determine output path
+    const specName = path.basename(specPath).replace(/\.ya?ml$/, "");
+    const outputPath = options.output
+        ? path.resolve(options.output)
+        : path.join(layout.machineDir, "feature-context", `${specName}.json`);
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, JSON.stringify(context, null, 2), "utf8");
+    console.log(`Wrote ${outputPath}`);
+    console.log(`  ${Object.keys(context.declared_endpoints).length} declared endpoints, ` +
+        `${Object.keys(context.neighbour_endpoints).length} neighbours, ` +
+        `${Object.keys(context.affected_models).length} models, ` +
+        `${Object.keys(context.affected_enums).length} enums`);
+}
+function buildFeatureContext(spec, intel) {
+    // Declared endpoints
+    const declaredEndpoints = {};
+    for (const epKey of spec.affected_endpoints) {
+        if (intel.api_registry[epKey]) {
+            declaredEndpoints[epKey] = intel.api_registry[epKey];
+        }
+    }
+    // Affected models (declared + inferred from endpoint model usage)
+    const modelNames = new Set(spec.affected_models);
+    // Enrich: collect models used by declared endpoints via service_calls heuristic
+    // (we don't have full endpoint→model map in intel — use request/response schema names)
+    for (const ep of Object.values(declaredEndpoints)) {
+        if (ep.request_schema)
+            modelNames.add(ep.request_schema);
+        if (ep.response_schema)
+            modelNames.add(ep.response_schema);
+    }
+    const affectedModels = {};
+    for (const name of modelNames) {
+        if (intel.model_registry[name]) {
+            affectedModels[name] = intel.model_registry[name];
+        }
+    }
+    // One-hop neighbours: other endpoints that share any affected model
+    const neighbourEndpoints = {};
+    for (const [key, ep] of Object.entries(intel.api_registry)) {
+        if (declaredEndpoints[key])
+            continue; // already declared
+        const requestMatch = ep.request_schema && modelNames.has(ep.request_schema);
+        const responseMatch = ep.response_schema && modelNames.has(ep.response_schema);
+        if (requestMatch || responseMatch) {
+            neighbourEndpoints[key] = ep;
+        }
+    }
+    // Affected enums: those whose names appear in model field lists
+    const affectedEnums = {};
+    for (const model of Object.values(affectedModels)) {
+        for (const field of model.fields) {
+            for (const [enumName, enumEntry] of Object.entries(intel.enum_registry)) {
+                if (field.toLowerCase().includes(enumName.toLowerCase())) {
+                    affectedEnums[enumName] = enumEntry;
+                }
+            }
+        }
+    }
+    // Pattern definitions for declared patterns
+    const patternDefs = intel.pattern_registry.patterns.filter((p) => spec.pattern.includes(p.id));
+    return {
+        meta: {
+            feature: spec.feature,
+            description: spec.description,
+            patterns: spec.pattern,
+            tradeoff: spec.tradeoff,
+            failure_risk: spec.failure_risk,
+            maps_to: spec.maps_to,
+            generated_at: new Date().toISOString(),
+        },
+        declared_endpoints: declaredEndpoints,
+        neighbour_endpoints: neighbourEndpoints,
+        affected_models: affectedModels,
+        affected_enums: affectedEnums,
+        pattern_definitions: patternDefs,
+        write_guide: {
+            rule: "Only use endpoints, models, and patterns listed in this file. Do not invent endpoints or models not listed here.",
+            endpoint_lookup: "declared_endpoints contains the exact endpoints this feature adds or modifies.",
+            model_lookup: "affected_models contains all ORM models this feature reads or writes.",
+            pattern_lookup: "pattern_definitions describes the implementation pattern(s) to follow.",
+        },
+    };
+}

package/dist/commands/generate.js

@@ -0,0 +1,339 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { buildSnapshots } from "../extract/index.js";
+import { renderContextBlock } from "../extract/context-block.js";
+import { getOutputLayout } from "../output-layout.js";
+import { analyzeDepth } from "../extract/analyzers/depth.js";
+export async function runGenerate(options) {
+    if (!options.aiContext) {
+        throw new Error("`specguard generate` currently supports `--ai-context` only.");
+    }
+    const outputRoot = path.resolve(options.output ?? "specs-out");
+    const layout = getOutputLayout(outputRoot);
+    const { architecture, ux } = await buildSnapshots({
+        projectRoot: options.projectRoot,
+        backendRoot: options.backendRoot,
+        frontendRoot: options.frontendRoot,
+        output: outputRoot,
+        includeFileGraph: true,
+        configPath: options.configPath
+    });
+    // Load persisted Structural Intelligence reports emitted by `specguard extract`
+    const siReports = await loadStructuralIntelligenceReports(layout.machineDir);
+    // If a --focus query is provided, prepend a real-time SI report for that query
+    if (options.focus) {
+        try {
+            const focusReport = analyzeDepth({
+                query: options.focus,
+                modules: architecture.modules,
+                moduleGraph: architecture.dependencies.module_graph,
+                fileGraph: architecture.dependencies.file_graph,
+                circularDependencies: architecture.analysis.circular_dependencies
+            });
+            const alreadyPresent = siReports.some((r) => r.feature === focusReport.feature);
+            if (!alreadyPresent)
+                siReports.unshift(focusReport);
+        }
+        catch {
+            // Non-fatal — just skip injection for this query
+        }
+    }
+    // Inject into the architecture object so renderContextBlock can consume it
+    architecture.structural_intelligence = siReports;
+    const pythonImportReferences = await pickPythonImportReferences(architecture);
+    // Load product description from README if available
+    let productDescription = "";
+    const readmeCandidates = [
+        path.join(path.resolve(architecture.project.workspace_root), "README.md"),
+        path.join(path.resolve(architecture.project.workspace_root), "readme.md"),
+    ];
+    for (const candidate of readmeCandidates) {
+        try {
+            const raw = await fs.readFile(candidate, "utf8");
+            // Extract first H1 + first paragraph (concise product description)
+            const lines = raw.split("\n");
+            const descLines = [];
+            let pastH1 = false;
+            for (const line of lines) {
+                if (line.startsWith("# ")) {
+                    pastH1 = true;
+                    descLines.push(line.replace(/^# /, "").trim());
+                    continue;
+                }
+                if (!pastH1)
+                    continue;
+                if (line.startsWith("## "))
+                    break; // stop at first H2
+                if (line.trim())
+                    descLines.push(line.trim());
+                if (descLines.length >= 4)
+                    break; // max 4 lines
+            }
+            productDescription = descLines.join(" ").slice(0, 300);
+            break;
+        }
+        catch {
+            // Not found
+        }
+    }
+    const content = renderAiContextMarkdown(architecture, ux, {
+        focusQuery: options.focus,
+        maxLines: normalizeMaxLines(options.maxLines),
+        pythonImportReferences,
+        structuralIntelligence: siReports,
+        productDescription
+    });
+    const outputPath = path.join(layout.machineDir, "architecture-context.md");
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, content, "utf8");
+    console.log(`Wrote ${outputPath}`);
+}
+async function loadStructuralIntelligenceReports(machineDir) {
+    const siPath = path.join(machineDir, "structural-intelligence.json");
+    try {
+        const raw = await fs.readFile(siPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // File doesn't exist yet — run extract first
+    }
+    return [];
+}
+function renderAiContextMarkdown(architecture, ux, options) {
+    const keyModules = pickKeyBackendModules(architecture);
+    const coreOrmModels = pickCoreOrmModels(architecture);
+    const fallbackSchemas = pickTopSchemas(architecture);
+    const lines = [];
+    lines.push("<!-- guardian:ai-context -->");
+    lines.push("# Architecture Context");
+    lines.push("");
+    lines.push("Use this file as compact architectural memory for AI coding tools. It is optimized for machine consumption and omits full docs, charts, and raw snapshots.");
+    lines.push("");
+    lines.push(`Project: **${architecture.project.name}**`);
+    if (options?.productDescription) {
+        lines.push(`Description: ${options.productDescription}`);
+    }
+    lines.push(`Workspace: \`${architecture.project.workspace_root}\``);
+    lines.push(`Backend: \`${architecture.project.backend_root}\``);
+    lines.push(`Frontend: \`${architecture.project.frontend_root}\``);
+    lines.push("");
+    if (keyModules.length > 0) {
+        lines.push(`Key backend modules: ${keyModules.join(", ")}`);
+    }
+    if (coreOrmModels.length > 0) {
+        lines.push(`Core data models: ${coreOrmModels.join(", ")}`);
+    }
+    else if (fallbackSchemas.length > 0) {
+        lines.push(`Core data models: no ORM models detected; top schemas: ${fallbackSchemas.join(", ")}`);
+    }
+    else {
+        lines.push("Core data models: none detected");
+    }
+    lines.push("");
+    if ((options?.pythonImportReferences?.length ?? 0) > 0) {
+        lines.push("## Backend Import Reference");
+        lines.push("");
+        for (const reference of options?.pythonImportReferences ?? []) {
+            lines.push(`- ${reference.name} -> \`${reference.statement}\` (${reference.kind}, ${reference.file})`);
+        }
+        lines.push("");
+    }
+    lines.push(renderContextBlock(architecture, ux, {
+        focusQuery: options?.focusQuery,
+        maxLines: options?.maxLines ?? 80,
+        structuralIntelligence: options?.structuralIntelligence
+    }));
+    lines.push("");
+    lines.push("## Usage");
+    lines.push("");
+    lines.push("- Paste into `CLAUDE.md`, `.cursorrules`, or a coding prompt.");
+    lines.push("- Prefer this file over the human-readable docs when minimizing AI context size.");
+    lines.push("- For deeper lookup, run `guardian search --query \"<feature>\"`.");
+    lines.push("- Regenerate after major structural changes.");
+    lines.push("");
+    lines.push("<!-- /guardian:ai-context -->");
+    return lines.join("\n");
+}
+function pickKeyBackendModules(architecture) {
+    return architecture.modules
+        .filter((module) => module.type === "backend")
+        .map((module) => ({
+        id: module.id,
+        score: module.endpoints.length * 3 + module.files.length + module.imports.length
+    }))
+        .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+        .slice(0, 4)
+        .map((module) => module.id);
+}
+function pickCoreOrmModels(architecture) {
+    const usageCounts = new Map();
+    for (const usage of architecture.endpoint_model_usage) {
+        for (const model of usage.models) {
+            usageCounts.set(model.name, (usageCounts.get(model.name) ?? 0) + 1);
+        }
+    }
+    return architecture.data_models
+        .filter((model) => model.framework !== "pydantic")
+        .map((model) => ({
+        name: model.name,
+        score: (usageCounts.get(model.name) ?? 0) * 4 +
+            model.relationships.length * 2 +
+            Math.min(model.fields.length, 10)
+    }))
+        .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+        .slice(0, 5)
+        .map((model) => model.name);
+}
+function pickTopSchemas(architecture) {
+    const schemaMentions = new Map();
+    for (const endpoint of architecture.endpoints) {
+        if (endpoint.request_schema) {
+            schemaMentions.set(endpoint.request_schema, (schemaMentions.get(endpoint.request_schema) ?? 0) + 1);
+        }
+        if (endpoint.response_schema) {
+            schemaMentions.set(endpoint.response_schema, (schemaMentions.get(endpoint.response_schema) ?? 0) + 1);
+        }
+    }
+    return architecture.data_models
+        .filter((model) => model.framework === "pydantic")
+        .map((model) => ({
+        name: model.name,
+        score: (schemaMentions.get(model.name) ?? 0) * 3 + Math.min(model.fields.length, 8)
+    }))
+        .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+        .slice(0, 5)
+        .map((model) => model.name);
+}
+function normalizeMaxLines(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+async function pickPythonImportReferences(architecture) {
+    const backendRoot = path.resolve(architecture.project.backend_root);
+    const workspaceRoot = path.resolve(architecture.project.workspace_root);
+    const topSchemas = pickTopSchemas(architecture).slice(0, 3);
+    const topOrmModels = pickCoreOrmModels(architecture).slice(0, 2);
+    const candidateNames = Array.from(new Set([...topSchemas, ...topOrmModels]));
+    if (candidateNames.length === 0) {
+        return [];
+    }
+    const modelByName = new Map(architecture.data_models.map((model) => [model.name, model]));
+    const importSpecifiers = await collectPythonImportSpecifiers(backendRoot, new Set(candidateNames));
+    const references = [];
+    for (const name of candidateNames) {
+        const model = modelByName.get(name);
+        if (!model) {
+            continue;
+        }
+        const specifier = importSpecifiers.get(name);
+        const derivedModulePath = derivePythonModulePath(model.file, workspaceRoot, backendRoot);
+        const statement = specifier
+            ? `from ${specifier} import ${name}`
+            : derivedModulePath
+                ? `from ${derivedModulePath} import ${name}`
+                : "";
+        if (!statement) {
+            continue;
+        }
+        references.push({
+            name,
+            statement,
+            file: model.file,
+            kind: model.framework === "pydantic" ? "schema" : "model"
+        });
+    }
+    return references;
+}
+async function collectPythonImportSpecifiers(backendRoot, targetNames) {
+    const counts = new Map();
+    const files = await listPythonFiles(backendRoot);
+    for (const file of files) {
+        let content = "";
+        try {
+            content = await fs.readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const usage of extractPythonFromImports(content)) {
+            for (const symbol of usage.symbols) {
+                if (!targetNames.has(symbol)) {
+                    continue;
+                }
+                const specifierCounts = counts.get(symbol) ?? new Map();
+                specifierCounts.set(usage.specifier, (specifierCounts.get(usage.specifier) ?? 0) + 1);
+                counts.set(symbol, specifierCounts);
+            }
+        }
+    }
+    const winners = new Map();
+    for (const [symbol, specifierCounts] of counts.entries()) {
+        const best = Array.from(specifierCounts.entries()).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0];
+        if (best) {
+            winners.set(symbol, best);
+        }
+    }
+    return winners;
+}
+async function listPythonFiles(root) {
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listPythonFiles(fullPath)));
+            continue;
+        }
+        if (entry.isFile() && fullPath.endsWith(".py")) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function extractPythonFromImports(content) {
+    const imports = [];
+    for (const match of content.matchAll(/^\s*from\s+([.\w]+)\s+import\s+(.+)$/gm)) {
+        let namesPart = match[2].split("#")[0]?.trim() ?? "";
+        namesPart = namesPart.replace(/[()]/g, "");
+        const symbols = namesPart
+            .split(",")
+            .map((name) => name.trim())
+            .filter(Boolean)
+            .map((name) => name.split(/\s+as\s+/i)[0]?.trim() ?? "")
+            .filter((name) => name.length > 0 && name !== "*");
+        if (symbols.length > 0) {
+            imports.push({ specifier: match[1], symbols });
+        }
+    }
+    return imports;
+}
+function derivePythonModulePath(relativeFile, workspaceRoot, backendRoot) {
+    const absoluteFile = path.resolve(workspaceRoot, relativeFile);
+    const relativeToBackend = path.relative(backendRoot, absoluteFile).replace(/\\/g, "/");
+    if (!relativeToBackend || relativeToBackend.startsWith("../") || !relativeToBackend.endsWith(".py")) {
+        return null;
+    }
+    const withoutExt = relativeToBackend.replace(/\.py$/, "");
+    const normalized = withoutExt.endsWith("/__init__")
+        ? withoutExt.slice(0, -"/__init__".length)
+        : withoutExt;
+    if (!normalized) {
+        return null;
+    }
+    const segments = normalized.split("/").filter(Boolean);
+    if (segments.some((segment) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(segment))) {
+        return null;
+    }
+    return segments.join(".");
+}

package/dist/commands/guard.js

@@ -0,0 +1,182 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { runConstraints } from "./constraints.js";
+import { runSimulate } from "./simulate.js";
+import { buildSnapshots } from "../extract/index.js";
+import { renderContextBlock } from "../extract/context-block.js";
+import { logResolvedProjectPaths, resolveProjectPaths } from "../project-discovery.js";
+export async function runGuard(options) {
+    const resolved = await resolveProjectPaths({
+        projectRoot: options.projectRoot,
+        backendRoot: options.backendRoot,
+        frontendRoot: options.frontendRoot,
+        configPath: options.configPath
+    });
+    const config = resolved.config;
+    logResolvedProjectPaths(resolved);
+    const constraintsPath = path.resolve("specs-out/machine/constraints.json");
+    await runConstraints({
+        projectRoot: resolved.workspaceRoot,
+        backendRoot: resolved.backendRoot,
+        frontendRoot: resolved.frontendRoot,
+        output: constraintsPath,
+        configPath: options.configPath
+    });
+    const constraints = await loadConstraints(constraintsPath);
+    const basePrompt = constraints && typeof constraints["prompt"] === "string" ? constraints["prompt"] : "";
+    if (options.printContext) {
+        const { architecture, ux } = await buildSnapshots({
+            projectRoot: resolved.workspaceRoot,
+            backendRoot: resolved.backendRoot,
+            frontendRoot: resolved.frontendRoot,
+            output: "specs-out",
+            includeFileGraph: true,
+            configPath: options.configPath
+        });
+        const context = renderGuardContext({
+            task: options.task,
+            constraintPrompt: basePrompt,
+            contextBlock: renderContextBlock(architecture, ux, {
+                focusQuery: options.task,
+                maxLines: 140
+            })
+        });
+        console.log(context);
+        return;
+    }
+    const prompt = buildGuardPrompt(basePrompt, options.task, config.llm?.promptTemplate);
+    const promptPath = path.resolve(options.promptOutput ?? "specs-out/machine/guard.prompt.txt");
+    await fs.mkdir(path.dirname(promptPath), { recursive: true });
+    await fs.writeFile(promptPath, prompt);
+    console.log(`Wrote ${promptPath}`);
+    const llmCommand = options.llmCommand || config.llm?.command;
+    if (!llmCommand) {
+        console.log("No LLM command configured. Provide llm.command in config or --llm-command.");
+        return;
+    }
+    const { command, args } = resolveCommand(llmCommand, config.llm?.args ?? []);
+    const patch = await runLlmCommand(command, args, prompt, config.llm?.timeoutMs ?? 120000);
+    if (!patch.trim()) {
+        throw new Error("LLM command returned empty output.");
+    }
+    const patchPath = path.resolve(options.patchOutput ?? "specs-out/machine/guard.patch");
+    await fs.mkdir(path.dirname(patchPath), { recursive: true });
+    await fs.writeFile(patchPath, patch);
+    console.log(`Wrote ${patchPath}`);
+    const simulationPath = path.resolve(options.simulationOutput ?? "specs-out/machine/drift.simulation.json");
+    await runSimulate({
+        projectRoot: resolved.workspaceRoot,
+        backendRoot: resolved.backendRoot,
+        frontendRoot: resolved.frontendRoot,
+        output: simulationPath,
+        configPath: options.configPath,
+        patch: patchPath,
+        mode: options.mode ?? config.guard?.mode ?? "soft"
+    });
+}
+function renderGuardContext(params) {
+    const lines = [];
+    lines.push("<!-- guardian:guard-context -->");
+    lines.push("## Requested Task");
+    lines.push(params.task.trim() || "(not provided)");
+    lines.push("");
+    lines.push("## Constraint Summary");
+    const constraints = extractConstraintLines(params.constraintPrompt);
+    if (constraints.length > 0) {
+        lines.push(...constraints);
+    }
+    else {
+        lines.push("- No explicit constraint summary available.");
+    }
+    lines.push("");
+    lines.push(params.contextBlock.trim());
+    lines.push("<!-- /guardian:guard-context -->");
+    return lines.join("\n");
+}
+function extractConstraintLines(prompt) {
+    const lines = prompt
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const explicit = lines.filter((line) => line.startsWith("- "));
+    if (explicit.length > 0) {
+        return explicit;
+    }
+    return lines.slice(0, 6).map((line) => `- ${line}`);
+}
+async function loadConstraints(constraintsPath) {
+    try {
+        const raw = await fs.readFile(constraintsPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function buildGuardPrompt(basePrompt, task, template) {
+    const trimmedTask = task?.trim() ?? "";
+    const defaultPrompt = [
+        basePrompt.trim(),
+        "",
+        "User Task:",
+        trimmedTask || "(not provided)",
+        "",
+        "Return a unified diff patch only."
+    ]
+        .filter(Boolean)
+        .join("\n");
+    if (!template || template.trim().length === 0) {
+        return defaultPrompt;
+    }
+    const withConstraints = template.includes("{{constraints}}")
+        ? template.replace(/{{constraints}}/g, basePrompt.trim())
+        : `${template.trim()}\n\n${basePrompt.trim()}`;
+    return withConstraints.includes("{{task}}")
+        ? withConstraints.replace(/{{task}}/g, trimmedTask)
+        : `${withConstraints.trim()}\n\nUser Task:\n${trimmedTask || "(not provided)"}\n`;
+}
+function resolveCommand(command, args) {
+    if (args.length > 0) {
+        return { command, args };
+    }
+    const parts = command.trim().split(/\s+/).filter(Boolean);
+    if (parts.length <= 1) {
+        return { command, args };
+    }
+    return { command: parts[0], args: parts.slice(1) };
+}
+function runLlmCommand(command, args, prompt, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: process.platform === "win32"
+        });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            reject(new Error("LLM command timed out."));
+        }, timeoutMs);
+        child.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        child.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                reject(new Error(`LLM command failed (${code}): ${stderr.trim()}`));
+                return;
+            }
+            resolve(stdout);
+        });
+        child.stdin.write(prompt);
+        child.stdin.end();
+    });
+}