@ngockhoale/ukit 2.7.3 → 2.7.5

package/templates/.claude/hooks/record-execution.mjs

@@ -0,0 +1,141 @@
+// record-execution.mjs — C40 TASK-004 dual-mode port of record-execution.sh
+// (SPEC §FR-004, §8): persist session-scoped source/write/verification receipts
+// through ukit/runtime/execution-ledger.mjs.
+//
+//   * `runHook(ctx)` — in-proc chain step. ctx = { payload, payloadText,
+//     projectRoot, env, deadlineMs, signal } -> { code, stdout, stderr }.
+//     ADVISORY: always code 0. A missing/failed runtime announces the same
+//     "runtime script failed — run: ukit install" systemMessage the .sh emits —
+//     loud, never a silent pass. In-proc mode collapses the .sh's separate
+//     "missing" vs "failed" branches into the "failed" message (an import that
+//     cannot find the module IS a failed runtime; deliberate parity note).
+//   * `isDirectRun()` CLI mode — the .sh thin wrapper execs
+//     `node record-execution.mjs` with the env contract INPUT_FILE,
+//     PROJECT_ROOT, UKIT_HOOK_DEADLINE_MS, UKIT_HARNESS (`--record` accepted
+//     for symmetry with the ledger's own CLI).
+//
+// Sweep-failure routing (FR-004): while this step runs it installs
+// setLedgerMessageEmitter so a sampled exec-ledger dir-sweep failure lands in
+// the returned stdout instead of fd 1 (which would corrupt the runner's
+// verdict channel). The emitter is always reset in `finally`.
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+export const hookFailClosed = false;
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_LEDGER_PATH = path.join(MODULE_DIR, '..', 'ukit', 'runtime', 'execution-ledger.mjs');
+
+// Byte-pinned parity with the .sh's `STATUS != 0` branch.
+const RUNTIME_FAILED =
+  '{"systemMessage":"UKit record execution: runtime script failed — run: ukit install"}\n';
+
+function parsePayload(rawInput) {
+  try {
+    const parsed = JSON.parse(rawInput);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// Shared advisory body for both modes. `rawInput` that fails to parse is a
+// silent pass — identical to the .sh piping garbage into `node … --record`,
+// which JSON.parse-falls back to `{}` and early-returns on the missing
+// tool_name.
+async function record({ rawInput, projectRoot, env, signal, deadlineMs }) {
+  const payload = parsePayload(rawInput) ?? {};
+  const ledgerPath = env.UKIT_EXECUTION_LEDGER_PATH || DEFAULT_LEDGER_PATH;
+  let ledger;
+  try {
+    ledger = await import(pathToFileURL(ledgerPath).href);
+  } catch {
+    return { code: 0, stdout: RUNTIME_FAILED, stderr: '' };
+  }
+  if (typeof ledger.recordExecutionReceipt !== 'function') {
+    return { code: 0, stdout: RUNTIME_FAILED, stderr: '' };
+  }
+
+  const emitted = [];
+  const emit = (line) => emitted.push(line);
+  if (typeof ledger.setLedgerMessageEmitter === 'function') {
+    ledger.setLedgerMessageEmitter(emit);
+  }
+  try {
+    await ledger.recordExecutionReceipt({
+      projectRoot,
+      payload,
+      toolName: payload.tool_name,
+      harness: env.UKIT_HARNESS || 'claude-code',
+      signal,
+      deadlineMs,
+    });
+  } catch {
+    return { code: 0, stdout: RUNTIME_FAILED, stderr: '' };
+  } finally {
+    if (typeof ledger.setLedgerMessageEmitter === 'function') {
+      ledger.setLedgerMessageEmitter(null);
+    }
+  }
+  return { code: 0, stdout: emitted.join(''), stderr: '' };
+}
+
+// --- SPEC §8 chain-step entry ------------------------------------------------
+export async function runHook(ctx) {
+  const env = (ctx && ctx.env) || {};
+  const projectRoot = (ctx && ctx.projectRoot) || env.PROJECT_ROOT || process.cwd();
+  let rawInput;
+  try {
+    rawInput =
+      typeof (ctx && ctx.payloadText) === 'string' && ctx.payloadText.length > 0
+        ? ctx.payloadText
+        : JSON.stringify((ctx && ctx.payload) ?? {});
+  } catch {
+    rawInput = '{}';
+  }
+  return record({
+    rawInput,
+    projectRoot,
+    env,
+    signal: ctx && ctx.signal,
+    deadlineMs: ctx && ctx.deadlineMs,
+  });
+}
+
+// --- direct-run CLI mode (the .sh thin wrapper's target) ---------------------
+export function isDirectRun() {
+  try {
+    const invoked = process.argv[1] ? fs.realpathSync(process.argv[1]) : '';
+    const self = fs.realpathSync(fileURLToPath(import.meta.url));
+    return invoked === self;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  const env = process.env;
+  let rawInput = '';
+  try {
+    rawInput = await fsp.readFile(env.INPUT_FILE || '', 'utf8');
+  } catch {
+    // No staged payload — silent advisory pass, same as an unreadable INPUT.
+  }
+  const projectRoot = env.PROJECT_ROOT || process.cwd();
+  const verdict = await record({ rawInput, projectRoot, env });
+  if (verdict.stdout) process.stdout.write(verdict.stdout);
+  process.exit(0);
+}
+
+if (isDirectRun()) {
+  main().catch(() => {
+    // Advisory hook: even a catastrophic error exits 0 with the loud message.
+    try {
+      process.stdout.write(RUNTIME_FAILED);
+    } catch { /* stdout already gone */ }
+    process.exit(0);
+  });
+}

package/templates/.claude/hooks/record-execution.sh

@@ -1,8 +1,17 @@
 #!/bin/bash
 # PostToolUse hook: persist session-scoped source/write/verification receipts.
 # ADVISORY ONLY — always exit 0. A missing or failing runtime must be loud, not a silent pass.
+#
+# C40 TASK-004 (SPEC §FR-004, §14): thin wrapper — stdin staging + env, then
+# delegate to record-execution.mjs (single source of truth, shared with the
+# in-proc chain step). The .sh used to distinguish "runtime script missing"
+# from "runtime script failed"; the in-proc contract collapses both into the
+# "failed" systemMessage, so this wrapper now emits "failed" for any non-zero
+# node exit (a missing .mjs is a failed runtime too).
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK_DIR="$SCRIPT_DIR"
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
 # TASK-019: arm advisory latency telemetry; the finish row is written by the
@@ -58,19 +67,14 @@ else
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi
-INPUT="$(cat "$UKIT_INPUT_FILE")"
-PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
-SCRIPT="$PROJECT_ROOT/.claude/ukit/runtime/execution-ledger.mjs"
-
-if [ ! -f "$SCRIPT" ]; then
-  printf '%s\n' '{"systemMessage":"UKit record execution: runtime script missing — run: ukit install"}'
-  exit 0
-fi
 
-OUTPUT=$(printf '%s' "$INPUT" | UKIT_HARNESS=claude-code UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$SCRIPT" --record)
+OUTPUT=$(INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" UKIT_HARNESS="${UKIT_HARNESS:-claude-code}" UKIT_HOOK_DEADLINE_MS="${UKIT_HOOK_DEADLINE_MS:-3000}" node "$HOOK_DIR/record-execution.mjs")
 STATUS=$?
 
 if [ "$STATUS" -ne 0 ]; then
+  # In-proc parity (SPEC §FR-004): the old "runtime script missing" branch is
+  # folded into "failed" — an .mjs that is absent or crashed is the same
+  # failed-runtime condition, and the module emits this exact line itself.
   printf '%s\n' '{"systemMessage":"UKit record execution: runtime script failed — run: ukit install"}'
   exit 0
 fi
@@ -78,3 +82,4 @@ fi
 if [ -n "$OUTPUT" ]; then
   printf '%s\n' "$OUTPUT"
 fi
+exit 0