@kody-ade/kody-engine 0.1.7 → 0.2.0

package/dist/executables/build/profile.json

@@ -0,0 +1,83 @@
+{
+  "name": "build",
+  "describe": "Implement a GitHub issue or apply PR feedback end-to-end.",
+
+  "inputs": [
+    {
+      "name": "mode",
+      "flag": "--mode",
+      "type": "enum",
+      "values": ["run", "fix", "fix-ci", "resolve"],
+      "required": true,
+      "describe": "Which Build mode to run."
+    },
+    {
+      "name": "issue",
+      "flag": "--issue",
+      "type": "int",
+      "requiredWhen": { "mode": "run" },
+      "describe": "GitHub issue number to implement."
+    },
+    {
+      "name": "pr",
+      "flag": "--pr",
+      "type": "int",
+      "requiredWhen": { "mode": ["fix", "fix-ci", "resolve"] },
+      "describe": "GitHub PR number to operate on."
+    },
+    {
+      "name": "feedback",
+      "flag": "--feedback",
+      "type": "string",
+      "required": false,
+      "describe": "Inline override for fix mode. If absent, the executor reads the latest PR review comment."
+    },
+    {
+      "name": "runId",
+      "flag": "--run-id",
+      "type": "string",
+      "required": false,
+      "describe": "Specific failed workflow run ID for fix-ci. Defaults to latest failed run on the PR branch."
+    }
+  ],
+
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "acceptEdits",
+    "maxTurns": null,
+    "systemPromptAppend": null,
+    "tools": ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
+    "hooks": {
+      "PreToolUse": [],
+      "PostToolUse": [],
+      "Stop": []
+    },
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+
+  "cliTools": [],
+
+  "scripts": {
+    "preflight": [
+      { "script": "runFlow",     "runWhen": { "args.mode": "run" } },
+      { "script": "fixFlow",     "runWhen": { "args.mode": "fix" } },
+      { "script": "fixCiFlow",   "runWhen": { "args.mode": "fix-ci" } },
+      { "script": "resolveFlow", "runWhen": { "args.mode": "resolve" } },
+      { "script": "loadConventions" },
+      { "script": "loadCoverageRules" },
+      { "script": "composePrompt" }
+    ],
+    "postflight": [
+      { "script": "parseAgentResult" },
+      { "script": "verify" },
+      { "script": "checkCoverageWithRetry" },
+      { "script": "commitAndPush" },
+      { "script": "ensurePr" },
+      { "script": "postIssueComment" }
+    ]
+  }
+}

package/dist/executables/build/prompts/fix-ci.md

@@ -0,0 +1,42 @@
+You are Kody, an autonomous engineer. A CI workflow on PR #{{pr.number}} (`{{branch}}`) is failing. Read the failed-step log below and fix the root cause. The wrapper handles git/gh — you do not.
+
+# Repo
+- {{repoOwner}}/{{repoName}}, default branch: {{defaultBranch}}
+
+# PR #{{pr.number}}: {{pr.title}}
+
+# Failing workflow
+- Workflow: {{failedWorkflowName}}
+- Run URL:  {{failedRunUrl}}
+
+# Failed-step log (truncated, most recent ~30KB)
+
+```
+{{failedLogTail}}
+```
+
+{{conventionsBlock}}{{toolsUsage}}# Current PR diff (truncated)
+
+```diff
+{{prDiff}}
+```
+
+# Required steps
+1. Read the log carefully. Identify the actual failure — compile error, failing test, lint rule, missing dep, etc.
+2. Make the minimum edits to fix the root cause. Do NOT disable tests or rules just to make CI pass.
+3. Re-run the relevant quality command locally with Bash and confirm exit 0.
+4. Final message format (or `FAILED: <reason>` on failure):
+
+   ```
+   DONE
+   COMMIT_MSG: fix(ci): <short root-cause description>
+   PR_SUMMARY:
+   <2-4 bullets: what was failing, what you changed, why it fixes it>
+   ```
+
+# Rules
+- Do NOT run git/gh. Wrapper handles it.
+- Do NOT disable/skip tests or lint rules just to pass CI.
+- If the failure is environmental (missing secret, broken runner) and not code, emit `FAILED: <explanation>`.
+- Stay on `{{branch}}`.
+{{systemPromptAppend}}

package/dist/executables/build/prompts/fix.md

@@ -0,0 +1,40 @@
+You are Kody, an autonomous engineer. Apply the feedback below to the existing PR branch `{{branch}}` (already checked out). The wrapper handles git/gh — you do not.
+
+# Repo
+- {{repoOwner}}/{{repoName}}, default branch: {{defaultBranch}}
+
+# PR #{{pr.number}}: {{pr.title}}
+{{pr.body}}
+
+# Feedback to address (AUTHORITATIVE — supersedes the original issue spec)
+
+{{feedback}}
+
+{{conventionsBlock}}{{coverageBlock}}{{toolsUsage}}# Existing PR diff (current state, truncated)
+
+```diff
+{{prDiff}}
+```
+
+# Required steps
+1. Read the feedback carefully. It takes precedence over the original issue spec. If feedback says "remove X", remove X even if the issue asked for it.
+2. Research ONLY what's needed to address the feedback. Make the minimum edits required.
+3. Run each quality command with Bash. Fix the root cause of any failure you introduced by this round of edits.
+4. Final message format (or a single `FAILED: <reason>` line on failure):
+
+   ```
+   DONE
+   COMMIT_MSG: <conventional-commit message for this round of fixes>
+   PR_SUMMARY:
+   <2-4 bullets describing what changed in THIS fix round — not the whole PR>
+   ```
+
+# Rules
+- **Treat the feedback as a concrete change request, not a code review to argue with.** If feedback says "add an X branch", you must add an X branch — not document that the existing Y branch already covers the case. "Already handles it in a different way" is NOT an acceptable reason to skip an edit.
+- **Your DONE is only valid if your edits produce a diff that materially implements the requested change.** A diff that only adds tests asserting the *current* behavior, or only tweaks comments/docs, does NOT count as addressing a change request. If the feedback asks for a new code path, the diff MUST contain that new code path.
+- **"Already satisfied" is only allowed when the code already does exactly what the feedback asks for, verifiable by reading the implementation.** If in doubt, make the edit.
+- Do NOT run git/gh commands. The wrapper handles it.
+- Stay on `{{branch}}`.
+- Do not modify files under `.kody/`, `.kody-engine/`, `.kody2/`, `node_modules/`, `dist/`, `build/`, `.env`, `*.log`.
+- If the feedback is ambiguous or conflicts with the issue, err toward what the feedback says.
+{{systemPromptAppend}}

package/dist/executables/build/prompts/resolve.md

@@ -0,0 +1,34 @@
+You are Kody, an autonomous engineer. A `git merge origin/{{baseBranch}}` into PR #{{pr.number}} (`{{branch}}`) produced conflicts. Resolve them. The wrapper handles git/gh — you do not.
+
+# Repo
+- {{repoOwner}}/{{repoName}}
+
+# PR #{{pr.number}}: {{pr.title}}
+
+# Conflicted files
+
+{{conflictedFiles}}
+
+{{conventionsBlock}}{{toolsUsage}}# Working-tree conflict markers (truncated)
+
+{{conflictMarkersPreview}}
+
+# Required steps
+1. For each conflicted file: read it, understand both sides of the `<<<<<<<` / `=======` / `>>>>>>>` markers, and produce the correct merged content. Remove all conflict markers.
+2. Preserve the PR's intent (the HEAD side) unless `origin/{{baseBranch}}` made a change that should be preserved (e.g. security fix, renamed API). Use judgement.
+3. After resolving, run the quality commands with Bash and fix any issues YOUR resolution introduced.
+4. Final message format (or `FAILED: <reason>` on failure):
+
+   ```
+   DONE
+   COMMIT_MSG: fix: resolve merge conflicts with {{baseBranch}}
+   PR_SUMMARY:
+   <2-4 bullets: which files had conflicts, how you resolved each, any judgement calls>
+   ```
+
+# Rules
+- Do NOT run git/gh. Wrapper handles the merge commit.
+- Do NOT delete files to "resolve" conflicts. Merge the content.
+- Do NOT leave any `<<<<<<<`, `=======`, or `>>>>>>>` markers in files.
+- Stay on `{{branch}}`.
+{{systemPromptAppend}}

package/dist/executables/build/prompts/run.md

@@ -0,0 +1,31 @@
+You are Kody, an autonomous engineer. Take a GitHub issue from spec to a tested set of edits in ONE session. The wrapper handles git/gh — you do not.
+
+# Repo
+- {{repoOwner}}/{{repoName}}, default branch: {{defaultBranch}}
+- current branch (already checked out): {{branch}}
+
+{{conventionsBlock}}{{coverageBlock}}{{toolsUsage}}# Issue #{{issue.number}}: {{issue.title}}
+{{issue.body}}
+
+# Required steps (all in this one session — no handoff)
+1. **Research** — read the issue carefully. Use Grep/Glob/Read to investigate the codebase: locate relevant files, understand existing patterns, check related tests, identify constraints. Do not edit anything yet.
+2. **Plan** — before any Edit/Write, output a short plan (5–10 lines): what files you'll change, the approach, what could go wrong. No fluff.
+3. **Build** — Edit/Write to implement the change. Stay within the plan; if you discover the plan was wrong, briefly say so and adjust.
+4. **Verify** — run each quality command with Bash. On failure, fix the root cause and re-run. When reporting that a command passed, you MUST have just run it and seen exit code 0 in this session — do not paraphrase prior output.
+5. Your FINAL message must use this exact format (or a single `FAILED: <reason>` line on failure):
+
+   ```
+   DONE
+   COMMIT_MSG: <conventional-commit message, e.g. "feat: add X" or "fix: handle Y">
+   PR_SUMMARY:
+   <2-6 short bullet points naming the files/functions/endpoints you added or modified. No marketing fluff. No restating the issue.>
+   ```
+
+# Rules
+- Do NOT run **any** `git` or `gh` commands. The wrapper handles all git/gh operations. If a quality gate fails, that's the failure — do not investigate it via git.
+- Stay on the current branch (`{{branch}}`). It is already checked out for you.
+- Do NOT modify files under: `.kody/`, `.kody-engine/`, `.kody-lean/`, `.kody2/`, `node_modules/`, `dist/`, `build/`, `.env`, or any `*.log`.
+- Do NOT post issue comments — the wrapper handles that.
+- Pre-existing quality-gate failures: assume they are NOT your responsibility unless your edits touched related code.
+- Keep the plan and reasoning concise. Long monologues waste turns.
+{{systemPromptAppend}}

package/dist/executables/types.ts

@@ -0,0 +1,154 @@
+/**
+ * Types shared by the generic executor and executables.
+ *
+ * The executor reads a Profile, validates the user's CLI args against
+ * Profile.inputs, then runs the declared preflight scripts → agent →
+ * postflight scripts. The executor knows nothing about any specific role
+ * (build, review, plan, etc.) — it only executes what the profile declares.
+ */
+
+import type { Kody2Config } from "../config.js"
+import type { AgentResult } from "../agent.js"
+
+// ────────────────────────────────────────────────────────────────────────────
+// Profile shape (mirrors the JSON on disk).
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface Profile {
+  name: string
+  describe: string
+  inputs: InputSpec[]
+  claudeCode: ClaudeCodeSpec
+  cliTools: CliToolSpec[]
+  scripts: {
+    preflight: ScriptEntry[]
+    postflight: ScriptEntry[]
+  }
+  outputContract?: OutputContract
+  /** Absolute directory the profile was loaded from. Used to resolve prompt.md. */
+  dir: string
+}
+
+export interface InputSpec {
+  name: string
+  flag: string
+  type: "int" | "string" | "bool" | "enum"
+  /** Allowed values for `type: "enum"`. */
+  values?: string[]
+  required?: boolean
+  /**
+   * Only required when another input matches one of these values.
+   * e.g. `{ mode: "run" }` or `{ mode: ["fix", "fix-ci", "resolve"] }`.
+   */
+  requiredWhen?: Record<string, string | string[]>
+  describe: string
+}
+
+export interface ClaudeCodeSpec {
+  /** "inherit" → use Kody2Config.agent.model. Or a concrete "provider/model". */
+  model: string
+  permissionMode: "default" | "acceptEdits" | "plan" | "bypassPermissions"
+  /** null = unbounded. */
+  maxTurns: number | null
+  /** Text appended on top of Claude Code's baseline system prompt. */
+  systemPromptAppend: string | null
+  /** SDK built-in tools this executable is allowed to use (capability pack). */
+  tools: string[]
+  /** Claude Code hooks. `matcher` is a tool-name glob; `command` is a shell invocation. */
+  hooks: {
+    PreToolUse: HookEntry[]
+    PostToolUse: HookEntry[]
+    Stop: HookEntry[]
+  }
+  skills: string[]
+  commands: string[]
+  subagents: string[]
+  plugins: string[]
+  mcpServers: McpServerSpec[]
+}
+
+export interface HookEntry {
+  matcher: string
+  command: string
+}
+
+export interface McpServerSpec {
+  name: string
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+}
+
+export interface CliToolSpec {
+  name: string
+  install: {
+    required: boolean
+    checkCommand: string
+    installCommand?: string
+  }
+  verify: string
+  usage: string
+  allowedUses: string[]
+}
+
+export interface ScriptEntry {
+  script: string
+  /**
+   * Optional conditional. Keys are dotted paths into the context (e.g.
+   * "args.mode"). Values are a single primitive or an array of primitives.
+   * The script runs only when every key matches. Missing `runWhen` = always.
+   */
+  runWhen?: Record<string, string | number | boolean | Array<string | number | boolean>>
+}
+
+export interface OutputContract {
+  finalMessage?: {
+    onSuccess?: string[]
+    onFailure?: string[]
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Run-time context passed to every script.
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface Context {
+  /** Validated CLI args, keyed by input `name`. */
+  args: Record<string, unknown>
+  /** Project root. */
+  cwd: string
+  /** Loaded kody.config.json. */
+  config: Kody2Config
+  /** Stream-output verbosity. */
+  verbose?: boolean
+  quiet?: boolean
+  /** Opaque bag scripts populate during preflight (issue, pr, diff, logs, …). */
+  data: Record<string, unknown>
+  /** Final output the executor returns. */
+  output: {
+    exitCode: number
+    prUrl?: string
+    reason?: string
+  }
+  /**
+   * If a preflight script sets this to true, the executor skips the agent
+   * invocation and proceeds straight to postflight. Used by e.g. the
+   * clean-merge resolve path.
+   */
+  skipAgent?: boolean
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Script signatures. Two phases, two contracts.
+// ────────────────────────────────────────────────────────────────────────────
+
+export type PreflightScript = (ctx: Context, profile: Profile) => Promise<void>
+
+export type PostflightScript = (
+  ctx: Context,
+  profile: Profile,
+  agentResult: AgentResult | null,
+) => Promise<void>
+
+/** A registered script may be either phase; registry looks it up by name. */
+export type AnyScript = PreflightScript | PostflightScript