@kody-ade/kody-engine-lite 0.1.62 → 0.1.63

package/README.md

@@ -40,7 +40,7 @@ Most AI coding tools are **autocomplete** (Copilot) or **chat-based** (Cursor, C
   └──────────────────────────┬──────────────────────────────────┘
                              │
                 ┌────────────▼────────────┐
-                │  LOW?  skip to ④        │
+                │  LOW?  skip to ③        │
                 │  MEDIUM?  continue      │
                 │  HIGH?  continue        │
                 └────────────┬────────────┘
@@ -124,10 +124,10 @@ This analyzes your project and generates:
 - **Config** (`kody.config.json` — auto-detected quality commands, git, GitHub settings)
 - **Project memory** (`.kody/memory/` — architecture and conventions)
 - **Customized step files** (`.kody/steps/` — see below)
-- **GitHub labels** for lifecycle tracking
-
 Then commits and pushes everything.
 
+> **Note:** GitHub labels for lifecycle tracking are created automatically during `@kody bootstrap`.
+
 ### 4. Use
 
 Comment on any GitHub issue:
@@ -246,10 +246,11 @@ name: build
 | Doc | What's in it |
 |-----|-------------|
 | [Pipeline](docs/PIPELINE.md) | Stage details, shared sessions, complexity skipping, artifacts |
+| [Bootstrap](docs/BOOTSTRAP.md) | Project memory, step files, labels — what bootstrap generates and when to run it |
 | [Features](docs/FEATURES.md) | Risk gate, diagnosis, sessions, retrospective, auto-learn, labels |
 | [LiteLLM](docs/LITELLM.md) | Non-Anthropic model setup, auto-start, tested providers |
 | [Configuration](docs/CONFIGURATION.md) | Full config reference, env vars, workflow setup |
-| [Comparison](docs/COMPARISON.md) | vs Copilot, Devin, Cursor, Cline, SWE-agent, OpenHands |
+| [Comparison](docs/COMPARISON.md) | vs Copilot, Devin, Cursor, Cline, OpenHands, SWE-agent |
 | [Architecture](docs/ARCHITECTURE.md) | Source tree, state machine diagram, development guide |
 | [FAQ](docs/FAQ.md) | Common questions about usage, models, security, cost |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine-lite",
-  "version": "0.1.62",
+  "version": "0.1.63",
   "description": "Autonomous SDLC pipeline: Kody orchestration + Claude Code + LiteLLM",
   "license": "MIT",
   "type": "module",

package/dist/agent-runner.d.ts

@@ -1,4 +0,0 @@
-import type { AgentRunner } from "./types.js";
-import type { KodyConfig } from "./config.js";
-export declare function createClaudeCodeRunner(): AgentRunner;
-export declare function createRunners(config: KodyConfig): Record<string, AgentRunner>;

package/dist/agent-runner.js

@@ -1,122 +0,0 @@
-import { spawn, execFileSync } from "child_process";
-const SIGKILL_GRACE_MS = 5000;
-const STDERR_TAIL_CHARS = 500;
-function writeStdin(child, prompt) {
-    return new Promise((resolve, reject) => {
-        if (!child.stdin) {
-            resolve();
-            return;
-        }
-        child.stdin.write(prompt, (err) => {
-            if (err)
-                reject(err);
-            else {
-                child.stdin.end();
-                resolve();
-            }
-        });
-    });
-}
-function waitForProcess(child, timeout) {
-    return new Promise((resolve) => {
-        const stdoutChunks = [];
-        const stderrChunks = [];
-        child.stdout?.on("data", (chunk) => stdoutChunks.push(chunk));
-        child.stderr?.on("data", (chunk) => stderrChunks.push(chunk));
-        const timer = setTimeout(() => {
-            child.kill("SIGTERM");
-            setTimeout(() => {
-                if (!child.killed)
-                    child.kill("SIGKILL");
-            }, SIGKILL_GRACE_MS);
-        }, timeout);
-        child.on("exit", (code) => {
-            clearTimeout(timer);
-            resolve({
-                code,
-                stdout: Buffer.concat(stdoutChunks).toString(),
-                stderr: Buffer.concat(stderrChunks).toString(),
-            });
-        });
-        child.on("error", (err) => {
-            clearTimeout(timer);
-            resolve({ code: -1, stdout: "", stderr: err.message });
-        });
-    });
-}
-async function runSubprocess(command, args, prompt, timeout, options) {
-    const child = spawn(command, args, {
-        cwd: options?.cwd ?? process.cwd(),
-        env: {
-            ...process.env,
-            SKIP_BUILD: "1",
-            SKIP_HOOKS: "1",
-            ...options?.env,
-        },
-        stdio: ["pipe", "pipe", "pipe"],
-    });
-    try {
-        await writeStdin(child, prompt);
-    }
-    catch (err) {
-        return {
-            outcome: "failed",
-            error: `Failed to send prompt: ${err instanceof Error ? err.message : String(err)}`,
-        };
-    }
-    const { code, stdout, stderr } = await waitForProcess(child, timeout);
-    if (code === 0) {
-        return { outcome: "completed", output: stdout };
-    }
-    return {
-        outcome: code === null ? "timed_out" : "failed",
-        error: `Exit code ${code}\n${stderr.slice(-STDERR_TAIL_CHARS)}`,
-    };
-}
-function checkCommand(command, args) {
-    try {
-        execFileSync(command, args, { timeout: 10_000, stdio: "pipe" });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-// ─── Claude Code Runner ──────────────────────────────────────────────────────
-export function createClaudeCodeRunner() {
-    return {
-        async run(_stageName, prompt, model, timeout, _taskDir, options) {
-            return runSubprocess("claude", [
-                "--print",
-                "--model", model,
-                "--dangerously-skip-permissions",
-                "--allowedTools", "Bash,Edit,Read,Write,Glob,Grep",
-            ], prompt, timeout, options);
-        },
-        async healthCheck() {
-            return checkCommand("claude", ["--version"]);
-        },
-    };
-}
-// ─── Runner Factory ──────────────────────────────────────────────────────────
-const RUNNER_FACTORIES = {
-    "claude-code": createClaudeCodeRunner,
-};
-export function createRunners(config) {
-    // New multi-runner config
-    if (config.agent.runners && Object.keys(config.agent.runners).length > 0) {
-        const runners = {};
-        for (const [name, runnerConfig] of Object.entries(config.agent.runners)) {
-            const factory = RUNNER_FACTORIES[runnerConfig.type];
-            if (factory) {
-                runners[name] = factory();
-            }
-        }
-        return runners;
-    }
-    // Legacy single-runner fallback
-    const runnerType = config.agent.runner ?? "claude-code";
-    const factory = RUNNER_FACTORIES[runnerType];
-    const defaultName = config.agent.defaultRunner ?? "claude";
-    return { [defaultName]: factory ? factory() : createClaudeCodeRunner() };
-}

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

@@ -1,6 +0,0 @@
-/**
- * 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

@@ -1,76 +0,0 @@
-/**
- * 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

@@ -1,6 +0,0 @@
-/**
- * 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

@@ -1,22 +0,0 @@
-/**
- * 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

@@ -1,13 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,2 +0,0 @@
-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

@@ -1,85 +0,0 @@
-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

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

package/dist/cli/task-resolution.js

@@ -1,41 +0,0 @@
-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

@@ -1,49 +0,0 @@
-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

@@ -1,72 +0,0 @@
-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

@@ -1,4 +0,0 @@
-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;