@kody-ade/kody-engine 0.4.64 → 0.4.65

package/dist/bin/kody.js

@@ -315,7 +315,7 @@ var init_verifyMcp = __esm({
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.4.64",
+  version: "0.4.65",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -1925,6 +1925,141 @@ init_events();
 // src/profile.ts
 import * as fs9 from "fs";
 import * as path8 from "path";
+
+// src/profile-error.ts
+var ProfileError = class extends Error {
+  constructor(profilePath, message) {
+    super(`Invalid profile at ${profilePath}:
+  ${message}`);
+    this.profilePath = profilePath;
+    this.name = "ProfileError";
+  }
+  profilePath;
+};
+
+// src/lifecycles/prBranch.ts
+var VALID_CONTEXTS = /* @__PURE__ */ new Set(["task", "ci-fix", "minimal"]);
+var CONTEXT_BUNDLES = {
+  task: ["loadTaskState", "loadConventions", "loadPriorArt", "loadMemoryContext", "loadCoverageRules"],
+  "ci-fix": ["loadTaskState", "loadConventions", "loadCoverageRules"],
+  minimal: []
+};
+function prBranchLifecycle(profile, profilePath) {
+  const cfg = validateConfig(profile.lifecycleConfig, profilePath);
+  const before = [];
+  if (cfg.sync) before.push({ script: "syncFlow" });
+  before.push({
+    script: "setLifecycleLabel",
+    with: {
+      label: cfg.label.name,
+      color: cfg.label.color,
+      description: cfg.label.description
+    }
+  });
+  const contextBundle = buildContextBundle(cfg.context, cfg.contextExtras);
+  const afterPreflight = cfg.context === "minimal" && cfg.contextExtras.length === 0 ? [{ script: "composePrompt" }] : [...contextBundle, { script: "composePrompt" }];
+  profile.scripts.preflight = [...before, ...profile.scripts.preflight, ...afterPreflight];
+  const beforePostflight = [{ script: "parseAgentResult" }];
+  const verifyChain = cfg.verify ? [{ script: "verify" }, { script: "checkCoverageWithRetry" }, { script: "abortUnfinishedGitOps" }] : [];
+  const tail = [
+    ...verifyChain,
+    { script: "commitAndPush" },
+    { script: "ensurePr" },
+    { script: "postIssueComment" },
+    { script: "writeRunSummary" },
+    { script: "saveTaskState" }
+  ];
+  if (cfg.mirrorState) tail.push({ script: "mirrorStateToPr" });
+  if (cfg.advance) tail.push({ script: "advanceFlow" });
+  profile.scripts.postflight = [...beforePostflight, ...profile.scripts.postflight, ...tail];
+}
+function buildContextBundle(context, extras) {
+  const base = CONTEXT_BUNDLES[context] ?? [];
+  if (base.length === 0 && extras.length === 0) return [];
+  const out = [];
+  let extrasInserted = false;
+  for (const name of base) {
+    out.push({ script: name });
+    if (name === "loadTaskState" && extras.length > 0) {
+      for (const e of extras) out.push({ script: e });
+      extrasInserted = true;
+    }
+  }
+  if (!extrasInserted && extras.length > 0) {
+    out.unshift(...extras.map((e) => ({ script: e })));
+  }
+  return out;
+}
+function validateConfig(raw, profilePath) {
+  if (!raw) {
+    throw new ProfileError(profilePath, `lifecycle "pr-branch" requires "lifecycleConfig" with a "label" object`);
+  }
+  const label = raw.label;
+  if (!label || typeof label !== "object" || Array.isArray(label)) {
+    throw new ProfileError(profilePath, `lifecycle "pr-branch": lifecycleConfig.label must be an object`);
+  }
+  const lbl = label;
+  for (const k of ["name", "color", "description"]) {
+    if (typeof lbl[k] !== "string" || lbl[k].length === 0) {
+      throw new ProfileError(profilePath, `lifecycle "pr-branch": lifecycleConfig.label.${k} must be a non-empty string`);
+    }
+  }
+  const context = raw.context === void 0 ? "task" : raw.context;
+  if (typeof context !== "string" || !VALID_CONTEXTS.has(context)) {
+    throw new ProfileError(
+      profilePath,
+      `lifecycle "pr-branch": lifecycleConfig.context must be one of: ${[...VALID_CONTEXTS].join(" | ")}`
+    );
+  }
+  let contextExtras = [];
+  if (raw.contextExtras !== void 0) {
+    if (!Array.isArray(raw.contextExtras) || raw.contextExtras.some((s) => typeof s !== "string" || !s)) {
+      throw new ProfileError(
+        profilePath,
+        `lifecycle "pr-branch": lifecycleConfig.contextExtras must be an array of non-empty strings`
+      );
+    }
+    contextExtras = raw.contextExtras;
+  }
+  return {
+    label: {
+      name: lbl.name,
+      color: lbl.color,
+      description: lbl.description
+    },
+    context,
+    contextExtras,
+    sync: parseBool(raw, profilePath, "sync", true),
+    verify: parseBool(raw, profilePath, "verify", true),
+    advance: parseBool(raw, profilePath, "advance", true),
+    mirrorState: parseBool(raw, profilePath, "mirrorState", false)
+  };
+}
+function parseBool(raw, profilePath, key, def) {
+  if (raw[key] === void 0) return def;
+  if (typeof raw[key] !== "boolean") {
+    throw new ProfileError(profilePath, `lifecycle "pr-branch": lifecycleConfig.${key} must be a boolean`);
+  }
+  return raw[key];
+}
+
+// src/lifecycles/index.ts
+var REGISTRY = {
+  "pr-branch": prBranchLifecycle
+};
+function applyLifecycle(profile, profilePath) {
+  if (!profile.lifecycle) return;
+  const expander = REGISTRY[profile.lifecycle];
+  if (!expander) {
+    throw new ProfileError(
+      profilePath,
+      `unknown "lifecycle": "${profile.lifecycle}". Registered: ${Object.keys(REGISTRY).sort().join(", ")}`
+    );
+  }
+  expander(profile, profilePath);
+}
+
+// src/profile.ts
 var VALID_INPUT_TYPES = /* @__PURE__ */ new Set(["int", "string", "bool", "enum"]);
 var VALID_PERMISSION_MODES = /* @__PURE__ */ new Set(["default", "acceptEdits", "plan", "bypassPermissions"]);
 var VALID_ROLES = /* @__PURE__ */ new Set(["primitive", "orchestrator", "container", "watch", "utility"]);
@@ -1940,6 +2075,8 @@ var KNOWN_PROFILE_KEYS = /* @__PURE__ */ new Set([
   "inputs",
   "claudeCode",
   "cliTools",
+  "lifecycle",
+  "lifecycleConfig",
   "scripts",
   "outputContract",
   "inputArtifacts",
@@ -1951,15 +2088,6 @@ var KNOWN_PROFILE_KEYS = /* @__PURE__ */ new Set([
   "children",
   "resetBetweenChildren"
 ]);
-var ProfileError = class extends Error {
-  constructor(profilePath, message) {
-    super(`Invalid profile at ${profilePath}:
-  ${message}`);
-    this.profilePath = profilePath;
-    this.name = "ProfileError";
-  }
-  profilePath;
-};
 function loadProfile(profilePath) {
   if (!fs9.existsSync(profilePath)) {
     throw new ProfileError(profilePath, "file not found");
@@ -1997,6 +2125,23 @@ function loadProfile(profilePath) {
     phase = r.phase;
   }
   const children = parseContainerChildren(profilePath, role, r.children);
+  let lifecycle;
+  if (r.lifecycle !== void 0) {
+    if (typeof r.lifecycle !== "string" || r.lifecycle.length === 0) {
+      throw new ProfileError(profilePath, `"lifecycle" must be a non-empty string`);
+    }
+    lifecycle = r.lifecycle;
+  }
+  let lifecycleConfig;
+  if (r.lifecycleConfig !== void 0) {
+    if (!r.lifecycleConfig || typeof r.lifecycleConfig !== "object" || Array.isArray(r.lifecycleConfig)) {
+      throw new ProfileError(profilePath, `"lifecycleConfig" must be an object`);
+    }
+    lifecycleConfig = r.lifecycleConfig;
+  }
+  if (lifecycleConfig && !lifecycle) {
+    throw new ProfileError(profilePath, `"lifecycleConfig" is only meaningful when "lifecycle" is set`);
+  }
   const profile = {
     name: requireString(profilePath, r, "name"),
     describe: typeof r.describe === "string" ? r.describe : "",
@@ -2007,6 +2152,8 @@ function loadProfile(profilePath) {
     inputs: parseInputs(profilePath, r.inputs),
     claudeCode: parseClaudeCode(profilePath, r.claudeCode),
     cliTools: parseCliTools(profilePath, r.cliTools),
+    lifecycle,
+    lifecycleConfig,
     scripts: parseScripts(profilePath, r.scripts),
     outputContract: r.outputContract,
     inputArtifacts: parseInputArtifacts(profilePath, r.input),
@@ -2018,6 +2165,9 @@ function loadProfile(profilePath) {
     resetBetweenChildren: typeof r.resetBetweenChildren === "boolean" ? r.resetBetweenChildren : true,
     dir: path8.dirname(profilePath)
   };
+  if (lifecycle) {
+    applyLifecycle(profile, profilePath);
+  }
   return profile;
 }
 function validateScriptReferences(profile, registeredScripts) {

package/dist/executables/fix/profile.json

@@ -63,37 +63,21 @@
       "usage": ""
     }
   ],
+  "lifecycle": "pr-branch",
+  "lifecycleConfig": {
+    "label": {
+      "name": "kody:fixing",
+      "color": "e99695",
+      "description": "kody: applying review feedback"
+    },
+    "context": "task"
+  },
   "scripts": {
     "preflight": [
-      { "script": "syncFlow" },
-      {
-        "script": "setLifecycleLabel",
-        "with": {
-          "label": "kody:fixing",
-          "color": "e99695",
-          "description": "kody: applying review feedback"
-        }
-      },
-      { "script": "fixFlow" },
-      { "script": "loadTaskState" },
-      { "script": "loadConventions" },
-      { "script": "loadPriorArt" },
-      { "script": "loadMemoryContext" },
-      { "script": "loadCoverageRules" },
-      { "script": "composePrompt" }
+      { "script": "fixFlow" }
     ],
     "postflight": [
-      { "script": "parseAgentResult" },
-      { "script": "requireFeedbackActions" },
-      { "script": "verify" },
-      { "script": "checkCoverageWithRetry" },
-      { "script": "abortUnfinishedGitOps" },
-      { "script": "commitAndPush" },
-      { "script": "ensurePr" },
-      { "script": "postIssueComment" },
-      { "script": "writeRunSummary" },
-      { "script": "saveTaskState" },
-      { "script": "advanceFlow" }
+      { "script": "requireFeedbackActions" }
     ]
   },
   "output": {

package/dist/executables/fix-ci/profile.json

@@ -44,62 +44,21 @@
     "mcpServers": []
   },
   "cliTools": [],
+  "lifecycle": "pr-branch",
+  "lifecycleConfig": {
+    "label": {
+      "name": "kody:fixing",
+      "color": "e99695",
+      "description": "kody: applying review feedback"
+    },
+    "context": "ci-fix",
+    "advance": false
+  },
   "scripts": {
     "preflight": [
-      { "script": "syncFlow" },
-      {
-        "script": "setLifecycleLabel",
-        "with": {
-          "label": "kody:fixing",
-          "color": "e99695",
-          "description": "kody: applying review feedback"
-        }
-      },
-      {
-        "script": "fixCiFlow"
-      },
-      {
-        "script": "loadTaskState"
-      },
-      {
-        "script": "loadConventions"
-      },
-      {
-        "script": "loadCoverageRules"
-      },
-      {
-        "script": "composePrompt"
-      }
+      { "script": "fixCiFlow" }
     ],
-    "postflight": [
-      {
-        "script": "parseAgentResult"
-      },
-      {
-        "script": "verify"
-      },
-      {
-        "script": "checkCoverageWithRetry"
-      },
-      {
-        "script": "abortUnfinishedGitOps"
-      },
-      {
-        "script": "commitAndPush"
-      },
-      {
-        "script": "ensurePr"
-      },
-      {
-        "script": "postIssueComment"
-      },
-      {
-        "script": "writeRunSummary"
-      },
-      {
-        "script": "saveTaskState"
-      }
-    ]
+    "postflight": []
   },
   "output": {
     "actionTypes": [

package/dist/executables/run/profile.json

@@ -44,38 +44,24 @@
     "mcpServers": []
   },
   "cliTools": [],
+  "lifecycle": "pr-branch",
+  "lifecycleConfig": {
+    "label": {
+      "name": "kody:running",
+      "color": "fbca04",
+      "description": "kody: implementing the change"
+    },
+    "context": "task",
+    "contextExtras": ["resolveArtifacts"],
+    "sync": false,
+    "mirrorState": true
+  },
   "scripts": {
     "preflight": [
-      {
-        "script": "setLifecycleLabel",
-        "with": {
-          "label": "kody:running",
-          "color": "fbca04",
-          "description": "kody: implementing the change"
-        }
-      },
-      { "script": "runFlow" },
-      { "script": "loadTaskState" },
-      { "script": "resolveArtifacts" },
-      { "script": "loadPriorArt" },
-      { "script": "loadMemoryContext" },
-      { "script": "loadConventions" },
-      { "script": "loadCoverageRules" },
-      { "script": "composePrompt" }
+      { "script": "runFlow" }
     ],
     "postflight": [
-      { "script": "parseAgentResult" },
-      { "script": "requirePlanDeviations" },
-      { "script": "verify" },
-      { "script": "checkCoverageWithRetry" },
-      { "script": "abortUnfinishedGitOps" },
-      { "script": "commitAndPush" },
-      { "script": "ensurePr" },
-      { "script": "postIssueComment" },
-      { "script": "writeRunSummary" },
-      { "script": "saveTaskState" },
-      { "script": "mirrorStateToPr" },
-      { "script": "advanceFlow" }
+      { "script": "requirePlanDeviations" }
     ]
   },
   "input": {

package/dist/executables/types.ts

@@ -51,6 +51,24 @@ export interface Profile {
   inputs: InputSpec[]
   claudeCode: ClaudeCodeSpec
   cliTools: CliToolSpec[]
+  /**
+   * Optional lifecycle macro. When set, the profile loader applies a
+   * predefined preflight/postflight wrapper around `scripts.preflight` and
+   * `scripts.postflight` before returning the profile. Registry of lifecycles
+   * lives in src/lifecycles/. Unknown values are rejected at load time.
+   *
+   * Lifecycles exist to consolidate orchestration boilerplate (label,
+   * context loading, verify, commit, comment) that recurs across many
+   * executables. Per-executable specifics still go in `scripts.preflight`
+   * and `scripts.postflight` — the lifecycle wraps them, it doesn't
+   * replace them.
+   */
+  lifecycle?: string
+  /**
+   * Lifecycle-specific configuration. Shape depends on `lifecycle`. Validated
+   * by each lifecycle expander, not by the generic profile parser.
+   */
+  lifecycleConfig?: Record<string, unknown>
   scripts: {
     preflight: ScriptEntry[]
     postflight: ScriptEntry[]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.4.64",
+  "version": "0.4.65",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",
@@ -12,18 +12,6 @@
     "templates",
     "kody.config.schema.json"
   ],
-  "scripts": {
-    "kody": "tsx bin/kody.ts",
-    "build": "tsup && node scripts/copy-assets.cjs",
-    "test": "vitest run tests/unit tests/int --no-coverage",
-    "test:e2e": "vitest run tests/e2e --no-coverage",
-    "test:all": "vitest run tests --no-coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check",
-    "lint:fix": "biome check --write",
-    "format": "biome format --write",
-    "prepublishOnly": "pnpm build"
-  },
   "dependencies": {
     "@actions/cache": "^6.0.0",
     "@anthropic-ai/claude-agent-sdk": "0.2.119",
@@ -45,5 +33,16 @@
     "url": "git+https://github.com/aharonyaircohen/kody-engine.git"
   },
   "homepage": "https://github.com/aharonyaircohen/kody-engine",
-  "bugs": "https://github.com/aharonyaircohen/kody-engine/issues"
-}
+  "bugs": "https://github.com/aharonyaircohen/kody-engine/issues",
+  "scripts": {
+    "kody": "tsx bin/kody.ts",
+    "build": "tsup && node scripts/copy-assets.cjs",
+    "test": "vitest run tests/unit tests/int --no-coverage",
+    "test:e2e": "vitest run tests/e2e --no-coverage",
+    "test:all": "vitest run tests --no-coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write"
+  }
+}