@kody-ade/engine 0.1.0

package/dist/ci/parse-inputs.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parses @kody / /kody comment body into structured inputs.
+ * Run by the parse job in GitHub Actions.
+ * Reads from env, writes to $GITHUB_OUTPUT.
+ */
+export {};

package/dist/ci/parse-inputs.js

@@ -0,0 +1,76 @@
+/**
+ * Parses @kody / /kody comment body into structured inputs.
+ * Run by the parse job in GitHub Actions.
+ * Reads from env, writes to $GITHUB_OUTPUT.
+ */
+import * as fs from "fs";
+const outputFile = process.env.GITHUB_OUTPUT;
+const triggerType = process.env.TRIGGER_TYPE ?? "dispatch";
+function output(key, value) {
+    if (outputFile) {
+        fs.appendFileSync(outputFile, `${key}=${value}\n`);
+    }
+    console.log(`${key}=${value}`);
+}
+// For workflow_dispatch, pass through inputs
+if (triggerType === "dispatch") {
+    output("task_id", process.env.INPUT_TASK_ID ?? "");
+    output("mode", process.env.INPUT_MODE ?? "full");
+    output("from_stage", process.env.INPUT_FROM_STAGE ?? "");
+    output("issue_number", process.env.INPUT_ISSUE_NUMBER ?? "");
+    output("feedback", process.env.INPUT_FEEDBACK ?? "");
+    output("valid", process.env.INPUT_TASK_ID ? "true" : "false");
+    output("trigger_type", "dispatch");
+    process.exit(0);
+}
+// For issue_comment, parse the comment body
+const commentBody = process.env.COMMENT_BODY ?? "";
+const issueNumber = process.env.ISSUE_NUMBER ?? "";
+// Match: @kody [mode] [task-id] [--from stage] [--feedback "text"]
+const kodyMatch = commentBody.match(/(?:@kody|\/kody)\s*(.*)/i);
+if (!kodyMatch) {
+    output("valid", "false");
+    output("trigger_type", "comment");
+    process.exit(0);
+}
+const parts = kodyMatch[1].trim().split(/\s+/);
+const validModes = ["full", "rerun", "status"];
+let mode = "full";
+let taskId = "";
+let fromStage = "";
+let feedback = "";
+let i = 0;
+// First arg: mode or task-id
+if (parts[i] && validModes.includes(parts[i])) {
+    mode = parts[i];
+    i++;
+}
+// Second arg: task-id
+if (parts[i] && !parts[i].startsWith("--")) {
+    taskId = parts[i];
+    i++;
+}
+// Named args
+while (i < parts.length) {
+    if (parts[i] === "--from" && parts[i + 1]) {
+        fromStage = parts[i + 1];
+        i += 2;
+    }
+    else if (parts[i] === "--feedback" && parts[i + 1]) {
+        // Collect quoted feedback
+        const rest = parts.slice(i + 1).join(" ");
+        const quoted = rest.match(/^"([^"]*)"/);
+        feedback = quoted ? quoted[1] : parts[i + 1];
+        break;
+    }
+    else {
+        i++;
+    }
+}
+output("task_id", taskId);
+output("mode", mode);
+output("from_stage", fromStage);
+output("issue_number", issueNumber);
+output("feedback", feedback);
+output("valid", taskId ? "true" : "false");
+output("trigger_type", "comment");

package/dist/ci/parse-safety.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Validates that a comment trigger is safe to execute.
+ * Run by the parse job in GitHub Actions.
+ * Reads from env, writes to $GITHUB_OUTPUT.
+ */
+export {};

package/dist/ci/parse-safety.js

@@ -0,0 +1,22 @@
+/**
+ * Validates that a comment trigger is safe to execute.
+ * Run by the parse job in GitHub Actions.
+ * Reads from env, writes to $GITHUB_OUTPUT.
+ */
+import * as fs from "fs";
+const ALLOWED_ASSOCIATIONS = ["COLLABORATOR", "MEMBER", "OWNER"];
+const association = process.env.COMMENT_AUTHOR_ASSOCIATION ?? "";
+const outputFile = process.env.GITHUB_OUTPUT;
+function output(key, value) {
+    if (outputFile) {
+        fs.appendFileSync(outputFile, `${key}=${value}\n`);
+    }
+    console.log(`${key}=${value}`);
+}
+if (!ALLOWED_ASSOCIATIONS.includes(association)) {
+    output("valid", "false");
+    output("reason", `Author association '${association}' not in allowlist: ${ALLOWED_ASSOCIATIONS.join(", ")}`);
+    process.exit(0);
+}
+output("valid", "true");
+output("reason", "");

package/dist/cli/args.d.ts

@@ -0,0 +1,13 @@
+export interface CliInput {
+    command: "run" | "rerun" | "fix" | "status";
+    taskId?: string;
+    task?: string;
+    fromStage?: string;
+    dryRun?: boolean;
+    cwd?: string;
+    issueNumber?: number;
+    feedback?: string;
+    local?: boolean;
+    complexity?: "low" | "medium" | "high";
+}
+export declare function parseArgs(): CliInput;

package/dist/cli/args.js

@@ -0,0 +1,42 @@
+const isCI = !!process.env.GITHUB_ACTIONS;
+function getArg(args, flag) {
+    const idx = args.indexOf(flag);
+    if (idx !== -1 && args[idx + 1] && !args[idx + 1].startsWith("--")) {
+        return args[idx + 1];
+    }
+    return undefined;
+}
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+export function parseArgs() {
+    const args = process.argv.slice(2);
+    if (hasFlag(args, "--help") || hasFlag(args, "-h") || args.length === 0) {
+        console.log(`Usage:
+  kody run    --task-id <id> [--task "<desc>"] [--cwd <path>] [--issue-number <n>] [--complexity low|medium|high] [--feedback "<text>"] [--local] [--dry-run]
+  kody rerun  --task-id <id> --from <stage> [--cwd <path>] [--issue-number <n>]
+  kody fix    --task-id <id> [--cwd <path>] [--issue-number <n>] [--feedback "<text>"]
+  kody status --task-id <id> [--cwd <path>]
+  kody --help`);
+        process.exit(0);
+    }
+    const command = args[0];
+    if (!["run", "rerun", "fix", "status"].includes(command)) {
+        console.error(`Unknown command: ${command}`);
+        process.exit(1);
+    }
+    const issueStr = getArg(args, "--issue-number") ?? process.env.ISSUE_NUMBER;
+    const localFlag = hasFlag(args, "--local");
+    return {
+        command,
+        taskId: getArg(args, "--task-id") ?? process.env.TASK_ID,
+        task: getArg(args, "--task"),
+        fromStage: getArg(args, "--from") ?? process.env.FROM_STAGE,
+        dryRun: hasFlag(args, "--dry-run") || process.env.DRY_RUN === "true",
+        cwd: getArg(args, "--cwd"),
+        issueNumber: issueStr ? parseInt(issueStr, 10) : undefined,
+        feedback: getArg(args, "--feedback") ?? process.env.FEEDBACK,
+        local: localFlag || (!isCI && !hasFlag(args, "--no-local")),
+        complexity: (getArg(args, "--complexity") ?? process.env.COMPLEXITY),
+    };
+}

package/dist/cli/litellm.d.ts

@@ -0,0 +1,2 @@
+export declare function checkLitellmHealth(url: string): Promise<boolean>;
+export declare function tryStartLitellm(url: string, projectDir: string): Promise<ReturnType<typeof import("child_process").spawn> | null>;

package/dist/cli/litellm.js

@@ -0,0 +1,85 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execFileSync } from "child_process";
+import { logger } from "../logger.js";
+export async function checkLitellmHealth(url) {
+    try {
+        const response = await fetch(`${url}/health`, { signal: AbortSignal.timeout(3000) });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function tryStartLitellm(url, projectDir) {
+    const configPath = path.join(projectDir, "litellm-config.yaml");
+    if (!fs.existsSync(configPath)) {
+        logger.warn("litellm-config.yaml not found — cannot start proxy");
+        return null;
+    }
+    // Extract port from URL
+    const portMatch = url.match(/:(\d+)/);
+    const port = portMatch ? portMatch[1] : "4000";
+    // Check if litellm is installed
+    try {
+        execFileSync("litellm", ["--version"], { timeout: 5000, stdio: "pipe" });
+    }
+    catch {
+        try {
+            execFileSync("python3", ["-m", "litellm", "--version"], { timeout: 5000, stdio: "pipe" });
+        }
+        catch {
+            logger.warn("litellm not installed (pip install 'litellm[proxy]')");
+            return null;
+        }
+    }
+    logger.info(`Starting LiteLLM proxy on port ${port}...`);
+    // Determine command
+    let cmd;
+    let args;
+    try {
+        execFileSync("litellm", ["--version"], { timeout: 5000, stdio: "pipe" });
+        cmd = "litellm";
+        args = ["--config", configPath, "--port", port];
+    }
+    catch {
+        cmd = "python3";
+        args = ["-m", "litellm", "--config", configPath, "--port", port];
+    }
+    // Load API key env vars from project .env (only *_API_KEY patterns)
+    const dotenvPath = path.join(projectDir, ".env");
+    const dotenvVars = {};
+    if (fs.existsSync(dotenvPath)) {
+        for (const line of fs.readFileSync(dotenvPath, "utf-8").split("\n")) {
+            const match = line.match(/^([A-Z_][A-Z0-9_]*_API_KEY)=(.*)$/);
+            if (match)
+                dotenvVars[match[1]] = match[2];
+        }
+        if (Object.keys(dotenvVars).length > 0) {
+            logger.info(`  Loaded API keys: ${Object.keys(dotenvVars).join(", ")}`);
+        }
+    }
+    const { spawn } = await import("child_process");
+    const child = spawn(cmd, args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: true,
+        env: { ...process.env, ...dotenvVars },
+    });
+    // Capture stderr for debugging
+    let proxyStderr = "";
+    child.stderr?.on("data", (chunk) => { proxyStderr += chunk.toString(); });
+    // Wait for health
+    for (let i = 0; i < 30; i++) {
+        await new Promise((r) => setTimeout(r, 2000));
+        if (await checkLitellmHealth(url)) {
+            logger.info(`LiteLLM proxy ready at ${url}`);
+            return child;
+        }
+    }
+    if (proxyStderr) {
+        logger.warn(`LiteLLM stderr: ${proxyStderr.slice(-1000)}`);
+    }
+    logger.warn("LiteLLM proxy failed to start within 60s");
+    child.kill();
+    return null;
+}

package/dist/cli/task-resolution.d.ts

@@ -0,0 +1,2 @@
+export declare function findLatestTaskForIssue(issueNumber: number, projectDir: string): string | null;
+export declare function generateTaskId(): string;

package/dist/cli/task-resolution.js

@@ -0,0 +1,41 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execFileSync } from "child_process";
+export function findLatestTaskForIssue(issueNumber, projectDir) {
+    const tasksDir = path.join(projectDir, ".tasks");
+    if (!fs.existsSync(tasksDir))
+        return null;
+    // Only consider directories (not files)
+    const allDirs = fs.readdirSync(tasksDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .sort()
+        .reverse();
+    // Direct match: tasks starting with issue number
+    const prefix = `${issueNumber}-`;
+    const direct = allDirs.find((d) => d.startsWith(prefix));
+    if (direct)
+        return direct;
+    // Fallback for PR comments: extract issue number from current git branch
+    // Branch format: <issueNum>--<slug> (e.g., 1031--security-8x-route)
+    try {
+        const branch = execFileSync("git", ["branch", "--show-current"], {
+            encoding: "utf-8", cwd: projectDir, timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        const branchIssueMatch = branch.match(/^(\d+)-/);
+        if (branchIssueMatch) {
+            const branchIssueNum = branchIssueMatch[1];
+            const branchPrefix = `${branchIssueNum}-`;
+            const fromBranch = allDirs.find((d) => d.startsWith(branchPrefix));
+            if (fromBranch)
+                return fromBranch;
+        }
+    }
+    catch { /* ignore */ }
+    return null;
+}
+export function generateTaskId() {
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${String(now.getFullYear()).slice(2)}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}

package/dist/config.d.ts

@@ -0,0 +1,49 @@
+export interface RunnerConfig {
+    type: "claude-code";
+}
+export interface KodyConfig {
+    quality: {
+        typecheck: string;
+        lint: string;
+        lintFix: string;
+        format: string;
+        formatFix: string;
+        testUnit: string;
+    };
+    git: {
+        defaultBranch: string;
+        userEmail?: string;
+        userName?: string;
+    };
+    github: {
+        owner: string;
+        repo: string;
+    };
+    paths: {
+        taskDir: string;
+    };
+    agent: {
+        runner?: string;
+        modelMap: {
+            cheap: string;
+            mid: string;
+            strong: string;
+        };
+        litellmUrl?: string;
+        usePerStageRouting?: boolean;
+        defaultRunner?: string;
+        runners?: Record<string, RunnerConfig>;
+        stageRunners?: Record<string, string>;
+    };
+}
+export declare const SIGKILL_GRACE_MS = 5000;
+export declare const MAX_PR_TITLE_LENGTH = 72;
+export declare const STDERR_TAIL_CHARS = 500;
+export declare const API_TIMEOUT_MS = 30000;
+export declare const DEFAULT_MAX_FIX_ATTEMPTS = 2;
+export declare const AGENT_RETRY_DELAY_MS = 2000;
+export declare const VERIFY_COMMAND_TIMEOUT_MS: number;
+export declare const FIX_COMMAND_TIMEOUT_MS: number;
+export declare function setConfigDir(dir: string): void;
+export declare function getProjectConfig(): KodyConfig;
+export declare function resetProjectConfig(): void;

package/dist/config.js

@@ -0,0 +1,72 @@
+import * as fs from "fs";
+import * as path from "path";
+import { logger } from "./logger.js";
+const DEFAULT_CONFIG = {
+    quality: {
+        typecheck: "pnpm -s tsc --noEmit",
+        lint: "pnpm -s lint",
+        lintFix: "pnpm lint:fix",
+        format: "pnpm -s format:check",
+        formatFix: "pnpm format:fix",
+        testUnit: "pnpm -s test",
+    },
+    git: {
+        defaultBranch: "dev",
+    },
+    github: {
+        owner: "",
+        repo: "",
+    },
+    paths: {
+        taskDir: ".tasks",
+    },
+    agent: {
+        runner: "claude-code",
+        defaultRunner: "claude",
+        modelMap: { cheap: "haiku", mid: "sonnet", strong: "opus" },
+    },
+};
+// Pipeline constants
+export const SIGKILL_GRACE_MS = 5000;
+export const MAX_PR_TITLE_LENGTH = 72;
+export const STDERR_TAIL_CHARS = 500;
+export const API_TIMEOUT_MS = 30_000;
+export const DEFAULT_MAX_FIX_ATTEMPTS = 2;
+export const AGENT_RETRY_DELAY_MS = 2000;
+export const VERIFY_COMMAND_TIMEOUT_MS = 5 * 60 * 1000;
+export const FIX_COMMAND_TIMEOUT_MS = 2 * 60 * 1000;
+let _config = null;
+let _configDir = null;
+export function setConfigDir(dir) {
+    _configDir = dir;
+    _config = null;
+}
+export function getProjectConfig() {
+    if (_config)
+        return _config;
+    const configPath = path.join(_configDir ?? process.cwd(), "kody.config.json");
+    if (fs.existsSync(configPath)) {
+        try {
+            const raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+            _config = {
+                quality: { ...DEFAULT_CONFIG.quality, ...raw.quality },
+                git: { ...DEFAULT_CONFIG.git, ...raw.git },
+                github: { ...DEFAULT_CONFIG.github, ...raw.github },
+                paths: { ...DEFAULT_CONFIG.paths, ...raw.paths },
+                agent: { ...DEFAULT_CONFIG.agent, ...raw.agent },
+            };
+        }
+        catch {
+            logger.warn("kody.config.json is invalid JSON — using defaults");
+            _config = { ...DEFAULT_CONFIG };
+        }
+    }
+    else {
+        _config = { ...DEFAULT_CONFIG };
+    }
+    return _config;
+}
+export function resetProjectConfig() {
+    _config = null;
+    _configDir = null;
+}

package/dist/context.d.ts

@@ -0,0 +1,4 @@
+export declare function readPromptFile(stageName: string): string;
+export declare function injectTaskContext(prompt: string, taskId: string, taskDir: string, feedback?: string): string;
+export declare function buildFullPrompt(stageName: string, taskId: string, taskDir: string, projectDir: string, feedback?: string): string;
+export declare function resolveModel(modelTier: string, stageName?: string): string;

package/dist/context.js

@@ -0,0 +1,83 @@
+import * as fs from "fs";
+import * as path from "path";
+import { readProjectMemory } from "./memory.js";
+import { getProjectConfig } from "./config.js";
+const DEFAULT_MODEL_MAP = {
+    cheap: "haiku",
+    mid: "sonnet",
+    strong: "opus",
+};
+const MAX_TASK_CONTEXT_PLAN = 1500;
+const MAX_TASK_CONTEXT_SPEC = 2000;
+export function readPromptFile(stageName) {
+    const scriptDir = new URL(".", import.meta.url).pathname;
+    // Try multiple resolution paths (dev: src/../prompts, prod: dist/bin/../../prompts)
+    const candidates = [
+        path.resolve(scriptDir, "..", "prompts", `${stageName}.md`),
+        path.resolve(scriptDir, "..", "..", "prompts", `${stageName}.md`),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate)) {
+            return fs.readFileSync(candidate, "utf-8");
+        }
+    }
+    throw new Error(`Prompt file not found: tried ${candidates.join(", ")}`);
+}
+export function injectTaskContext(prompt, taskId, taskDir, feedback) {
+    let context = `## Task Context\n`;
+    context += `Task ID: ${taskId}\n`;
+    context += `Task Directory: ${taskDir}\n`;
+    const taskMdPath = path.join(taskDir, "task.md");
+    if (fs.existsSync(taskMdPath)) {
+        const taskMd = fs.readFileSync(taskMdPath, "utf-8");
+        context += `\n## Task Description\n${taskMd}\n`;
+    }
+    const taskJsonPath = path.join(taskDir, "task.json");
+    if (fs.existsSync(taskJsonPath)) {
+        try {
+            const taskDef = JSON.parse(fs.readFileSync(taskJsonPath, "utf-8"));
+            context += `\n## Task Classification\n`;
+            context += `Type: ${taskDef.task_type ?? "unknown"}\n`;
+            context += `Title: ${taskDef.title ?? "unknown"}\n`;
+            context += `Risk: ${taskDef.risk_level ?? "unknown"}\n`;
+        }
+        catch {
+            // Ignore parse errors
+        }
+    }
+    const specPath = path.join(taskDir, "spec.md");
+    if (fs.existsSync(specPath)) {
+        const spec = fs.readFileSync(specPath, "utf-8");
+        const truncated = spec.slice(0, MAX_TASK_CONTEXT_SPEC);
+        context += `\n## Spec Summary\n${truncated}${spec.length > MAX_TASK_CONTEXT_SPEC ? "\n..." : ""}\n`;
+    }
+    const planPath = path.join(taskDir, "plan.md");
+    if (fs.existsSync(planPath)) {
+        const plan = fs.readFileSync(planPath, "utf-8");
+        const truncated = plan.slice(0, MAX_TASK_CONTEXT_PLAN);
+        context += `\n## Plan Summary\n${truncated}${plan.length > MAX_TASK_CONTEXT_PLAN ? "\n..." : ""}\n`;
+    }
+    if (feedback) {
+        context += `\n## Human Feedback\n${feedback}\n`;
+    }
+    return prompt.replace("{{TASK_CONTEXT}}", context);
+}
+export function buildFullPrompt(stageName, taskId, taskDir, projectDir, feedback) {
+    const memory = readProjectMemory(projectDir);
+    const promptTemplate = readPromptFile(stageName);
+    const prompt = injectTaskContext(promptTemplate, taskId, taskDir, feedback);
+    return memory ? `${memory}\n---\n\n${prompt}` : prompt;
+}
+export function resolveModel(modelTier, stageName) {
+    const config = getProjectConfig();
+    // Per-stage routing: use stage name as LiteLLM alias
+    if (config.agent.usePerStageRouting && stageName) {
+        return stageName;
+    }
+    // Config model map (may be LiteLLM aliases or direct model names)
+    const mapped = config.agent.modelMap[modelTier];
+    if (mapped)
+        return mapped;
+    // Fallback to defaults
+    return DEFAULT_MODEL_MAP[modelTier] ?? "sonnet";
+}

package/dist/definitions.d.ts

@@ -0,0 +1,3 @@
+import type { StageDefinition } from "./types.js";
+export declare const STAGES: StageDefinition[];
+export declare function getStage(name: string): StageDefinition | undefined;

package/dist/definitions.js

@@ -0,0 +1,59 @@
+export const STAGES = [
+    {
+        name: "taskify",
+        type: "agent",
+        modelTier: "cheap",
+        timeout: 300_000,
+        maxRetries: 1,
+        outputFile: "task.json",
+    },
+    {
+        name: "plan",
+        type: "agent",
+        modelTier: "strong",
+        timeout: 600_000,
+        maxRetries: 1,
+        outputFile: "plan.md",
+    },
+    {
+        name: "build",
+        type: "agent",
+        modelTier: "mid",
+        timeout: 1_200_000,
+        maxRetries: 1,
+    },
+    {
+        name: "verify",
+        type: "gate",
+        modelTier: "cheap",
+        timeout: 300_000,
+        maxRetries: 2,
+        retryWithAgent: "autofix",
+    },
+    {
+        name: "review",
+        type: "agent",
+        modelTier: "strong",
+        timeout: 600_000,
+        maxRetries: 1,
+        outputFile: "review.md",
+    },
+    {
+        name: "review-fix",
+        type: "agent",
+        modelTier: "mid",
+        timeout: 600_000,
+        maxRetries: 1,
+    },
+    {
+        name: "ship",
+        type: "deterministic",
+        modelTier: "cheap",
+        timeout: 120_000,
+        maxRetries: 1,
+        outputFile: "ship.md",
+    },
+];
+export function getStage(name) {
+    return STAGES.find((s) => s.name === name);
+}

package/dist/entry.d.ts

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