agent-harness-kit 0.6.0 → 0.8.0

package/src/templates/_adapter-swift/harness/structural-check.mjs.hbs

@@ -0,0 +1,285 @@
+// harness/structural-check.mjs — forward-only layer enforcement for Swift.
+//
+// Reads harness.config.json. For each domain, walks every .swift file
+// under the domain root (excluding .build/, DerivedData/, Pods/, .git/)
+// and asserts no `import` statement pulls in a layer that comes BEFORE
+// the source layer.
+//
+// Layer resolution mirrors the Rust adapter:
+//   * Source layer  = first directory segment under <root>, run through
+//                     `layerDirPattern` (default `{layer}`).
+//   * Target layer  = first identifier after `import` (or after
+//                     `import struct | class | enum | protocol | typealias
+//                      | func | var | let`), looked up by the configured
+//                     layer list or `useIdentPattern` (default `{layer}`).
+//
+// Skip-zones handled by stripNonCode():
+//   - line comment `// ... \n`
+//   - block comment `/* ... */` (Swift allows nesting)
+//   - regular string `"..."` (with `\"` and `\\` escapes)
+//   - extended string `#"..."#` and `##"..."##` (with N hashes)
+//   - multi-line string `""" ... """`
+//
+// Exit codes:
+//   0 — clean (or only baselined violations; or first-run baseline write)
+//   2 — new violations found
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+} from "node:fs";
+import { join, relative, sep } from "node:path";
+
+const repoRoot = process.cwd();
+const SKIP_DIRS = new Set([
+  ".git",
+  ".build",
+  "DerivedData",
+  "Pods",
+  "node_modules",
+  ".harness",
+  "Carthage",
+]);
+
+function readConfig() {
+  return JSON.parse(readFileSync(join(repoRoot, "harness.config.json"), "utf8"));
+}
+function readBaseline() {
+  const path = join(repoRoot, ".harness/structural-baseline.json");
+  if (!existsSync(path)) return { exists: false, set: new Set() };
+  try {
+    const arr = JSON.parse(readFileSync(path, "utf8"));
+    return { exists: true, set: new Set(Array.isArray(arr) ? arr : []) };
+  } catch {
+    return { exists: true, set: new Set() };
+  }
+}
+
+function* walkSwiftFiles(root) {
+  if (!existsSync(root)) return;
+  for (const ent of readdirSync(root, { withFileTypes: true })) {
+    if (SKIP_DIRS.has(ent.name) || ent.name.startsWith(".")) continue;
+    const full = join(root, ent.name);
+    if (ent.isDirectory()) yield* walkSwiftFiles(full);
+    else if (ent.isFile() && ent.name.endsWith(".swift")) yield full;
+  }
+}
+
+// stripNonCode — blank out comments + strings, preserve newlines.
+// Block comments nest. Triple-quoted strings span multiple lines.
+// Hashed strings allow embedded `"` (Swift's "raw string" form).
+export function stripNonCode(src) {
+  const n = src.length;
+  const out = new Array(n);
+  let i = 0;
+  while (i < n) {
+    const c = src[i];
+    const next = src[i + 1];
+    if (c === "/" && next === "/") {
+      while (i < n && src[i] !== "\n") {
+        out[i] = src[i] === "\n" ? "\n" : " ";
+        i++;
+      }
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      let depth = 1;
+      out[i] = " ";
+      out[i + 1] = " ";
+      i += 2;
+      while (i < n && depth > 0) {
+        if (src[i] === "/" && src[i + 1] === "*") {
+          depth++;
+          out[i] = " ";
+          out[i + 1] = " ";
+          i += 2;
+        } else if (src[i] === "*" && src[i + 1] === "/") {
+          depth--;
+          out[i] = " ";
+          out[i + 1] = " ";
+          i += 2;
+        } else {
+          out[i] = src[i] === "\n" ? "\n" : " ";
+          i++;
+        }
+      }
+      continue;
+    }
+    // Hashed string: #"..."# / ##"..."## etc. May enclose triple-quoted form.
+    if (c === "#") {
+      let hashes = 0;
+      let j = i;
+      while (src[j] === "#") {
+        hashes++;
+        j++;
+      }
+      if (src[j] === '"') {
+        // Check for triple-quoted variant: #"""..."""#
+        const triple = src.slice(j, j + 3) === '"""';
+        const opener = triple ? '"""' : '"';
+        const closeStr = opener + "#".repeat(hashes);
+        for (let k = i; k < j + opener.length; k++) out[k] = " ";
+        let m = j + opener.length;
+        while (m < n) {
+          if (src.slice(m, m + closeStr.length) === closeStr) {
+            for (let k = m; k < m + closeStr.length; k++) out[k] = " ";
+            m += closeStr.length;
+            break;
+          }
+          out[m] = src[m] === "\n" ? "\n" : " ";
+          m++;
+        }
+        i = m;
+        continue;
+      }
+    }
+    // Triple-quoted string """..."""
+    if (c === '"' && next === '"' && src[i + 2] === '"') {
+      out[i] = out[i + 1] = out[i + 2] = " ";
+      let m = i + 3;
+      while (m < n) {
+        if (src[m] === '"' && src[m + 1] === '"' && src[m + 2] === '"') {
+          out[m] = out[m + 1] = out[m + 2] = " ";
+          m += 3;
+          break;
+        }
+        out[m] = src[m] === "\n" ? "\n" : " ";
+        m++;
+      }
+      i = m;
+      continue;
+    }
+    // Regular string
+    if (c === '"') {
+      out[i] = " ";
+      i++;
+      while (i < n) {
+        if (src[i] === "\\" && i + 1 < n) {
+          out[i] = " ";
+          out[i + 1] = " ";
+          i += 2;
+          continue;
+        }
+        if (src[i] === '"') {
+          out[i] = " ";
+          i++;
+          break;
+        }
+        out[i] = src[i] === "\n" ? "\n" : " ";
+        i++;
+      }
+      continue;
+    }
+    out[i] = c;
+    i++;
+  }
+  return out.join("");
+}
+
+function layerOf(relPath, cfg) {
+  for (const d of cfg.domains) {
+    const altPrefix = d.root + "/";
+    const sepPrefix = d.root + sep;
+    let stripped;
+    if (relPath.startsWith(altPrefix)) stripped = relPath.slice(altPrefix.length);
+    else if (relPath.startsWith(sepPrefix)) stripped = relPath.slice(sepPrefix.length);
+    else continue;
+    const first = stripped.split(/[\/\\]/)[0];
+    const pattern = d.layerDirPattern || "{layer}";
+    const layer = resolveFromPattern(first, pattern, d.layers);
+    if (layer) return { layer, domain: d };
+  }
+  return null;
+}
+
+function resolveFromPattern(ident, pattern, layers) {
+  if (pattern === "{layer}") return layers.includes(ident) ? ident : null;
+  const [prefix, suffix] = pattern.split("{layer}");
+  const pre = (prefix || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const suf = (suffix || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`^${pre}(.+?)${suf}$`);
+  const m = ident.match(re);
+  if (m && layers.includes(m[1])) return m[1];
+  return null;
+}
+
+// `import [submodule-kind] <ident>[.<ident>]?`
+const IMPORT_RE =
+  /\bimport\s+(?:struct\s+|class\s+|enum\s+|protocol\s+|typealias\s+|func\s+|var\s+|let\s+)?([A-Za-z_][A-Za-z0-9_]*)/g;
+
+function findImportLayers(code, domain) {
+  const out = [];
+  const ident = domain.useIdentPattern || "{layer}";
+  IMPORT_RE.lastIndex = 0;
+  let m;
+  while ((m = IMPORT_RE.exec(code)) !== null) {
+    const layer = resolveFromPattern(m[1], ident, domain.layers);
+    if (layer) {
+      const line = code.slice(0, m.index).split("\n").length;
+      out.push({ layer, line });
+    }
+  }
+  return out;
+}
+
+function main() {
+  const cfg = readConfig();
+  const { exists: baselineExists, set: baselineSet } = readBaseline();
+  const violations = [];
+  for (const d of cfg.domains) {
+    const rootDir = join(repoRoot, d.root);
+    for (const file of walkSwiftFiles(rootDir)) {
+      const relPath = relative(repoRoot, file);
+      const src = layerOf(relPath, cfg);
+      if (!src) continue;
+      const srcIdx = src.domain.layers.indexOf(src.layer);
+      const content = readFileSync(file, "utf8");
+      const code = stripNonCode(content);
+      for (const { layer: tgtLayer, line } of findImportLayers(code, src.domain)) {
+        const tgtIdx = src.domain.layers.indexOf(tgtLayer);
+        if (tgtIdx === -1) continue;
+        if (srcIdx < tgtIdx) {
+          const key = `${relPath}::${tgtLayer}`;
+          if (baselineSet.has(key)) continue;
+          violations.push({
+            file: relPath,
+            line,
+            from: src.layer,
+            to: tgtLayer,
+            domain: src.domain.name,
+            key,
+          });
+        }
+      }
+    }
+  }
+
+  if (!baselineExists && violations.length > 0) {
+    mkdirSync(join(repoRoot, ".harness"), { recursive: true });
+    const keys = [...new Set(violations.map((v) => v.key))].sort();
+    writeFileSync(
+      join(repoRoot, ".harness/structural-baseline.json"),
+      JSON.stringify(keys, null, 2) + "\n",
+    );
+    console.log(`✓ structural test: baselined ${keys.length} existing violation(s).`);
+    process.exit(0);
+  }
+  if (violations.length === 0) {
+    console.log("✓ structural test passed");
+    process.exit(0);
+  }
+  for (const v of violations) {
+    console.error(`✖ ${v.file}:${v.line}  layer=${v.from} → ${v.to}  (must be forward-only)`);
+  }
+  console.error(`\n${violations.length} new layer violation(s). Fix the import direction.`);
+  if (cfg.domains.length > 0) {
+    console.error(`Layer order for domain "${cfg.domains[0].name}": ${cfg.domains[0].layers.join(" → ")}`);
+  }
+  process.exit(2);
+}
+
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) main();

package/src/templates/harness.config.json.hbs

@@ -7,14 +7,14 @@
   "domains": [
     {
       "name": "default",
-      "root": "{{#if isPython}}app{{else}}{{#if isGo}}internal{{else}}src{{/if}}{{/if}}",
+      "root": "{{#if isPython}}app{{else}}{{#if isGo}}internal{{else}}{{#if isSwift}}Sources{{else}}{{#if isKotlin}}src/main/kotlin{{else}}src{{/if}}{{/if}}{{/if}}{{/if}}",
       "layers": [{{#each layers}}"{{this}}"{{#unless @last}}, {{/unless}}{{/each}}]
     }
   ],
   "providers": ["auth", "telemetry", "feature-flags"],
   "goldenPrinciples": "docs/golden-principles.md",
   "structuralTest": {
-    "engine": "{{#if isPython}}libcst{{else}}{{#if isGo}}go-parser{{else}}{{#if isRust}}rust-regex{{else}}ts-morph{{/if}}{{/if}}{{/if}}",
+    "engine": "{{#if isPython}}libcst{{else}}{{#if isGo}}go-parser{{else}}{{#if isRust}}rust-lexer{{else}}{{#if isSwift}}swift-lexer{{else}}{{#if isKotlin}}kotlin-lexer{{else}}ts-morph{{/if}}{{/if}}{{/if}}{{/if}}{{/if}}",
     "configPath": ".harness/structural-test.config.json",
     "blockOnViolation": true
   },
@@ -30,7 +30,9 @@
   },
   "claudeMd": {
     "path": "CLAUDE.md",
-    "maxInstructions": 200
+    "maxInstructions": 200,
+    "maxTokens": 0,
+    "humanLanguage": "{{humanLanguage}}"
   },
   "recovery": {
     "headless": false

package/src/templates/scripts/_lib/approx-tokens.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// approx-tokens.mjs — heuristic token counter for CLAUDE.md cap.
+//
+// Why this exists: the original `claudeMd.maxInstructions` cap counts
+// bullets and numbered list items. For ASCII-heavy English content, 200
+// bullets ≈ ~3000 tokens (the threshold HumanLayer measured). But for
+// CJK or accent-heavy languages (Vietnamese, Thai), the same 200 bullets
+// can carry 2–3× more tokens, so the bullet count alone can let drift
+// past the model's "follow CLAUDE.md reliably" budget without firing.
+//
+// Heuristic: Anthropic's tokenizer charges roughly:
+//   - 1 token per ~4 ASCII chars (English/code)
+//   - 1 token per ~2 chars for non-ASCII (Vietnamese, CJK, etc.)
+//
+// We approximate by walking code points, classifying each into
+// "latin-1" (codepoint < 0x100, ~4 chars/token) vs "other" (~2 chars/
+// token), and dividing accordingly. Off by maybe 10–20% vs the real
+// tokenizer — close enough for a Stop-hook cap.
+//
+// Output: a single integer (the approximate token count).
+
+import { readFileSync } from "node:fs";
+
+const path = process.argv[2];
+if (!path) {
+  console.error("usage: approx-tokens.mjs <file>");
+  process.exit(1);
+}
+
+let text;
+try {
+  text = readFileSync(path, "utf8");
+} catch (e) {
+  console.error(`approx-tokens: cannot read ${path}: ${e.message}`);
+  process.exit(1);
+}
+
+console.log(approxTokens(text));
+
+export function approxTokens(text) {
+  let latin = 0;
+  let other = 0;
+  for (const ch of text) {
+    if (ch.codePointAt(0) < 0x100) latin++;
+    else other++;
+  }
+  return Math.ceil(latin / 4 + other / 2);
+}

package/src/templates/scripts/_lib/json-pick.mjs

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+// json-pick.mjs — tiny jq-subset for Stop hook + pre-push hook.
+//
+// Why this exists: harness hooks shell out to `jq` for path queries against
+// harness.config.json. On minimal CI images and on Windows without WSL+brew,
+// `jq` is missing — the hooks used to silently skip the whole check (return
+// 0 from a stub branch), which left the user unprotected. This script is a
+// pure-Node fallback so a `node` binary is the only hard requirement (which
+// the kit already has via the `engines` field).
+//
+// Usage:
+//   node json-pick.mjs <jq-expr> <file>
+//   node json-pick.mjs <jq-expr> < json-on-stdin
+//
+// Supported subset (the only constructs the hooks actually use today):
+//   .                                 — identity
+//   .a.b.c                            — dotted path
+//   .a[3]                             — array index
+//   .a[]                              — iterate array (one value per line)
+//   .a | length                       — length of array / object / string
+//   .a // "fallback"                  — alternative when missing/null/false
+//   .a // empty                       — emit nothing when missing (jq idiom)
+//   length                            — length of root value
+//
+// Output format matches `jq -r`: strings are unquoted, booleans/numbers are
+// raw. Missing/null prints empty string when used with `// default` else
+// prints `null` (same as `jq -r`).
+//
+// Exit codes:
+//   0 — value resolved (may be empty string)
+//   1 — parse / IO error
+//
+// Hard-coded subset by design. Adding new operators here forces an update to
+// the hook scripts, which keeps the surface auditable.
+
+import { readFileSync } from "node:fs";
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  console.error("usage: json-pick.mjs <expr> [<file>]");
+  process.exit(1);
+}
+const expr = args[0];
+const file = args[1];
+
+let raw;
+try {
+  raw = file ? readFileSync(file, "utf8") : readFileSync(0, "utf8");
+} catch (e) {
+  console.error(`json-pick: cannot read ${file ?? "stdin"}: ${e.message}`);
+  process.exit(1);
+}
+
+let root;
+try {
+  root = JSON.parse(raw);
+} catch (e) {
+  console.error(`json-pick: invalid JSON in ${file ?? "stdin"}: ${e.message}`);
+  process.exit(1);
+}
+
+function tokenize(src) {
+  const toks = [];
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === " " || c === "\t" || c === "\n") { i++; continue; }
+    if (c === ".") { toks.push({ t: "dot" }); i++; continue; }
+    if (c === "|") { toks.push({ t: "pipe" }); i++; continue; }
+    if (c === "[") { toks.push({ t: "lbrack" }); i++; continue; }
+    if (c === "]") { toks.push({ t: "rbrack" }); i++; continue; }
+    if (c === "/" && src[i + 1] === "/") { toks.push({ t: "fallback" }); i += 2; continue; }
+    if (c === '"') {
+      let j = i + 1, val = "";
+      while (j < src.length && src[j] !== '"') {
+        if (src[j] === "\\" && j + 1 < src.length) { val += src[j + 1]; j += 2; continue; }
+        val += src[j]; j++;
+      }
+      if (src[j] !== '"') throw new Error("unterminated string");
+      toks.push({ t: "string", v: val });
+      i = j + 1; continue;
+    }
+    if (/[0-9-]/.test(c)) {
+      let j = i;
+      while (j < src.length && /[0-9-]/.test(src[j])) j++;
+      toks.push({ t: "number", v: parseInt(src.slice(i, j), 10) });
+      i = j; continue;
+    }
+    if (/[a-zA-Z_]/.test(c)) {
+      let j = i;
+      while (j < src.length && /[a-zA-Z0-9_]/.test(src[j])) j++;
+      const word = src.slice(i, j);
+      if (word === "length" || word === "null" || word === "true" || word === "false") {
+        toks.push({ t: "keyword", v: word });
+      } else {
+        toks.push({ t: "ident", v: word });
+      }
+      i = j; continue;
+    }
+    throw new Error(`unexpected char '${c}' at ${i}`);
+  }
+  return toks;
+}
+
+// Parse and apply against root. Returns array of result rows (each printed on
+// its own line) — `[]` may produce many, `.` produces one.
+function evalExpr(src, value) {
+  const toks = tokenize(src);
+  let p = 0;
+  const peek = () => toks[p];
+  const eat = (t) => {
+    if (!toks[p] || toks[p].t !== t) throw new Error(`expected ${t}, got ${toks[p]?.t ?? "EOF"}`);
+    return toks[p++];
+  };
+
+  // pipeline = primary ( "|" filter )*    and `// default` is parsed at the path level.
+  // We unify "// default" handling: any path can have `// LITERAL` appended.
+  function parsePrimary() {
+    // Special case: starting with `length` alone → length of root.
+    if (peek() && peek().t === "keyword" && peek().v === "length") {
+      p++;
+      return { kind: "length", inner: { kind: "identity" } };
+    }
+    return parsePath();
+  }
+
+  function parsePath() {
+    // Must start with "."
+    if (!peek() || peek().t !== "dot") throw new Error("expr must start with '.'");
+    p++;
+    const steps = [];
+    // Allow `.` alone (identity).
+    while (peek()) {
+      const cur = peek();
+      if (cur.t === "ident") {
+        steps.push({ kind: "key", v: cur.v });
+        p++;
+        // optional `.next` chain
+        while (peek() && peek().t === "dot" && toks[p + 1] && toks[p + 1].t === "ident") {
+          p++; // dot
+          steps.push({ kind: "key", v: toks[p].v });
+          p++;
+        }
+        continue;
+      }
+      if (cur.t === "lbrack") {
+        p++;
+        if (peek() && peek().t === "rbrack") {
+          steps.push({ kind: "iter" });
+          p++;
+        } else if (peek() && peek().t === "number") {
+          const n = toks[p].v;
+          p++;
+          eat("rbrack");
+          steps.push({ kind: "index", v: n });
+        } else {
+          throw new Error("expected number or ']' after '['");
+        }
+        // dot after `]` is allowed: `.a[0].b`
+        if (peek() && peek().t === "dot") {
+          p++;
+        }
+        continue;
+      }
+      break;
+    }
+    return { kind: "path", steps };
+  }
+
+  let node = parsePrimary();
+
+  // ( | length )* and ( // literal )?
+  while (peek()) {
+    if (peek().t === "pipe") {
+      p++;
+      if (peek() && peek().t === "keyword" && peek().v === "length") {
+        p++;
+        node = { kind: "length", inner: node };
+      } else {
+        throw new Error("only 'length' is supported after '|'");
+      }
+      continue;
+    }
+    if (peek().t === "fallback") {
+      p++;
+      const lit = peek();
+      if (!lit) throw new Error("expected literal after //");
+      let v;
+      let drop = false;
+      if (lit.t === "string") v = lit.v;
+      else if (lit.t === "number") v = lit.v;
+      else if (lit.t === "keyword") {
+        if (lit.v === "true") v = true;
+        else if (lit.v === "false") v = false;
+        else if (lit.v === "null") v = null;
+        else throw new Error("unexpected literal");
+      } else if (lit.t === "ident" && lit.v === "empty") {
+        drop = true;
+      } else {
+        throw new Error("expected literal after //");
+      }
+      p++;
+      node = { kind: "fallback", inner: node, default: v, drop };
+      continue;
+    }
+    break;
+  }
+
+  if (p !== toks.length) {
+    throw new Error("trailing tokens");
+  }
+
+  // Now interpret.
+  function run(n, v) {
+    if (n.kind === "identity") return [v];
+    if (n.kind === "path") {
+      let cur = [v];
+      for (const step of n.steps) {
+        const next = [];
+        for (const item of cur) {
+          if (step.kind === "key") {
+            next.push(item == null ? null : item[step.v]);
+          } else if (step.kind === "index") {
+            next.push(Array.isArray(item) ? item[step.v] : null);
+          } else if (step.kind === "iter") {
+            if (Array.isArray(item)) for (const e of item) next.push(e);
+            else if (item && typeof item === "object") for (const e of Object.values(item)) next.push(e);
+            else next.push(null);
+          }
+        }
+        cur = next;
+      }
+      if (n.steps.length === 0) return [v]; // bare `.`
+      return cur;
+    }
+    if (n.kind === "length") {
+      const inner = run(n.inner, v);
+      return inner.map((x) => {
+        if (x == null) return 0;
+        if (Array.isArray(x)) return x.length;
+        if (typeof x === "string") return x.length;
+        if (typeof x === "object") return Object.keys(x).length;
+        return 0;
+      });
+    }
+    if (n.kind === "fallback") {
+      const inner = run(n.inner, v);
+      const out = [];
+      for (const x of inner) {
+        const missing = x === null || x === undefined || x === false;
+        if (missing && n.drop) continue;
+        out.push(missing ? n.default : x);
+      }
+      return out;
+    }
+    throw new Error("unknown node kind");
+  }
+
+  return run(node, value);
+}
+
+let rows;
+try {
+  rows = evalExpr(expr, root);
+} catch (e) {
+  console.error(`json-pick: ${e.message} (expr: ${expr})`);
+  process.exit(1);
+}
+
+for (const r of rows) {
+  if (r === null || r === undefined) {
+    console.log("null");
+  } else if (typeof r === "string") {
+    console.log(r);
+  } else {
+    console.log(JSON.stringify(r));
+  }
+}