@kody-ade/kody-engine 0.3.9 → 0.3.11

package/dist/bin/kody.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.3.9",
+  version: "0.3.11",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -795,6 +795,7 @@ function coerceBare(spec, value) {
 }
 
 // src/executor.ts
+import { spawnSync as spawnSync2 } from "child_process";
 import * as fs21 from "fs";
 import * as path18 from "path";
 
@@ -977,7 +978,7 @@ function loadProfile(profilePath) {
 function validateScriptReferences(profile, registeredScripts) {
   const missing = [];
   for (const e of [...profile.scripts.preflight, ...profile.scripts.postflight]) {
-    if (!registeredScripts.has(e.script)) missing.push(e.script);
+    if (e.script && !registeredScripts.has(e.script)) missing.push(e.script);
   }
   return missing;
 }
@@ -1137,11 +1138,20 @@ function parseScriptList(p, key, raw) {
   const out = [];
   for (const [i, item] of raw.entries()) {
     if (!item || typeof item !== "object") {
-      throw new ProfileError(p, `scripts.${key}[${i}] must be an object like { script, runWhen? }`);
+      throw new ProfileError(p, `scripts.${key}[${i}] must be an object like { script, runWhen? } or { shell, runWhen? }`);
     }
     const r = item;
-    const script = requireString(p, r, "script");
-    const entry = { script };
+    const hasScript = typeof r.script === "string" && r.script.length > 0;
+    const hasShell = typeof r.shell === "string" && r.shell.length > 0;
+    if (hasScript && hasShell) {
+      throw new ProfileError(p, `scripts.${key}[${i}] cannot set both "script" and "shell" \u2014 pick one`);
+    }
+    if (!hasScript && !hasShell) {
+      throw new ProfileError(p, `scripts.${key}[${i}] must set "script" (registered TS function) or "shell" (filename in executable dir)`);
+    }
+    const entry = {};
+    if (hasScript) entry.script = r.script;
+    if (hasShell) entry.shell = r.shell;
     if (r.runWhen && typeof r.runWhen === "object") {
       entry.runWhen = r.runWhen;
     }
@@ -4327,6 +4337,24 @@ function lastReleaseTag(cwd) {
     return null;
   }
 }
+function remoteBranchExists(branch, cwd) {
+  try {
+    const out = git3(["ls-remote", "--heads", "origin", branch], cwd, 3e4);
+    return out.length > 0;
+  } catch {
+    return false;
+  }
+}
+function findOpenPrForBranch(branch, cwd) {
+  try {
+    const out = gh2(["pr", "list", "--head", branch, "--state", "open", "--json", "url", "--limit", "1"], { cwd });
+    const parsed = JSON.parse(out || "[]");
+    const first = parsed[0];
+    return first?.url ?? null;
+  } catch {
+    return null;
+  }
+}
 function runShell(cmd, cwd, timeoutMs) {
   const r = spawnSync(cmd, {
     cwd,
@@ -4341,6 +4369,7 @@ var releaseFlow = async (ctx) => {
   const mode = ctx.args.mode ?? "prepare";
   const bump = ctx.args.bump ?? "patch";
   const dryRun = ctx.args["dry-run"] === true || ctx.args.dryRun === true;
+  const prefer = ctx.args.prefer ?? void 0;
   const issueNumber = typeof ctx.args.issue === "number" ? ctx.args.issue : void 0;
   const cwd = ctx.cwd;
   const releaseCfg = ctx.config.release ?? {};
@@ -4348,7 +4377,7 @@ var releaseFlow = async (ctx) => {
   const timeoutMs = releaseCfg.timeoutMs ?? 6e5;
   ctx.skipAgent = true;
   if (mode === "prepare") {
-    await runPrepare({ cwd, bump, dryRun, versionFiles, ctx });
+    await runPrepare({ cwd, bump, dryRun, prefer, versionFiles, ctx });
   } else if (mode === "finalize") {
     await runFinalize({ cwd, dryRun, timeoutMs, releaseCfg, ctx });
   } else {
@@ -4378,7 +4407,7 @@ function buildIssueNotice(mode, dryRun, ctx) {
   return `\u2705 kody ${label} complete`;
 }
 async function runPrepare(args) {
-  const { cwd, bump, dryRun, versionFiles, ctx } = args;
+  const { cwd, bump, dryRun, prefer, versionFiles, ctx } = args;
   const pkgPath = path17.join(cwd, "package.json");
   if (!fs19.existsSync(pkgPath)) {
     ctx.output.exitCode = 99;
@@ -4398,11 +4427,35 @@ async function runPrepare(args) {
 `);
   if (dryRun) {
     ctx.output.exitCode = 0;
-    ctx.output.reason = `dry-run \u2014 would bump to ${newVersion}`;
+    ctx.output.reason = `dry-run \u2014 would bump to ${newVersion}${prefer ? ` (--prefer ${prefer})` : ""}`;
     process.stdout.write(`RELEASE_PLAN=bump=${newVersion} tag=${tag}
 `);
     return;
   }
+  const releaseBranch = `release/${tag}`;
+  const collides = remoteBranchExists(releaseBranch, cwd);
+  if (collides) {
+    if (prefer === "theirs") {
+      const existingPr = findOpenPrForBranch(releaseBranch, cwd);
+      if (existingPr) {
+        process.stdout.write(`  reusing existing PR (--prefer theirs): ${existingPr}
+`);
+        ctx.output.prUrl = existingPr;
+        ctx.output.exitCode = 0;
+        return;
+      }
+      ctx.output.exitCode = 4;
+      ctx.output.reason = `release prepare --prefer theirs: ${releaseBranch} exists on remote but has no open PR \u2014 nothing to reuse`;
+      return;
+    }
+    if (prefer !== "ours") {
+      ctx.output.exitCode = 4;
+      ctx.output.reason = `release prepare: branch ${releaseBranch} already exists on remote. Use --prefer ours to force-push, or --prefer theirs to reuse the existing PR.`;
+      return;
+    }
+    process.stdout.write(`  branch ${releaseBranch} exists on remote \u2014 will force-push (--prefer ours)
+`);
+  }
   const touched = [];
   for (const f of versionFiles) {
     if (updateVersionInFile(f, newVersion, cwd)) touched.push(f);
@@ -4418,12 +4471,12 @@ async function runPrepare(args) {
   prependChangelog(cwd, entry);
   process.stdout.write(`  wrote    CHANGELOG.md
 `);
-  const releaseBranch = `release/${tag}`;
   try {
     git3(["checkout", "-b", releaseBranch], cwd);
     for (const f of [...touched, "CHANGELOG.md"]) git3(["add", "--", f], cwd);
     git3(["commit", "--no-gpg-sign", "-m", `chore: release ${tag}`], cwd);
-    git3(["push", "-u", "origin", releaseBranch], cwd, 12e4);
+    const pushArgs = collides && prefer === "ours" ? ["push", "-u", "--force-with-lease", "origin", releaseBranch] : ["push", "-u", "origin", releaseBranch];
+    git3(pushArgs, cwd, 12e4);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     ctx.output.exitCode = 4;
@@ -4442,16 +4495,23 @@ ${rawEntry}
 
 Merge this and then run \`kody release --mode finalize\`.`;
   let prUrl = "";
-  try {
-    prUrl = gh2(["pr", "create", "--head", releaseBranch, "--base", base, "--title", title, "--body-file", "-"], {
-      input: body,
-      cwd
-    }).trim();
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    ctx.output.exitCode = 4;
-    ctx.output.reason = `release prepare: gh pr create failed: ${msg}`;
-    return;
+  const preexistingPr = collides && prefer === "ours" ? findOpenPrForBranch(releaseBranch, cwd) : null;
+  if (preexistingPr) {
+    process.stdout.write(`  PR already open for ${releaseBranch}: ${preexistingPr}
+`);
+    prUrl = preexistingPr;
+  } else {
+    try {
+      prUrl = gh2(["pr", "create", "--head", releaseBranch, "--base", base, "--title", title, "--body-file", "-"], {
+        input: body,
+        cwd
+      }).trim();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      ctx.output.exitCode = 4;
+      ctx.output.reason = `release prepare: gh pr create failed: ${msg}`;
+      return;
+    }
   }
   ctx.output.prUrl = prUrl;
   ctx.output.exitCode = 0;
@@ -4681,6 +4741,7 @@ var resolveFlow = async (ctx) => {
   }
   ctx.data.conflictedFiles = conflictedFiles;
   ctx.data.conflictMarkersPreview = getConflictMarkersPreview(conflictedFiles, ctx.cwd);
+  ctx.data.preferBlock = buildPreferBlock(ctx.args.prefer, baseBranch);
   const runUrl = getRunUrl();
   const runSuffix = runUrl ? `, run ${runUrl}` : "";
   tryPostPr3(
@@ -4689,6 +4750,23 @@ var resolveFlow = async (ctx) => {
     ctx.cwd
   );
 };
+function buildPreferBlock(prefer, baseBranch) {
+  if (prefer !== "ours" && prefer !== "theirs") return "";
+  const keepSide = prefer === "ours" ? "HEAD (this PR branch)" : `origin/${baseBranch} (base branch)`;
+  const keepMarkers = prefer === "ours" ? "content between `<<<<<<< HEAD` and `=======`" : `content between \`=======\` and \`>>>>>>> origin/${baseBranch}\``;
+  const dropSide = prefer === "ours" ? `origin/${baseBranch}` : "HEAD";
+  return [
+    "# Conflict resolution directive (AUTHORITATIVE \u2014 overrides defaults below)",
+    "",
+    `The user requested \`--prefer ${prefer}\`. For **every** conflict in **every** file:`,
+    "",
+    `- Keep the **${prefer}** side: ${keepSide} \u2014 ${keepMarkers}.`,
+    `- Discard the **${prefer === "ours" ? "theirs" : "ours"}** side (from ${dropSide}) entirely.`,
+    "- Remove all `<<<<<<<`, `=======`, `>>>>>>>` markers.",
+    "- Do NOT attempt to merge the two sides or apply judgement.",
+    ""
+  ].join("\n");
+}
 function getConflictedFiles(cwd) {
   try {
     const out = execFileSync17("git", ["diff", "--name-only", "--diff-filter=U"], {
@@ -5373,9 +5451,13 @@ async function runExecutable(profileName, input) {
   try {
     for (const entry of profile.scripts.preflight) {
       if (!shouldRun(entry, ctx)) continue;
-      const fn = preflightScripts[entry.script];
-      if (!fn) return finish({ exitCode: 99, reason: `preflight script not registered: ${entry.script}` });
-      await fn(ctx, profile, entry.with);
+      if (entry.shell) {
+        runShellEntry(entry, ctx, profile);
+      } else {
+        const fn = preflightScripts[entry.script];
+        if (!fn) return finish({ exitCode: 99, reason: `preflight script not registered: ${entry.script}` });
+        await fn(ctx, profile, entry.with);
+      }
       if (ctx.skipAgent && ctx.output.exitCode !== void 0 && ctx.output.exitCode !== 0) {
         return finish(ctx.output);
       }
@@ -5390,15 +5472,20 @@ async function runExecutable(profileName, input) {
     }
     for (const entry of profile.scripts.postflight) {
       if (!shouldRun(entry, ctx)) continue;
-      const fn = postflightScripts[entry.script];
-      if (!fn) return finish({ exitCode: 99, reason: `postflight script not registered: ${entry.script}` });
+      const label = entry.script ?? entry.shell ?? "<unknown>";
       try {
-        await fn(ctx, profile, agentResult, entry.with);
+        if (entry.shell) {
+          runShellEntry(entry, ctx, profile);
+        } else {
+          const fn = postflightScripts[entry.script];
+          if (!fn) return finish({ exitCode: 99, reason: `postflight script not registered: ${entry.script}` });
+          await fn(ctx, profile, agentResult, entry.with);
+        }
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`[kody] postflight script "${entry.script}" crashed: ${msg}
+        process.stderr.write(`[kody] postflight "${label}" crashed: ${msg}
 `);
-        if (!ctx.output.reason) ctx.output.reason = `postflight ${entry.script} crashed: ${msg}`;
+        if (!ctx.output.reason) ctx.output.reason = `postflight ${label} crashed: ${msg}`;
         if (ctx.output.exitCode === 0) ctx.output.exitCode = 99;
       }
     }
@@ -5515,6 +5602,48 @@ function finish(out) {
 `);
   return out;
 }
+var SHELL_TIMEOUT_MS = 3e5;
+function runShellEntry(entry, ctx, profile) {
+  const shellName = entry.shell;
+  const shellPath = path18.join(profile.dir, shellName);
+  if (!fs21.existsSync(shellPath)) {
+    ctx.skipAgent = true;
+    ctx.output.exitCode = 99;
+    ctx.output.reason = `shell script not found: ${shellName} (looked in ${profile.dir})`;
+    return;
+  }
+  const positional = entry.with ? Object.values(entry.with).map((v) => String(v)) : [];
+  const env = { ...process.env, HUSKY: "0", SKIP_HOOKS: "1" };
+  for (const [k, v] of Object.entries(ctx.args)) {
+    if (v === void 0 || v === null) continue;
+    env[`KODY_ARG_${k.toUpperCase().replace(/-/g, "_")}`] = String(v);
+  }
+  const r = spawnSync2("bash", [shellPath, ...positional], {
+    cwd: ctx.cwd,
+    encoding: "utf-8",
+    env,
+    stdio: ["pipe", "pipe", "pipe"],
+    timeout: SHELL_TIMEOUT_MS
+  });
+  const stdout = r.stdout ?? "";
+  const stderr = r.stderr ?? "";
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+  if (/^KODY_SKIP_AGENT=true\s*$/m.test(stdout)) {
+    ctx.skipAgent = true;
+  }
+  const exit = r.status ?? -1;
+  if (exit !== 0) {
+    ctx.skipAgent = true;
+    if (ctx.output.exitCode === void 0 || ctx.output.exitCode === 0) {
+      ctx.output.exitCode = exit;
+    }
+    if (!ctx.output.reason) {
+      const tail = (stderr || stdout).slice(-800);
+      ctx.output.reason = `shell '${shellName}' exited ${exit}${tail ? `: ${tail}` : ""}`;
+    }
+  }
+}
 
 // src/kody-cli.ts
 var CI_HELP = `kody ci \u2014 minimal-YAML autonomous engineer (CI preflight + run)

package/dist/executables/release/profile.json

@@ -40,6 +40,17 @@
       "type": "int",
       "required": false,
       "describe": "Issue number to post success/failure follow-up on. Auto-populated by dispatch when triggered via @kody comment."
+    },
+    {
+      "name": "prefer",
+      "flag": "--prefer",
+      "type": "enum",
+      "values": [
+        "ours",
+        "theirs"
+      ],
+      "required": false,
+      "describe": "On release/vX.Y.Z branch collision (prepare mode): 'ours' force-pushes over the remote branch; 'theirs' reuses the existing branch and its open PR. Default (unset): refuse on non-ff."
     }
   ],
   "claudeCode": {

package/dist/executables/resolve/apply-prefer.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+#
+# Deterministic conflict resolution for `kody resolve --prefer ours|theirs`.
+#
+# Runs as a preflight shell entry (see src/executables/resolve/profile.json).
+# Gated by runWhen on args.prefer, so it only fires when the user requested
+# a side. Reads the side from $KODY_ARG_PREFER (the executor exposes every
+# ctx.args.<key> as an env var).
+#
+# Preconditions set by the prior `resolveFlow` preflight:
+#   - cwd is on the PR branch.
+#   - `git merge origin/<base> --no-edit --no-ff` already ran and conflicted.
+#   - Working tree has unmerged paths.
+#
+# Behavior: for each unmerged file, git checkout --ours (or --theirs), add,
+# commit the merge, push the branch. Prints `KODY_SKIP_AGENT=true` on
+# success so the executor bypasses the agent entirely.
+#
+# Exits:
+#   0   — resolved + pushed (or nothing to resolve)
+#   64  — invalid side value
+#   1+  — git operation failed (executor will surface stderr)
+
+set -euo pipefail
+
+side="${KODY_ARG_PREFER:-}"
+if [[ "$side" != "ours" && "$side" != "theirs" ]]; then
+  echo "apply-prefer: expected KODY_ARG_PREFER=ours|theirs, got '$side'" >&2
+  exit 64
+fi
+
+unmerged=$(git diff --name-only --diff-filter=U)
+if [[ -z "$unmerged" ]]; then
+  echo "apply-prefer: no unmerged paths — nothing to resolve"
+  echo "KODY_SKIP_AGENT=true"
+  exit 0
+fi
+
+count=0
+while IFS= read -r f; do
+  [[ -z "$f" ]] && continue
+  git checkout "--$side" -- "$f"
+  git add -- "$f"
+  count=$((count + 1))
+done <<< "$unmerged"
+echo "apply-prefer: resolved $count file(s) via --$side"
+
+# Complete the merge. git merge left MERGE_MSG in place; --no-edit uses it.
+HUSKY=0 SKIP_HOOKS=1 git -c commit.gpgsign=false commit --no-edit
+
+branch=$(git rev-parse --abbrev-ref HEAD)
+git push origin "$branch"
+echo "apply-prefer: pushed $branch"
+echo "KODY_SKIP_AGENT=true"

package/dist/executables/resolve/profile.json

@@ -9,6 +9,14 @@
       "type": "int",
       "required": true,
       "describe": "GitHub PR number whose branch has conflicts with the default branch."
+    },
+    {
+      "name": "prefer",
+      "flag": "--prefer",
+      "type": "enum",
+      "values": ["ours", "theirs"],
+      "required": false,
+      "describe": "Force one side for every conflict: 'ours' = PR branch (HEAD), 'theirs' = base branch. Omit to let the agent merge by judgement."
     }
   ],
   "claudeCode": {
@@ -45,6 +53,10 @@
       {
         "script": "resolveFlow"
       },
+      {
+        "shell": "apply-prefer.sh",
+        "runWhen": { "args.prefer": ["ours", "theirs"] }
+      },
       {
         "script": "loadTaskState"
       },

package/dist/executables/resolve/prompt.md

@@ -9,13 +9,13 @@ You are Kody, an autonomous engineer. A `git merge origin/{{baseBranch}}` into P
 
 {{conflictedFiles}}
 
-{{conventionsBlock}}{{toolsUsage}}# Working-tree conflict markers (truncated)
+{{preferBlock}}{{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.
+2. If a conflict resolution directive is given above, follow it exactly — take the specified side for every conflict, no judgement. Otherwise, preserve the PR's intent (the HEAD side) unless `origin/{{baseBranch}}` made a change that should be preserved (e.g. security fix, renamed API), and 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):
 

package/dist/executables/types.ts

@@ -159,7 +159,20 @@ export interface CliToolSpec {
 }
 
 export interface ScriptEntry {
-  script: string
+  /**
+   * Name of a registered TS function in src/scripts/index.ts. Mutually
+   * exclusive with `shell` — exactly one must be set.
+   */
+  script?: string
+  /**
+   * Filename of a shell script colocated with the executable
+   * (e.g. "apply-prefer.sh"). Resolved relative to the profile's
+   * directory. Invoked via `bash <path> <with-args>` with ctx.args
+   * exposed as env vars (KODY_ARG_<UPPER_NAME>=<value>). A stdout
+   * line `KODY_SKIP_AGENT=true` signals the executor to bypass the
+   * agent. Non-zero exit is treated as a preflight failure.
+   */
+  shell?: string
   /**
    * Optional conditional. Keys are dotted paths into the context (e.g.
    * "args.mode"). Values are a single primitive or an array of primitives.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",