@kody-ade/kody-engine 0.4.222 → 0.4.224

package/dist/duties/npm-publish/duty.md

@@ -0,0 +1,17 @@
+# NPM Publish
+
+## Purpose
+
+Publish current `package.json` version to npm from the repository CI sandbox.
+
+## Requirements
+
+- Store npm automation token as `NPM_TOKEN` in `.kody/secrets.enc`.
+- Kody must load that secret into the `NPM_TOKEN` environment variable before the executable runs.
+- The executable must not read or decrypt `.kody/secrets.enc` directly.
+- Run only after version in `package.json` is ready to publish.
+
+## Instructions
+
+Use the `npm-publish` executable for the implementation details.
+The duty owns the public action name and the reason this action exists; the executable owns the method.

package/dist/duties/npm-publish/profile.json

@@ -0,0 +1,6 @@
+{
+  "name": "npm-publish",
+  "action": "npm-publish",
+  "executable": "npm-publish",
+  "describe": "Publish the current package.json version to npm."
+}

package/dist/executables/npm-publish/profile.json

@@ -0,0 +1,73 @@
+{
+  "name": "npm-publish",
+  "role": "utility",
+  "phase": "shipped",
+  "describe": "Publish the current package.json version to npm using NPM_TOKEN. No agent.",
+  "inputs": [
+    {
+      "name": "dry-run",
+      "flag": "--dry-run",
+      "type": "bool",
+      "required": false,
+      "describe": "Print the publish plan without requiring NPM_TOKEN or publishing."
+    },
+    {
+      "name": "tag",
+      "flag": "--tag",
+      "type": "string",
+      "required": false,
+      "describe": "npm dist-tag to publish under. Defaults to latest."
+    },
+    {
+      "name": "access",
+      "flag": "--access",
+      "type": "enum",
+      "values": ["public", "restricted"],
+      "required": false,
+      "describe": "npm package access. Defaults to public."
+    },
+    {
+      "name": "issue",
+      "flag": "--issue",
+      "type": "int",
+      "required": false,
+      "describe": "Issue/PR number to post terminal notice on."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "acceptEdits",
+    "maxTurns": 0,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [],
+  "inputArtifacts": [],
+  "outputArtifacts": [],
+  "scripts": {
+    "preflight": [
+      { "script": "setCommentTarget", "with": { "type": "issue" } },
+      { "script": "loadTaskState" },
+      { "shell": "publish.sh", "timeoutSec": 900 },
+      { "script": "skipAgent" }
+    ],
+    "postflight": [
+      { "script": "recordOutcome" },
+      { "script": "saveTaskState" },
+      { "script": "notifyTerminal", "with": { "label": "npm publish" } }
+    ]
+  },
+  "output": {
+    "actionTypes": [
+      "NPM_PUBLISH_COMPLETED",
+      "NPM_PUBLISH_FAILED"
+    ]
+  }
+}

package/dist/executables/npm-publish/publish.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+#
+# npm-publish: publish the current package.json version to npm.
+#
+# Secrets:
+# - NPM_TOKEN must be present in the environment.
+#   Kody loads secrets before executables run; this script must not read or
+#   decrypt .kody/secrets.enc directly.
+#
+# Inputs:
+# - KODY_ARG_DRY_RUN true|false
+# - KODY_ARG_TAG npm dist-tag, default latest
+# - KODY_ARG_ACCESS public|restricted, default public
+#
+# Stdout markers:
+# - KODY_REASON=<text>
+# - KODY_SKIP_AGENT=true
+
+set -euo pipefail
+
+dry_run="${KODY_ARG_DRY_RUN:-false}"
+tag="${KODY_ARG_TAG:-latest}"
+access="${KODY_ARG_ACCESS:-public}"
+registry="${NPM_CONFIG_REGISTRY:-https://registry.npmjs.org/}"
+
+fail() {
+  echo "KODY_REASON=$1"
+  echo "KODY_SKIP_AGENT=true"
+  exit "${2:-1}"
+}
+
+json_eval() {
+  node -e "$1"
+}
+
+[[ -f package.json ]] || fail "npm publish: package.json not found" 99
+
+pkg_name="$(json_eval "const p=require('./package.json'); if(!p.name) process.exit(1); console.log(p.name)")" \
+  || fail "npm publish: package.json missing name" 99
+pkg_version="$(json_eval "const p=require('./package.json'); if(!p.version) process.exit(1); console.log(p.version)")" \
+  || fail "npm publish: package.json missing version" 99
+
+if [[ "$access" != "public" && "$access" != "restricted" ]]; then
+  fail "npm publish: --access must be public or restricted" 64
+fi
+
+echo "→ npm publish: ${pkg_name}@${pkg_version} tag=${tag} access=${access}"
+
+if [[ "$dry_run" == "true" ]]; then
+  echo "KODY_REASON=dry-run — would publish ${pkg_name}@${pkg_version} to npm with tag ${tag}"
+  echo "KODY_SKIP_AGENT=true"
+  exit 0
+fi
+
+[[ -n "${NPM_TOKEN:-}" ]] || fail "npm publish: missing NPM_TOKEN secret" 64
+
+tmp_npmrc="$(mktemp)"
+auth_host="${registry#http://}"
+auth_host="${auth_host#https://}"
+auth_host="${auth_host%/}"
+cleanup() {
+  rm -f "$tmp_npmrc"
+}
+trap cleanup EXIT
+
+chmod 600 "$tmp_npmrc"
+printf '%s\n' "registry=${registry}" >"$tmp_npmrc"
+printf '%s\n' "//${auth_host}/:_authToken=${NPM_TOKEN}" >>"$tmp_npmrc"
+
+export NODE_AUTH_TOKEN="$NPM_TOKEN"
+export NPM_CONFIG_USERCONFIG="$tmp_npmrc"
+export HUSKY=0
+export SKIP_HOOKS=1
+export CI="${CI:-1}"
+
+if npm view "${pkg_name}@${pkg_version}" version --registry "$registry" >/dev/null 2>&1; then
+  echo "KODY_REASON=${pkg_name}@${pkg_version} is already published"
+  echo "KODY_SKIP_AGENT=true"
+  exit 0
+fi
+
+publish_args=(publish --access "$access" --tag "$tag" --registry "$registry")
+
+if [[ -f pnpm-lock.yaml && -x "$(command -v pnpm)" ]]; then
+  echo " publish: pnpm ${publish_args[*]}"
+  pnpm "${publish_args[@]}"
+else
+  echo " publish: npm ${publish_args[*]}"
+  npm "${publish_args[@]}"
+fi
+
+echo "KODY_REASON=published ${pkg_name}@${pkg_version} to npm with tag ${tag}"
+echo "KODY_SKIP_AGENT=true"

package/dist/executables/preview-health/profile.json

@@ -0,0 +1,48 @@
+{
+  "name": "preview-health",
+  "role": "watch",
+  "kind": "oneshot",
+  "describe": "Scan open PRs and dispatch mechanical preview repairs.",
+  "inputs": [],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": 0,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [
+    {
+      "name": "gh",
+      "install": {
+        "required": true,
+        "checkCommand": "command -v gh"
+      },
+      "verify": "gh auth status",
+      "usage": "Reads open PRs, reads the CTO trust ledger, dispatches Kody workflows, and posts PR audit/recommendation comments.",
+      "allowedUses": ["pr", "api", "issue", "workflow"]
+    }
+  ],
+  "inputArtifacts": [],
+  "outputArtifacts": [],
+  "scripts": {
+    "preflight": [
+      {
+        "shell": "tick.sh",
+        "with": {
+          "jobsDir": ".kody/duties",
+          "duty": "preview-health"
+        },
+        "timeoutSec": 300
+      }
+    ],
+    "postflight": []
+  }
+}

package/dist/executables/preview-health/tick.sh

@@ -0,0 +1,319 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+jobs_dir="${1:-.kody/duties}"
+duty="${2:-preview-health}"
+
+export KODY_PREVIEW_HEALTH_JOBS_DIR="$jobs_dir"
+export KODY_PREVIEW_HEALTH_DUTY="$duty"
+
+python3 <<'PY'
+import base64
+import json
+import os
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+DECISIONS_LABEL = "kody:cto-decisions"
+LEDGER_START = "<!-- kody-cto-decisions:start -->"
+LEDGER_END = "<!-- kody-cto-decisions:end -->"
+VERBS = ("fix-ci", "sync", "resolve")
+AUTO_VERBS = {"resolve"}
+MAX_ACTIONS_PER_TICK = 5
+FAIL_CONCLUSIONS = {"FAILURE", "TIMED_OUT", "ACTION_REQUIRED", "STARTUP_FAILURE"}
+RUNNING_STATUSES = {"IN_PROGRESS", "QUEUED"}
+STALE_THRESHOLD = 10
+STATE_BRANCH = "kody-state"
+
+
+def log(message):
+    print(f"[preview-health] {message}", file=sys.stderr)
+
+
+def now_iso():
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def run_gh(args, input_text=None, check=True):
+    result = subprocess.run(
+        ["gh", *args],
+        input=input_text,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        cwd=os.getcwd(),
+    )
+    if check and result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or result.stdout.strip() or f"gh {' '.join(args)} failed")
+    return result.stdout
+
+
+def repo_slug():
+    owner = os.environ.get("KODY_CFG_GITHUB_OWNER", "").strip()
+    repo = os.environ.get("KODY_CFG_GITHUB_REPO", "").strip()
+    if owner and repo:
+        return f"{owner}/{repo}"
+    return run_gh(["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"]).strip()
+
+
+def default_branch(slug):
+    configured = os.environ.get("KODY_CFG_GIT_DEFAULTBRANCH", "").strip()
+    if configured:
+        return configured
+    return run_gh(["repo", "view", slug, "--json", "defaultBranchRef", "--jq", ".defaultBranchRef.name"]).strip()
+
+
+def ensure_state_branch(slug):
+    if run_gh(["api", f"/repos/{slug}/git/ref/heads/{STATE_BRANCH}"], check=False).strip():
+        return
+    branch = default_branch(slug)
+    sha = run_gh(["api", f"/repos/{slug}/git/ref/heads/{branch}", "--jq", ".object.sha"]).strip()
+    payload = json.dumps({"ref": f"refs/heads/{STATE_BRANCH}", "sha": sha})
+    run_gh(["api", "--method", "POST", f"/repos/{slug}/git/refs", "--input", "-"], input_text=payload)
+
+
+def initial_state():
+    return {"version": 1, "rev": 0, "cursor": "seed", "data": {}, "done": False}
+
+
+def load_state(slug, path):
+    result = run_gh(
+        ["api", f"/repos/{slug}/contents/{path}?ref={STATE_BRANCH}"],
+        check=False,
+    )
+    if not result.strip():
+        return {"path": path, "sha": None, "state": initial_state(), "created": True}
+    obj = json.loads(result)
+    raw = base64.b64decode(obj["content"]).decode("utf-8")
+    return {"path": path, "sha": obj.get("sha"), "state": json.loads(raw), "created": False}
+
+
+def state_unchanged(prev, next_state):
+    return (
+        prev.get("cursor") == next_state.get("cursor")
+        and prev.get("done") == next_state.get("done")
+        and prev.get("data") == next_state.get("data")
+    )
+
+
+def save_state(slug, loaded, next_state):
+    if not loaded["created"] and state_unchanged(loaded["state"], next_state):
+        return False
+    ensure_state_branch(slug)
+    body = json.dumps(next_state, indent=2) + "\n"
+    payload = {
+        "message": f"chore(jobs): update state for {os.environ['KODY_PREVIEW_HEALTH_DUTY']} (rev {next_state['rev']})",
+        "content": base64.b64encode(body.encode("utf-8")).decode("ascii"),
+        "branch": STATE_BRANCH,
+    }
+    if loaded.get("sha"):
+        payload["sha"] = loaded["sha"]
+    result = run_gh(
+        ["api", "--method", "PUT", f"/repos/{slug}/contents/{loaded['path']}", "--input", "-"],
+        input_text=json.dumps(payload),
+        check=False,
+    )
+    if result.strip():
+        return True
+    reloaded = load_state(slug, loaded["path"])
+    if not reloaded["created"] and state_unchanged(reloaded["state"], next_state):
+        return False
+    if reloaded.get("sha"):
+        payload["sha"] = reloaded["sha"]
+    else:
+        payload.pop("sha", None)
+    run_gh(["api", "--method", "PUT", f"/repos/{slug}/contents/{loaded['path']}", "--input", "-"], input_text=json.dumps(payload))
+    return True
+
+
+def read_ledger_modes():
+    modes = {verb: "ask" for verb in VERBS}
+    try:
+        raw = run_gh(["issue", "list", "--label", DECISIONS_LABEL, "--state", "open", "--limit", "20", "--json", "number,body"])
+        issues = json.loads(raw or "[]")
+        if not issues:
+            return modes
+        body = sorted(issues, key=lambda x: x.get("number", 10**9))[0].get("body", "")
+        if LEDGER_START not in body or LEDGER_END not in body:
+            return modes
+        inner = body.split(LEDGER_START, 1)[1].split(LEDGER_END, 1)[0]
+        match = re.search(r"```(?:json)?\s*(\{[\s\S]*?\})\s*```", inner)
+        if not match:
+            return modes
+        ledger = json.loads(match.group(1))
+        cto = ledger.get("staff", {}).get("cto", {})
+        for verb in VERBS:
+            if cto.get(verb, {}).get("mode") == "auto":
+                modes[verb] = "auto"
+    except Exception as err:
+        log(f"ledger read failed; treating all verbs as ask: {err}")
+    return modes
+
+
+def ci_failing(rollup):
+    if not isinstance(rollup, list):
+        return False
+    has_fail = any(str(check.get("conclusion", "")) in FAIL_CONCLUSIONS for check in rollup if isinstance(check, dict))
+    running = any(str(check.get("status", "")) in RUNNING_STATUSES for check in rollup if isinstance(check, dict))
+    return has_fail and not running
+
+
+def behind_by(slug, base, head):
+    try:
+        raw = run_gh(["api", f"repos/{slug}/compare/{base}...{head}", "--jq", ".behind_by"])
+        return int(raw.strip() or "0")
+    except Exception as err:
+        log(f"compare {base}...{head} failed: {err}")
+        return 0
+
+
+def detect_repair(slug, pr):
+    mergeable = str(pr.get("mergeable") or "").upper()
+    if mergeable == "UNKNOWN":
+        return ("defer", f"PR #{pr['number']} mergeability still UNKNOWN; retry next tick.")
+    if mergeable == "CONFLICTING":
+        return ("resolve", f"PR #{pr['number']} has merge conflicts with `{pr['baseRefName']}`.")
+    if ci_failing(pr.get("statusCheckRollup")):
+        return ("fix-ci", f"PR #{pr['number']} has failing CI checks.")
+    drift = behind_by(slug, pr["baseRefName"], pr["headRefName"])
+    if drift >= STALE_THRESHOLD:
+        return ("sync", f"PR #{pr['number']}'s branch is {drift} commits behind `{pr['baseRefName']}`.")
+    return None
+
+
+def duty_operator(jobs_dir, duty):
+    try:
+        with open(os.path.join(os.getcwd(), jobs_dir, duty, "profile.json"), "r", encoding="utf-8") as f:
+            profile = json.load(f)
+        mentions = profile.get("mentions", [])
+        return mentions[0] if isinstance(mentions, list) and mentions else ""
+    except Exception:
+        return ""
+
+
+def post_comment(pr_number, body):
+    if os.environ.get("KODY_DRY_RUN") == "1":
+        log(f"[dry-run] would comment on #{pr_number}: {body.splitlines()[0]}")
+        return True
+    try:
+        run_gh(["pr", "comment", str(pr_number), "--body", body])
+        return True
+    except Exception as err:
+        log(f"comment failed on #{pr_number}: {err}")
+        return False
+
+
+def recommend(pr_number, verb, reason, operator):
+    mention = f"@{operator} " if operator else ""
+    body = (
+        f"{mention}**CTO recommendation** - `{verb}`\n\n"
+        f"{reason} Recommended action: `{verb}` for PR #{pr_number}.\n\n"
+        "_Confirm in dashboard inbox or run the action manually. CTO will not act on its own._"
+    )
+    return post_comment(pr_number, body)
+
+
+def auto_run(pr_number, verb, reason):
+    if os.environ.get("KODY_DRY_RUN") == "1":
+        log(f"[dry-run] would dispatch kody.yml executable={verb} issue_number={pr_number}")
+    else:
+        try:
+            run_gh(["workflow", "run", "kody.yml", "-f", f"executable={verb}", "-f", f"issue_number={pr_number}"])
+        except Exception as err:
+            log(f"workflow_dispatch failed #{pr_number} ({verb}): {err}")
+            return False
+    auto_reason = (
+        "Policy: preview-health auto-runs `resolve` for merge conflicts."
+        if verb in AUTO_VERBS
+        else f"Graduated: operator approved `{verb}` repeatedly. A **Reject** on any `{verb}` returns me asking."
+    )
+    return post_comment(pr_number, f"**CTO action** - `{verb}` dispatched\n\n{reason}\n\n{auto_reason}")
+
+
+def print_row(pr, verb, fp, action, note):
+    print(f"| #{pr} | {verb} | {fp} | {action} | {note} |")
+
+
+def main():
+    slug = repo_slug()
+    jobs_dir = os.environ["KODY_PREVIEW_HEALTH_JOBS_DIR"].rstrip("/")
+    duty = os.environ["KODY_PREVIEW_HEALTH_DUTY"]
+    state_path = f"{jobs_dir}/{duty}/state.json"
+    loaded = load_state(slug, state_path)
+    modes = read_ledger_modes()
+    operator = duty_operator(jobs_dir, duty)
+
+    prs = json.loads(
+        run_gh([
+            "pr",
+            "list",
+            "--state",
+            "open",
+            "--limit",
+            "100",
+            "--json",
+            "number,title,headRefName,headRefOid,baseRefName,isDraft,mergeable,statusCheckRollup,updatedAt",
+        ])
+        or "[]"
+    )
+
+    prior = loaded["state"].get("data", {}).get("prs", {})
+    open_numbers = {str(pr["number"]) for pr in prs}
+    next_prs = {key: value for key, value in prior.items() if key in open_numbers and isinstance(value, dict)}
+
+    print("| PR | verb | fingerprint | action | note |")
+    print("|----|------|-------------|--------|------|")
+
+    priority = {"resolve": 0, "fix-ci": 1, "sync": 2}
+    queue = []
+    for pr in prs:
+        if pr.get("isDraft"):
+            print_row(pr["number"], "-", "-", "skip", "draft")
+            continue
+        repair = detect_repair(slug, pr)
+        if not repair:
+            print_row(pr["number"], "-", "-", "skip", "healthy")
+            continue
+        verb, reason = repair
+        if verb == "defer":
+            print_row(pr["number"], "-", "-", "defer", "mergeable=UNKNOWN")
+            continue
+        queue.append((priority[verb], pr["number"], pr, verb, reason))
+
+    actions_taken = 0
+    for _, number, pr, verb, reason in sorted(queue):
+        key = str(number)
+        fp = f"{verb}|{pr.get('headRefOid', '')}"
+        graduated = verb in AUTO_VERBS or modes.get(verb) == "auto"
+        intended_stage = f"{verb}-auto" if graduated else f"{verb}-recommended"
+        prev = next_prs.get(key, {})
+        if prev.get("fp") == fp and prev.get("stage") == intended_stage:
+            print_row(number, verb, fp[:24], "skip", "dedup")
+            continue
+        if actions_taken >= MAX_ACTIONS_PER_TICK:
+            print_row(number, verb, fp[:24], "defer", "tick cap")
+            continue
+
+        ok = auto_run(number, verb, reason) if graduated else recommend(number, verb, reason, operator)
+        action = "auto-ran" if graduated and ok else "auto-failed" if graduated else "recommended" if ok else "recommend-failed"
+        if ok:
+            actions_taken += 1
+            next_prs[key] = {"fp": fp, "stage": intended_stage, "lastActAt": now_iso()}
+        print_row(number, verb, fp[:24], action, "auto" if graduated else "advisory")
+
+    next_state = {
+        "version": 1,
+        "rev": int(loaded["state"].get("rev", 0)) + 1,
+        "cursor": "idle",
+        "data": {"prs": next_prs, "lastFiredAt": now_iso()},
+        "done": False,
+    }
+    save_state(slug, loaded, next_state)
+    log(f"tick complete: {actions_taken} action(s), {len(next_prs)} tracked PR(s)")
+    print("KODY_SKIP_AGENT=true")
+
+
+main()
+PY

package/dist/executables/release/prepare.sh

@@ -261,8 +261,10 @@ open_prepare_pr() {
   fi
 
   # Bump version files.
-  local files
-  mapfile -t files < <(resolve_version_files)
+  local files=()
+  while IFS= read -r f; do
+    files+=("$f")
+  done < <(resolve_version_files)
   local touched=()
   for f in "${files[@]}"; do
     local res