chati-dev 4.3.0 → 4.4.0

package/framework/executors/json-validate.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * json-validate executor - parse JSON files and report any that are malformed.
+ * A deterministic, zero-LLM well-formedness check (valid JSON, not schema
+ * conformance). Reads a JSON request on stdin and writes a JSON result on
+ * stdout (the executor contract; see executors/registry.yaml).
+ *
+ * arg is a comma-separated list of project-relative .json paths. Paths are
+ * contained to projectDir, and parse failures report only "not valid JSON"
+ * (never the parser message), so the executor cannot read or leak file content
+ * outside the project.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { resolve, sep } from 'path';
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => resolve(data));
+  });
+}
+
+/** True when `p`, resolved against the project root, stays inside the project. */
+function within(root, p) {
+  const full = resolve(root, p);
+  return full === root || full.startsWith(root + sep);
+}
+
+async function main() {
+  let input;
+  try {
+    input = JSON.parse((await readStdin()) || '{}');
+  } catch {
+    process.stdout.write(JSON.stringify({ status: 'error', summary: 'json-validate: request was not valid JSON.' }));
+    return;
+  }
+
+  const root = resolve(input.projectDir || process.cwd());
+  const files = String(input.arg || '').split(',').map((p) => p.trim()).filter(Boolean);
+
+  if (files.length === 0) {
+    process.stdout.write(JSON.stringify({ status: 'error', summary: 'json-validate: no files given (arg is a comma-separated list).' }));
+    return;
+  }
+
+  const escaping = files.filter((f) => !within(root, f));
+  if (escaping.length > 0) {
+    process.stdout.write(JSON.stringify({
+      status: 'error',
+      summary: `json-validate: ${escaping.length} path(s) are outside the project directory and were refused.`,
+      details: { refused: escaping },
+    }));
+    return;
+  }
+
+  const errors = [];
+  for (const f of files) {
+    const full = resolve(root, f);
+    if (!existsSync(full)) { errors.push({ file: f, error: 'not found' }); continue; }
+    try {
+      JSON.parse(readFileSync(full, 'utf-8'));
+    } catch {
+      // Report only that the file is not valid JSON. The parser message can echo
+      // file content, so it is never forwarded.
+      errors.push({ file: f, error: 'not valid JSON' });
+    }
+  }
+
+  process.stdout.write(JSON.stringify({
+    status: errors.length === 0 ? 'passed' : 'failed',
+    summary: errors.length === 0
+      ? `All ${files.length} JSON file(s) are well-formed.`
+      : `${errors.length} of ${files.length} file(s) failed to parse.`,
+    details: { errors },
+  }));
+}
+
+main();

package/framework/executors/npm-script.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * npm-script executor - run a whitelisted project npm script as a deterministic,
+ * zero-LLM task. Reads a JSON request on stdin and writes a JSON result on
+ * stdout (the executor contract; see executors/registry.yaml).
+ *
+ * Only a fixed set of terminating script names is allowed, so a script task can
+ * never run an arbitrary or long-running command: a task declares execution_ref
+ * "npm-script:test" and this runs `npm run test` and reports pass or fail from
+ * the exit code.
+ */
+import { spawn } from 'child_process';
+
+const ALLOWED = new Set(['lint', 'test', 'typecheck', 'build', 'format']);
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => resolve(data));
+  });
+}
+
+async function main() {
+  // Emit exactly once: spawn can fire both 'error' and 'close', and emitting
+  // twice would put two JSON objects on stdout and break the runner's parse.
+  let settled = false;
+  const emit = (result) => {
+    if (settled) return;
+    settled = true;
+    process.stdout.write(JSON.stringify(result));
+  };
+
+  let input;
+  try {
+    input = JSON.parse((await readStdin()) || '{}');
+  } catch {
+    emit({ status: 'error', summary: 'npm-script: request was not valid JSON.' });
+    return;
+  }
+
+  const projectDir = input.projectDir || process.cwd();
+  const script = String(input.arg || '').trim();
+
+  if (!ALLOWED.has(script)) {
+    emit({
+      status: 'error',
+      summary: `npm-script: "${script || '(none)'}" is not an allowed script. Allowed: ${[...ALLOWED].join(', ')}.`,
+    });
+    return;
+  }
+
+  const child = spawn('npm', ['run', script], { cwd: projectDir, shell: false });
+  let out = '';
+  let err = '';
+  child.stdout.on('data', (c) => { out += c; });
+  child.stderr.on('data', (c) => { err += c; });
+  child.on('error', (e) => {
+    emit({ status: 'error', summary: `npm-script: could not spawn npm (${e.message}).` });
+  });
+  child.on('close', (code) => {
+    const tail = (out + err).split('\n').filter(Boolean).slice(-20).join('\n');
+    emit({
+      status: code === 0 ? 'passed' : 'failed',
+      summary: `npm run ${script} exited ${code}.`,
+      details: { exitCode: code, tail },
+    });
+  });
+}
+
+main();

package/framework/executors/path-check.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * path-check executor - assert that required paths exist. A deterministic,
+ * zero-LLM verification gate (for example "the build output and the generated
+ * client both exist"). Reads a JSON request on stdin and writes a JSON result
+ * on stdout (the executor contract; see executors/registry.yaml).
+ *
+ * arg is a comma-separated list of project-relative paths. Paths are contained
+ * to projectDir: an absolute path or a "../" sequence that escapes the project
+ * is rejected, so the executor cannot be used to probe the wider filesystem.
+ */
+import { existsSync } from 'fs';
+import { resolve, sep } from 'path';
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => resolve(data));
+  });
+}
+
+/** True when `p`, resolved against the project root, stays inside the project. */
+function within(root, p) {
+  const full = resolve(root, p);
+  return full === root || full.startsWith(root + sep);
+}
+
+async function main() {
+  let input;
+  try {
+    input = JSON.parse((await readStdin()) || '{}');
+  } catch {
+    process.stdout.write(JSON.stringify({ status: 'error', summary: 'path-check: request was not valid JSON.' }));
+    return;
+  }
+
+  const root = resolve(input.projectDir || process.cwd());
+  const paths = String(input.arg || '').split(',').map((p) => p.trim()).filter(Boolean);
+
+  if (paths.length === 0) {
+    process.stdout.write(JSON.stringify({ status: 'error', summary: 'path-check: no paths given (arg is a comma-separated list).' }));
+    return;
+  }
+
+  const escaping = paths.filter((p) => !within(root, p));
+  if (escaping.length > 0) {
+    process.stdout.write(JSON.stringify({
+      status: 'error',
+      summary: `path-check: ${escaping.length} path(s) are outside the project directory and were refused.`,
+      details: { refused: escaping },
+    }));
+    return;
+  }
+
+  const missing = paths.filter((p) => !existsSync(resolve(root, p)));
+  process.stdout.write(JSON.stringify({
+    status: missing.length === 0 ? 'passed' : 'failed',
+    summary: missing.length === 0
+      ? `All ${paths.length} path(s) exist.`
+      : `${missing.length} of ${paths.length} path(s) missing: ${missing.join(', ')}.`,
+    details: { checked: paths, missing },
+  }));
+}
+
+main();

package/framework/executors/registry.yaml

@@ -0,0 +1,36 @@
+# Executor Registry - deterministic, zero-LLM task executors.
+#
+# Each executor is a standalone Node script that reads a JSON request on stdin
+# and writes a JSON result on stdout. The runner (packages/chati-dev/src/
+# executors/runner.js) resolves an executor by id, spawns it, enforces a
+# timeout, and writes a synthetic handoff. Executors run ONLY when a task
+# declares execution_kind: script AND the execution_kinds feature flag is on.
+#
+# Contract:
+#   stdin   {"task": {id, title, execution_ref}, "projectDir": "...", "arg": "..."}
+#   stdout  {"status": "passed" | "failed" | "error", "summary": "...", "details": {...}}
+#   arg     the part after the first colon in execution_ref
+#           (e.g. "npm-script:test" resolves executor "npm-script", arg "test").
+#   status  passed = the deterministic check succeeded;
+#           failed  = it ran and the result is negative (route to dev);
+#           error   = the executor could not run (bad arg, spawn failure).
+#
+# Adding an executor: write a standalone script under executors/, register it
+# here with a path and a timeout, and cover it with a test. Executors must be
+# deterministic, side-effect-light, and never call an LLM.
+
+version: "1.0.0"
+
+executors:
+  npm-script:
+    path: executors/npm-script.js
+    description: "Run a project npm script and report deterministic pass/fail. arg is the script name; only lint, test, typecheck, build, and format are allowed (no arbitrary or long-running commands)."
+    timeout_ms: 600000
+  path-check:
+    path: executors/path-check.js
+    description: "Assert that one or more paths exist (a deterministic verification gate). arg is a comma-separated list of project-relative paths."
+    timeout_ms: 30000
+  json-validate:
+    path: executors/json-validate.js
+    description: "Parse JSON files and report any that are malformed (a deterministic well-formedness check). arg is a comma-separated list of project-relative .json paths."
+    timeout_ms: 60000

package/framework/hooks/advance-trigger.js

@@ -17,10 +17,33 @@
  * ignored so it outlives the hook process.
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { spawn } from 'child_process';
 
+// Canonical gate thresholds live in data/qa-rubrics.yaml. These literals are
+// only a last-resort fallback for when that file is briefly unavailable (for
+// example mid-upgrade); they must match the YAML.
+const FALLBACK_QA_THRESHOLDS = { 'qa-planning': 95, 'qa-implementation': 95, 'qa-visual': 90 };
+
+function loadQaThresholds(cwd) {
+  const candidates = [
+    join(cwd, '.chati.dev', 'data', 'qa-rubrics.yaml'),
+    join(cwd, 'chati.dev', 'data', 'qa-rubrics.yaml'),
+  ];
+  let raw = null;
+  for (const p of candidates) {
+    if (existsSync(p)) { try { raw = readFileSync(p, 'utf-8'); break; } catch { /* fall through */ } }
+  }
+  if (!raw) return { ...FALLBACK_QA_THRESHOLDS };
+  const out = {};
+  for (const key of Object.keys(FALLBACK_QA_THRESHOLDS)) {
+    const m = raw.match(new RegExp(`^\\s*${key}:\\s*(\\d+)`, 'm'));
+    out[key] = m ? parseInt(m[1], 10) : FALLBACK_QA_THRESHOLDS[key];
+  }
+  return out;
+}
+
 async function readStdin() {
   let data = '';
   for await (const chunk of process.stdin) data += chunk;
@@ -95,7 +118,7 @@ async function main() {
 
   // Decide whether to fire under interactive mode.
   if (profile !== 'autonomous') {
-    const QA_THRESHOLDS = { 'qa-planning': 95, 'qa-implementation': 95, 'qa-visual': 90 };
+    const QA_THRESHOLDS = loadQaThresholds(cwd);
     const threshold = QA_THRESHOLDS[agent];
     const isQA = threshold !== undefined;
     const verdict = (fm.verdict || '').toUpperCase();
@@ -118,14 +141,35 @@ async function main() {
   if (!routerPath) return;
 
   // Fire and forget: detach so the router outlives this hook process.
+  // A silent spawn failure would stall the pipeline with no signal. Warn on
+  // stderr (Claude Code surfaces it immediately as a non-blocking hook warning)
+  // and drop a durable post-mortem marker in .chati/failures/ for inspection.
+  // The stderr warning is the surfaced signal; nothing scans the marker dir
+  // automatically yet.
+  const recordFailure = (err) => {
+    const msg = (err && err.message) ? err.message : String(err);
+    try {
+      const failuresDir = join(cwd, '.chati', 'failures');
+      mkdirSync(failuresDir, { recursive: true });
+      writeFileSync(
+        join(failuresDir, `advance-${agent}-${Date.now()}.json`),
+        JSON.stringify({ type: 'advance_spawn_failure', agent, score, error: msg, timestamp: new Date().toISOString() }),
+        'utf-8'
+      );
+    } catch { /* truly non-fatal: filesystem unavailable */ }
+    try { process.stderr.write(`[chati] advance-trigger: pipeline advance for "${agent}" failed to spawn: ${msg}\n`); } catch { /* ignore */ }
+  };
   try {
     const child = spawn('node', [routerPath, 'advance', '--agent', agent, '--score', String(score)], {
       cwd,
       detached: true,
       stdio: 'ignore',
     });
+    child.on('error', recordFailure);
     child.unref();
-  } catch { /* non-fatal */ }
+  } catch (err) {
+    recordFailure(err);
+  }
 }
 
 main().catch(() => process.stdout.write('{}\n'));

package/framework/hooks/constitution-guard.js

@@ -137,10 +137,15 @@ async function main() {
 
     process.stdout.write(JSON.stringify(allowOutput()));
   } catch (err) {
-    process.stderr.write(`[chati-hook-error] constitution-guard: ${err?.message || 'unknown'}\n`);
-    // Fail-open on hook errors: a broken hook should not block legitimate work.
-    // Real security checks above are explicit and run before this catch.
-    process.stdout.write(JSON.stringify(allowOutput()));
+    const msg = err?.message || 'unknown';
+    process.stderr.write(`[chati-hook-error] constitution-guard: ${msg}\n`);
+    // Fail CLOSED. A security/integrity guard that crashes must not
+    // silently permit the operation. The cost of a false block (user re-runs)
+    // is far lower than a false pass (a secret leak or governance violation
+    // slipping through). Deny with a clear, actionable reason.
+    process.stdout.write(JSON.stringify(denyOutput(
+      `constitution-guard could not complete its security checks (internal error: ${msg}). The operation was blocked as a precaution. Re-run once resolved, or report this if it keeps happening.`
+    )));
   }
 }
 

package/framework/hooks/git-push-authority.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview Git-push authority hook — PreToolUse (Bash).
+ *
+ * During an active pipeline, only the devops agent may push to a remote or open
+ * a pull request. This stops a non-devops agent (for example dev, mid
+ * implementation) from pushing unreviewed work past the quality gates.
+ *
+ * Scope is deliberately narrow so normal git use is never blocked:
+ *   - it only ever denies push / PR-creation / release-creation commands;
+ *   - it only enforces while a pipeline is active (session.mode is a pipeline
+ *     phase) AND the current agent is set AND is not devops;
+ *   - outside an active session (no session, completed session) it does
+ *     nothing.
+ *
+ * Fails open (with an stderr log) on any internal error: a guard crash must
+ * never block every Bash command.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const PUSH_PATTERNS = [
+  // git push, including global options that carry a value (git -C <path> push,
+  // git -c k=v push) so an agent cannot side-step the guard with -C.
+  /\bgit\s+(?:-{1,2}\S+(?:\s+\S+)?\s+)*push\b/i,
+  /\bgh\s+pr\s+(?:create|merge)\b/i,
+  /\bgh\s+release\s+create\b/i,
+];
+
+// Pipeline phases during which a non-devops agent is actively driving work.
+const ACTIVE_MODES = ['discover', 'plan', 'build', 'validate', 'deploy'];
+
+function isPushCommand(command) {
+  return PUSH_PATTERNS.some((p) => p.test(command || ''));
+}
+
+/**
+ * Block only when a push/PR command runs while a pipeline is active (mode is a
+ * pipeline phase) and the current driver is a non-devops agent.
+ */
+function shouldBlockPush(command, mode, agent) {
+  if (!isPushCommand(command)) return false;
+  return Boolean(mode && ACTIVE_MODES.includes(mode) && agent && agent !== 'devops');
+}
+
+function readSessionField(projectDir, key) {
+  const p = join(projectDir, '.chati', 'session.yaml');
+  if (!existsSync(p)) return null;
+  try {
+    const raw = readFileSync(p, 'utf-8');
+    const m = raw.match(new RegExp(`^\\s*${key}:\\s*(.+)$`, 'm'));
+    if (!m) return null;
+    const v = m[1].trim().replace(/^["']|["']$/g, '');
+    return v === 'null' || v === '' ? null : v;
+  } catch {
+    return null;
+  }
+}
+
+async function main() {
+  let input = '';
+  for await (const chunk of process.stdin) input += chunk;
+
+  try {
+    const event = JSON.parse(input);
+    if ((event.tool_name || '') !== 'Bash') {
+      process.stdout.write('{}');
+      return;
+    }
+    const command = (event.tool_input && event.tool_input.command) || '';
+    if (!isPushCommand(command)) {
+      process.stdout.write('{}');
+      return;
+    }
+
+    const projectDir = event.cwd || process.cwd();
+    const mode = readSessionField(projectDir, 'mode');
+    const agent = readSessionField(projectDir, 'current_agent');
+
+    // Only enforce while a pipeline is active with a non-devops driver.
+    if (shouldBlockPush(command, mode, agent)) {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: `[Article IV] Only the devops agent may push to a remote or open a pull request during an active pipeline. The current agent is "${agent}". Let the pipeline reach the deploy phase (devops), or run /chati exit to take manual control.`,
+        },
+      }));
+      return;
+    }
+
+    process.stdout.write('{}');
+  } catch (err) {
+    // Fail open: a guard crash must not block every Bash command. Log so the
+    // failure is visible instead of silently disabling enforcement.
+    process.stderr.write(`[chati] git-push-authority error (allowing operation): ${err && err.message ? err.message : err}\n`);
+    process.stdout.write('{}');
+  }
+}
+
+export { PUSH_PATTERNS, ACTIVE_MODES, isPushCommand, shouldBlockPush, readSessionField };
+
+// Only run main when executed directly (not when imported by tests).
+// realpathSync resolves symlinks on both sides (macOS /tmp -> /private/tmp).
+import { fileURLToPath } from 'url';
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
+}

package/framework/hooks/license-guard.js

@@ -19,7 +19,7 @@
  * Telemetry pings are owned by session-digest.js (PreCompact event), not here.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 
@@ -70,9 +70,21 @@ export async function checkLicense() {
   // cache or detects revocation. Network failures NEVER block the user.
   try {
     const machineId = await computeMachineId();
+    // The license key travels in a request header, never in the URL query
+    // string (which lands in server access, CDN and proxy logs in plaintext).
+    // Server contract: POST /license/validate, key in X-License-Key header,
+    // machine_id in the JSON body.
     const res = await fetch(
-      `${API_BASE}/license/validate?key=${encodeURIComponent(licenseKey)}&machine_id=${encodeURIComponent(machineId)}`,
-      { signal: AbortSignal.timeout(5000) }
+      `${API_BASE}/license/validate`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-License-Key': licenseKey,
+        },
+        body: JSON.stringify({ machine_id: machineId }),
+        signal: AbortSignal.timeout(5000),
+      }
     );
     const data = await res.json();
 
@@ -89,6 +101,8 @@ export async function checkLicense() {
     };
     mkdirSync(GLOBAL_DIR, { recursive: true });
     writeFileSync(LICENSE_PATH, dumpYaml(updated));
+    // The license file holds the activation key; restrict to owner-only.
+    try { chmodSync(LICENSE_PATH, 0o600); } catch { /* no-op on Windows / read-only FS */ }
 
     if (data.status === 'VALID') return { valid: true, status: 'VALID' };
     return { valid: false, reason: buildMessage(data.status, data.reason), status: data.status };
@@ -138,7 +152,12 @@ async function main() {
         process.exit(2);
       }
     }
-  } catch { /* fail open */
+  } catch (err) {
+    // Fail open by design: a license-guard crash must never brick a paying
+    // user (an unreadable or corrupt license file, a transient FS error). But
+    // it must not be silent: log to stderr so the failure is visible instead
+    // of silently bypassing enforcement.
+    process.stderr.write(`[chati] license-guard error (allowing operation): ${err && err.message ? err.message : err}\n`);
     process.stdout.write(isPreToolUse
       ? JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' } })
       : '{}');
@@ -169,9 +188,26 @@ function buildMessage(status, reason) {
 // YAML helpers (no external deps)
 // ---------------------------------------------------------------------------
 
+/**
+ * Unquote a scalar. Single-quoted values un-double the '' escape; double-quoted
+ * values are taken verbatim; bare values are returned trimmed.
+ */
+function unquoteYaml(s) {
+  s = s.trim();
+  if (s.length >= 2 && s.startsWith("'") && s.endsWith("'")) {
+    return s.slice(1, -1).replace(/''/g, "'");
+  }
+  if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
 function readYamlField(raw, field) {
-  const match = raw.match(new RegExp(`^${field}:\\s*(.+)$`, 'm'));
-  return match ? match[1].trim().replace(/^["']|["']$/g, '') : null;
+  const match = raw.match(new RegExp(`^${field}:\\s*(.*)$`, 'm'));
+  if (!match) return null;
+  const value = unquoteYaml(match[1]);
+  return value === '' ? null : value;
 }
 
 /** Minimal YAML object parser for simple key:value files */
@@ -179,15 +215,29 @@ function parseYaml(raw) {
   const obj = {};
   for (const line of raw.split('\n')) {
     const m = line.match(/^(\w+):\s*(.*)$/);
-    if (m) obj[m[1]] = m[2].trim().replace(/^["']|["']$/g, '');
+    if (m) obj[m[1]] = unquoteYaml(m[2]);
   }
   return obj;
 }
 
-/** Minimal YAML serializer for simple flat objects */
+/**
+ * Minimal YAML serializer for simple flat objects.
+ * Single-quotes any value that contains ':', a quote, '#' or surrounding
+ * whitespace, and doubles inner single-quotes ('' is the YAML single-quote
+ * escape). Newlines are collapsed to spaces so a multi-line reason can never
+ * split the record across lines and corrupt later fields. A naive serializer
+ * that wraps colon-bearing values in single quotes without escaping inner
+ * quotes can write a file the parser then cannot read back, which would brick
+ * the license cache until manually deleted.
+ */
 function dumpYaml(obj) {
   return Object.entries(obj)
-    .map(([k, v]) => `${k}: ${v == null ? '' : String(v).includes(':') ? `'${v}'` : v}`)
+    .map(([k, v]) => {
+      if (v == null) return `${k}: `;
+      const s = String(v).replace(/\r?\n/g, ' ').trim();
+      const needsQuote = s === '' || /[:'#]/.test(s) || /^\s|\s$/.test(s);
+      return needsQuote ? `${k}: '${s.replace(/'/g, "''")}'` : `${k}: ${s}`;
+    })
     .join('\n') + '\n';
 }