@kody-ade/engine 0.1.0

package/dist/stages/review.js

@@ -0,0 +1,32 @@
+import * as fs from "fs";
+import * as path from "path";
+import { STAGES } from "../definitions.js";
+import { logger } from "../logger.js";
+import { executeAgentStage } from "./agent.js";
+export async function executeReviewWithFix(ctx, def) {
+    if (ctx.input.dryRun) {
+        return { outcome: "completed", retries: 0 };
+    }
+    const reviewDef = STAGES.find((s) => s.name === "review");
+    const reviewFixDef = STAGES.find((s) => s.name === "review-fix");
+    const reviewResult = await executeAgentStage(ctx, reviewDef);
+    if (reviewResult.outcome !== "completed") {
+        return reviewResult;
+    }
+    const reviewFile = path.join(ctx.taskDir, "review.md");
+    if (!fs.existsSync(reviewFile)) {
+        return { outcome: "failed", retries: 0, error: "review.md not found" };
+    }
+    const content = fs.readFileSync(reviewFile, "utf-8");
+    const hasIssues = /\bfail\b/i.test(content) && !/pass/i.test(content);
+    if (!hasIssues) {
+        return reviewResult;
+    }
+    logger.info(`  review found issues, running review-fix...`);
+    const fixResult = await executeAgentStage(ctx, reviewFixDef);
+    if (fixResult.outcome !== "completed") {
+        return fixResult;
+    }
+    logger.info(`  re-running review after fix...`);
+    return executeAgentStage(ctx, reviewDef);
+}

package/dist/stages/ship.d.ts

@@ -0,0 +1,3 @@
+import type { StageDefinition, StageResult, PipelineContext } from "../types.js";
+export declare function buildPrBody(ctx: PipelineContext): string;
+export declare function executeShipStage(ctx: PipelineContext, _def: StageDefinition): StageResult;

package/dist/stages/ship.js

@@ -0,0 +1,154 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execFileSync } from "child_process";
+import { getCurrentBranch, getDefaultBranch, pushBranch, } from "../git-utils.js";
+import { postComment, createPR, } from "../github-api.js";
+import { getProjectConfig } from "../config.js";
+export function buildPrBody(ctx) {
+    const sections = [];
+    // What and why — from task.json
+    const taskJsonPath = path.join(ctx.taskDir, "task.json");
+    if (fs.existsSync(taskJsonPath)) {
+        try {
+            const raw = fs.readFileSync(taskJsonPath, "utf-8");
+            const cleaned = raw.replace(/^```json\s*\n?/m, "").replace(/\n?```\s*$/m, "");
+            const task = JSON.parse(cleaned);
+            if (task.description) {
+                sections.push(`## What\n\n${task.description}`);
+            }
+            if (task.scope?.length) {
+                sections.push(`\n## Scope\n\n${task.scope.map((s) => `- \`${s}\``).join("\n")}`);
+            }
+            sections.push(`\n**Type:** ${task.task_type ?? "unknown"} | **Risk:** ${task.risk_level ?? "unknown"}`);
+        }
+        catch { /* ignore parse errors */ }
+    }
+    // Changes — from review.md summary
+    const reviewPath = path.join(ctx.taskDir, "review.md");
+    if (fs.existsSync(reviewPath)) {
+        const review = fs.readFileSync(reviewPath, "utf-8");
+        const summaryMatch = review.match(/## Summary\s*\n([\s\S]*?)(?=\n## |\n*$)/);
+        if (summaryMatch) {
+            const summary = summaryMatch[1].trim();
+            if (summary) {
+                sections.push(`\n## Changes\n\n${summary}`);
+            }
+        }
+        const verdictMatch = review.match(/## Verdict:\s*(PASS|FAIL)/i);
+        if (verdictMatch) {
+            sections.push(`\n**Review:** ${verdictMatch[1].toUpperCase() === "PASS" ? "✅ PASS" : "❌ FAIL"}`);
+        }
+    }
+    // Verify result
+    const verifyPath = path.join(ctx.taskDir, "verify.md");
+    if (fs.existsSync(verifyPath)) {
+        const verify = fs.readFileSync(verifyPath, "utf-8");
+        if (/PASS/i.test(verify))
+            sections.push(`**Verify:** ✅ typecheck + tests + lint passed`);
+    }
+    // Plan — collapsible details
+    const planPath = path.join(ctx.taskDir, "plan.md");
+    if (fs.existsSync(planPath)) {
+        const plan = fs.readFileSync(planPath, "utf-8").trim();
+        if (plan) {
+            const truncated = plan.length > 800 ? plan.slice(0, 800) + "\n..." : plan;
+            sections.push(`\n<details><summary>📋 Implementation plan</summary>\n\n${truncated}\n</details>`);
+        }
+    }
+    // Closes issue
+    if (ctx.input.issueNumber) {
+        sections.push(`\nCloses #${ctx.input.issueNumber}`);
+    }
+    sections.push(`\n---\n🤖 Generated by Kody`);
+    return sections.join("\n");
+}
+export function executeShipStage(ctx, _def) {
+    const shipPath = path.join(ctx.taskDir, "ship.md");
+    if (ctx.input.dryRun) {
+        fs.writeFileSync(shipPath, "# Ship\n\nShip stage skipped — dry run.\n");
+        return { outcome: "completed", outputFile: "ship.md", retries: 0 };
+    }
+    // Local mode or no issue: skip git push + PR
+    if (ctx.input.local && !ctx.input.issueNumber) {
+        fs.writeFileSync(shipPath, "# Ship\n\nShip stage skipped — local mode, no issue number.\n");
+        return { outcome: "completed", outputFile: "ship.md", retries: 0 };
+    }
+    try {
+        const head = getCurrentBranch(ctx.projectDir);
+        const base = getDefaultBranch(ctx.projectDir);
+        pushBranch(ctx.projectDir);
+        // Resolve owner/repo
+        const config = getProjectConfig();
+        let owner = config.github?.owner;
+        let repo = config.github?.repo;
+        if (!owner || !repo) {
+            try {
+                const remoteUrl = execFileSync("git", ["remote", "get-url", "origin"], {
+                    encoding: "utf-8",
+                    cwd: ctx.projectDir,
+                }).trim();
+                const match = remoteUrl.match(/github\.com[/:]([^/]+)\/([^/.]+)/);
+                if (match) {
+                    owner = match[1];
+                    repo = match[2];
+                }
+            }
+            catch {
+                // Can't determine repo
+            }
+        }
+        // Derive PR title from task.json (preferred) or task.md (fallback)
+        let title = "Update";
+        const TYPE_PREFIX = {
+            feature: "feat",
+            bugfix: "fix",
+            refactor: "refactor",
+            docs: "docs",
+            chore: "chore",
+        };
+        const taskJsonPath = path.join(ctx.taskDir, "task.json");
+        if (fs.existsSync(taskJsonPath)) {
+            try {
+                const raw = fs.readFileSync(taskJsonPath, "utf-8");
+                const cleaned = raw.replace(/^```json\s*\n?/m, "").replace(/\n?```\s*$/m, "");
+                const task = JSON.parse(cleaned);
+                const prefix = TYPE_PREFIX[task.task_type] ?? "chore";
+                const taskTitle = task.title ?? "Update";
+                title = `${prefix}: ${taskTitle}`.slice(0, 72);
+            }
+            catch { /* fallback below */ }
+        }
+        if (title === "Update") {
+            const taskMdPath = path.join(ctx.taskDir, "task.md");
+            if (fs.existsSync(taskMdPath)) {
+                const content = fs.readFileSync(taskMdPath, "utf-8");
+                const firstLine = content.split("\n").find((l) => l.trim() && !l.startsWith("#") && !l.startsWith("*"));
+                if (firstLine)
+                    title = `chore: ${firstLine.trim()}`.slice(0, 72);
+            }
+        }
+        // Build rich PR body
+        const body = buildPrBody(ctx);
+        const pr = createPR(head, base, title, body);
+        if (pr) {
+            if (ctx.input.issueNumber && !ctx.input.local) {
+                try {
+                    postComment(ctx.input.issueNumber, `🎉 PR created: ${pr.url}`);
+                }
+                catch {
+                    // Fire and forget
+                }
+            }
+            fs.writeFileSync(shipPath, `# Ship\n\nPR created: ${pr.url}\nPR #${pr.number}\n`);
+        }
+        else {
+            fs.writeFileSync(shipPath, "# Ship\n\nPushed branch but failed to create PR.\n");
+        }
+        return { outcome: "completed", outputFile: "ship.md", retries: 0 };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        fs.writeFileSync(shipPath, `# Ship\n\nFailed: ${msg}\n`);
+        return { outcome: "failed", retries: 0, error: msg };
+    }
+}

package/dist/stages/verify.d.ts

@@ -0,0 +1,2 @@
+import type { StageDefinition, StageResult, PipelineContext } from "../types.js";
+export declare function executeVerifyWithAutofix(ctx: PipelineContext, def: StageDefinition): Promise<StageResult>;

package/dist/stages/verify.js

@@ -0,0 +1,94 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execFileSync } from "child_process";
+import { resolveModel } from "../context.js";
+import { getProjectConfig, FIX_COMMAND_TIMEOUT_MS } from "../config.js";
+import { parseCommand } from "../verify-runner.js";
+import { getRunnerForStage } from "../pipeline/runner-selection.js";
+import { postComment } from "../github-api.js";
+import { diagnoseFailure, getModifiedFiles } from "../observer.js";
+import { logger } from "../logger.js";
+import { executeAgentStage } from "./agent.js";
+import { executeGateStage } from "./gate.js";
+export async function executeVerifyWithAutofix(ctx, def) {
+    const maxAttempts = def.maxRetries ?? 2;
+    for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+        logger.info(`  verification attempt ${attempt + 1}/${maxAttempts + 1}`);
+        const gateResult = executeGateStage(ctx, def);
+        if (gateResult.outcome === "completed") {
+            return { ...gateResult, retries: attempt };
+        }
+        if (attempt < maxAttempts) {
+            // Read verify errors for diagnosis
+            const verifyPath = path.join(ctx.taskDir, "verify.md");
+            const errorOutput = fs.existsSync(verifyPath) ? fs.readFileSync(verifyPath, "utf-8") : "Unknown error";
+            // AI diagnosis — classify the failure
+            const modifiedFiles = getModifiedFiles(ctx.projectDir);
+            const defaultRunner = getRunnerForStage(ctx, "taskify"); // use cheap model
+            const diagnosis = await diagnoseFailure("verify", errorOutput, modifiedFiles, defaultRunner, resolveModel("cheap"));
+            if (diagnosis.classification === "infrastructure") {
+                logger.warn(`  Infrastructure issue: ${diagnosis.reason}`);
+                if (ctx.input.issueNumber && !ctx.input.local) {
+                    try {
+                        postComment(ctx.input.issueNumber, `⚠️ **Infrastructure issue detected:** ${diagnosis.reason}\n\n${diagnosis.resolution}`);
+                    }
+                    catch { /* fire-and-forget */ }
+                }
+                return { outcome: "completed", retries: attempt, error: `Skipped: ${diagnosis.reason}` };
+            }
+            if (diagnosis.classification === "pre-existing") {
+                logger.warn(`  Pre-existing issue: ${diagnosis.reason}`);
+                return { outcome: "completed", retries: attempt, error: `Skipped: ${diagnosis.reason}` };
+            }
+            if (diagnosis.classification === "abort") {
+                logger.error(`  Unrecoverable: ${diagnosis.reason}`);
+                return { outcome: "failed", retries: attempt, error: diagnosis.reason };
+            }
+            // fixable or retry — proceed with autofix
+            logger.info(`  Diagnosis: ${diagnosis.classification} — ${diagnosis.reason}`);
+            const config = getProjectConfig();
+            const runFix = (cmd) => {
+                if (!cmd)
+                    return;
+                const parts = parseCommand(cmd);
+                if (parts.length === 0)
+                    return;
+                try {
+                    execFileSync(parts[0], parts.slice(1), {
+                        stdio: "pipe",
+                        timeout: FIX_COMMAND_TIMEOUT_MS,
+                    });
+                }
+                catch {
+                    // Silently ignore fix failures
+                }
+            };
+            runFix(config.quality.lintFix);
+            runFix(config.quality.formatFix);
+            if (def.retryWithAgent) {
+                // Create new context with diagnosis guidance — don't mutate original
+                const autofixCtx = {
+                    ...ctx,
+                    input: {
+                        ...ctx.input,
+                        feedback: `${diagnosis.resolution}\n\n${ctx.input.feedback ?? ""}`.trim(),
+                    },
+                };
+                logger.info(`  running ${def.retryWithAgent} agent with diagnosis guidance...`);
+                await executeAgentStage(autofixCtx, {
+                    ...def,
+                    name: def.retryWithAgent,
+                    type: "agent",
+                    modelTier: "mid",
+                    timeout: 300_000,
+                    outputFile: undefined,
+                });
+            }
+        }
+    }
+    return {
+        outcome: "failed",
+        retries: maxAttempts,
+        error: "Verification failed after autofix attempts",
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+export type StageName = "taskify" | "plan" | "build" | "verify" | "review" | "review-fix" | "ship";
+export type StageType = "agent" | "gate" | "deterministic";
+export type PipelineState = "pending" | "running" | "completed" | "failed" | "timeout";
+export interface StageDefinition {
+    name: StageName;
+    type: StageType;
+    modelTier: "cheap" | "mid" | "strong";
+    timeout: number;
+    maxRetries: number;
+    outputFile?: string;
+    retryWithAgent?: string;
+}
+export interface StageState {
+    state: PipelineState;
+    startedAt?: string;
+    completedAt?: string;
+    retries: number;
+    error?: string;
+    outputFile?: string;
+}
+export interface PipelineStatus {
+    taskId: string;
+    state: "running" | "completed" | "failed";
+    stages: Record<StageName, StageState>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface StageResult {
+    outcome: "completed" | "failed" | "timed_out";
+    outputFile?: string;
+    error?: string;
+    retries: number;
+}
+export interface AgentResult {
+    outcome: "completed" | "failed" | "timed_out";
+    output?: string;
+    error?: string;
+}
+export interface AgentRunnerOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+}
+export interface AgentRunner {
+    run(stageName: string, prompt: string, model: string, timeout: number, taskDir: string, options?: AgentRunnerOptions): Promise<AgentResult>;
+    healthCheck(): Promise<boolean>;
+}
+export interface PipelineContext {
+    taskId: string;
+    taskDir: string;
+    projectDir: string;
+    runners: Record<string, AgentRunner>;
+    input: {
+        mode: "full" | "rerun" | "status";
+        fromStage?: string;
+        dryRun?: boolean;
+        issueNumber?: number;
+        feedback?: string;
+        local?: boolean;
+        complexity?: "low" | "medium" | "high";
+    };
+}

package/dist/types.js

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

package/dist/validators.d.ts

@@ -0,0 +1,8 @@
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+}
+export declare function stripFences(content: string): string;
+export declare function validateTaskJson(content: string): ValidationResult;
+export declare function validatePlanMd(content: string): ValidationResult;
+export declare function validateReviewMd(content: string): ValidationResult;

package/dist/validators.js

@@ -0,0 +1,42 @@
+const REQUIRED_TASK_FIELDS = [
+    "task_type",
+    "title",
+    "description",
+    "scope",
+    "risk_level",
+];
+export function stripFences(content) {
+    return content.replace(/^```json\s*\n?/m, "").replace(/\n?```\s*$/m, "");
+}
+export function validateTaskJson(content) {
+    try {
+        const parsed = JSON.parse(stripFences(content));
+        for (const field of REQUIRED_TASK_FIELDS) {
+            if (!(field in parsed)) {
+                return { valid: false, error: `Missing field: ${field}` };
+            }
+        }
+        return { valid: true };
+    }
+    catch (err) {
+        return {
+            valid: false,
+            error: `Invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+export function validatePlanMd(content) {
+    if (content.length < 10) {
+        return { valid: false, error: "Plan is too short (< 10 chars)" };
+    }
+    if (!/^##\s+\w+/m.test(content)) {
+        return { valid: false, error: "Plan has no markdown h2 sections" };
+    }
+    return { valid: true };
+}
+export function validateReviewMd(content) {
+    if (/pass/i.test(content) || /fail/i.test(content)) {
+        return { valid: true };
+    }
+    return { valid: false, error: "Review must contain 'pass' or 'fail'" };
+}

package/dist/verify-runner.d.ts

@@ -0,0 +1,11 @@
+export interface VerifyResult {
+    pass: boolean;
+    errors: string[];
+    summary: string[];
+}
+/**
+ * Parse a command string into [executable, ...args], respecting quoted arguments.
+ * e.g., 'pnpm -s "test:unit"' → ["pnpm", "-s", "test:unit"]
+ */
+export declare function parseCommand(cmd: string): string[];
+export declare function runQualityGates(taskDir: string, projectRoot?: string): VerifyResult;

package/dist/verify-runner.js

@@ -0,0 +1,110 @@
+import { execFileSync } from "child_process";
+import { getProjectConfig, VERIFY_COMMAND_TIMEOUT_MS } from "./config.js";
+import { logger } from "./logger.js";
+function isExecError(err) {
+    return typeof err === "object" && err !== null;
+}
+/**
+ * Parse a command string into [executable, ...args], respecting quoted arguments.
+ * e.g., 'pnpm -s "test:unit"' → ["pnpm", "-s", "test:unit"]
+ */
+export function parseCommand(cmd) {
+    const parts = [];
+    let current = "";
+    let inQuote = null;
+    for (const ch of cmd) {
+        if (inQuote) {
+            if (ch === inQuote) {
+                inQuote = null;
+            }
+            else {
+                current += ch;
+            }
+        }
+        else if (ch === '"' || ch === "'") {
+            inQuote = ch;
+        }
+        else if (/\s/.test(ch)) {
+            if (current) {
+                parts.push(current);
+                current = "";
+            }
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current)
+        parts.push(current);
+    if (inQuote)
+        logger.warn(`Unclosed quote in command: ${cmd}`);
+    return parts;
+}
+function runCommand(cmd, cwd, timeout) {
+    const parts = parseCommand(cmd);
+    if (parts.length === 0) {
+        return { success: true, output: "", timedOut: false };
+    }
+    try {
+        const output = execFileSync(parts[0], parts.slice(1), {
+            cwd,
+            timeout,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, FORCE_COLOR: "0" },
+        });
+        return { success: true, output: output ?? "", timedOut: false };
+    }
+    catch (err) {
+        const stdout = isExecError(err) ? err.stdout ?? "" : "";
+        const stderr = isExecError(err) ? err.stderr ?? "" : "";
+        const killed = isExecError(err) ? !!err.killed : false;
+        return { success: false, output: `${stdout}${stderr}`, timedOut: killed };
+    }
+}
+function parseErrors(output) {
+    const errors = [];
+    for (const line of output.split("\n")) {
+        if (/error|Error|ERROR|failed|Failed|FAIL|warning:|Warning:|WARN/i.test(line)) {
+            errors.push(line.slice(0, 500));
+        }
+    }
+    return errors;
+}
+function extractSummary(output, cmdName) {
+    const summaryPatterns = /Test Suites|Tests|Coverage|ERRORS|FAILURES|success|completed/i;
+    const lines = output.split("\n").filter((l) => summaryPatterns.test(l));
+    return lines.slice(-3).map((l) => `[${cmdName}] ${l.trim()}`);
+}
+export function runQualityGates(taskDir, projectRoot) {
+    const config = getProjectConfig();
+    const cwd = projectRoot ?? process.cwd();
+    const allErrors = [];
+    const allSummary = [];
+    let allPass = true;
+    const commands = [
+        { name: "typecheck", cmd: config.quality.typecheck },
+        { name: "test", cmd: config.quality.testUnit },
+    ];
+    if (config.quality.lint) {
+        commands.push({ name: "lint", cmd: config.quality.lint });
+    }
+    for (const { name, cmd } of commands) {
+        if (!cmd)
+            continue;
+        logger.info(`  Running ${name}: ${cmd}`);
+        const result = runCommand(cmd, cwd, VERIFY_COMMAND_TIMEOUT_MS);
+        if (result.timedOut) {
+            allErrors.push(`${name}: timed out after ${VERIFY_COMMAND_TIMEOUT_MS / 1000}s`);
+            allPass = false;
+            continue;
+        }
+        if (!result.success) {
+            allPass = false;
+            const errors = parseErrors(result.output);
+            allErrors.push(...errors.map((e) => `[${name}] ${e}`));
+        }
+        allSummary.push(...extractSummary(result.output, name));
+    }
+    return { pass: allPass, errors: allErrors, summary: allSummary };
+}