@rungs/cli 0.1.0

package/src/add.ts

@@ -0,0 +1,331 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import type { Manifest } from './types.ts';
+import { matchAny, walk } from './glob.ts';
+import { markers, mergeBlock, substitute, type Params } from './substitute.ts';
+
+export interface AddAction {
+  disposition: 'create' | 'skip-exists' | 'rule' | 'skill' | 'merge' | 'gate';
+  target: string;
+  note?: string;
+}
+
+/** Where a fragment file merges to. The name is the target, not a path. */
+const FRAGMENT_TARGET: Record<string, string> = {
+  'AGENTS.md': 'AGENTS.md',
+  gitignore: '.gitignore',
+  gitattributes: '.gitattributes',
+};
+
+/**
+ * Install one module. Disposition is decided by which subdirectory a file is
+ * in — never by per-file configuration (ADR-0003), which is why this function
+ * is a switch over five directory names and nothing else.
+ *
+ * Never overwrites an existing file. ADR-0004: `add` on existing structure
+ * reports the delta; the dangerous operation is removed rather than guarded.
+ */
+export function addModule(
+  mod: Manifest,
+  repoRoot: string,
+  params: Params,
+  opts: { dryRun?: boolean; skillsDir?: string } = {},
+): AddAction[] {
+  const actions: AddAction[] = [];
+  const write = (rel: string, content: string, disposition: AddAction['disposition']) => {
+    const full = join(repoRoot, rel);
+    if (existsSync(full)) {
+      actions.push({ disposition: 'skip-exists', target: rel, note: 'already present — left alone' });
+      return;
+    }
+    actions.push({ disposition, target: rel });
+    if (opts.dryRun) return;
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, content);
+  };
+
+  const sub = (text: string) => substitute(text, mod.name, params);
+  const has = (d: string) => existsSync(join(mod.dir, d));
+
+  if (has('files')) {
+    const base = join(mod.dir, 'files');
+    for (const rel of walk(base)) {
+      write(sub(rel), sub(readFileSync(join(base, rel), 'utf8')), 'create');
+    }
+  }
+
+  if (has('rules')) {
+    const base = join(mod.dir, 'rules');
+    for (const rel of walk(base)) {
+      write(join('.ai', 'rules', rel).split('\\').join('/'), sub(readFileSync(join(base, rel), 'utf8')), 'rule');
+    }
+  }
+
+  if (has('skills')) {
+    const base = join(mod.dir, 'skills');
+    const dir = opts.skillsDir ?? '.claude/skills';
+    for (const rel of walk(base)) {
+      write(`${dir}/${rel}`, sub(readFileSync(join(base, rel), 'utf8')), 'skill');
+    }
+  }
+
+  if (has('fragments')) {
+    const base = join(mod.dir, 'fragments');
+    for (const rel of walk(base)) {
+      const target = FRAGMENT_TARGET[rel];
+      if (!target) {
+        actions.push({ disposition: 'merge', target: rel, note: 'unknown fragment target — skipped' });
+        continue;
+      }
+      const full = join(repoRoot, target);
+      const existing = existsSync(full) ? readFileSync(full, 'utf8') : '';
+      const fragment = sub(readFileSync(join(base, rel), 'utf8'));
+      const merged = mergeBlock(existing, fragment, mod.name);
+      actions.push({
+        disposition: 'merge',
+        target,
+        note: existing.includes(`rungs:begin ${mod.name}`) ? 'block replaced' : 'block appended',
+      });
+      if (!opts.dryRun) {
+        mkdirSync(dirname(full), { recursive: true });
+        writeFileSync(full, merged);
+      }
+    }
+  }
+
+  return actions;
+}
+
+/**
+ * Gate registration is a **second phase**, run after every module's files exist.
+ *
+ * Done inside `addModule` it raced the `gates` module's own registry file:
+ * whichever module merged an entry first created `.ai/gates.toml`, and the
+ * owner then hit the never-overwrite rule and was skipped — leaving a registry
+ * with entries and no `[runner]` block. Reordering the install did not fix it,
+ * because `gates` depends on `instructions`, which itself ships gates. The
+ * ordering was never the problem: **the owner of a shared file must create it
+ * before anything merges into it, which is a phase, not a position.**
+ */
+export function registerGates(mods: Manifest[], repoRoot: string, dryRun = false, adopted: AdoptedGate[] = []): AddAction[] {
+  const actions: AddAction[] = [];
+  const registry = join(repoRoot, '.ai', 'gates.toml');
+
+  // Adoption, in the only form ADR-0004 permits: the repo's existing validators
+  // are registered as `command` gates so they gain the runner, the ledger and
+  // attribution — **without a line of them being rewritten**. This is the claim
+  // the whole product rests on, and it was missing: `add` created a registry of
+  // rungs' own gates and left the repo's sixteen where they were.
+  if (adopted.length) {
+    const existing = existsSync(registry) ? readFileSync(registry, 'utf8') : '';
+    const { begin, end } = markers('gates.toml', 'adopted', '1.0.0');
+    const body = [
+      begin,
+      '# Registered from validators this repo already had. Their scripts are untouched and',
+      '# stay yours; rungs only runs them and records what it observes.',
+      ...adopted.map(
+        (a) => `\n[[gates]]\nid      = "${a.id}"\nkind    = "command"\nmodule  = "adopted"\ntier    = "${a.tier}"\ncommand = "${a.command}"\nwhy     = """Adopted from ${a.source}. Predates rungs and is owned by this repo."""`,
+      ),
+      end,
+    ].join('\n');
+    actions.push({ disposition: 'gate', target: '.ai/gates.toml', note: `adopted: ${adopted.length} entries` });
+    if (!dryRun) {
+      mkdirSync(dirname(registry), { recursive: true });
+      writeFileSync(registry, mergeBlock(existing, body, 'adopted'));
+    }
+  }
+
+  for (const mod of mods) {
+    if (!mod.gates.length) continue;
+    const existing = existsSync(registry) ? readFileSync(registry, 'utf8') : '';
+    const { begin, end } = markers('gates.toml', mod.name, mod.version);
+    const body = [begin, ...mod.gates.map(gateEntry(mod)), end].join('\n');
+    actions.push({ disposition: 'gate', target: '.ai/gates.toml', note: `${mod.name}: ${mod.gates.length} entries` });
+    if (dryRun) continue;
+    mkdirSync(dirname(registry), { recursive: true });
+    writeFileSync(registry, mergeBlock(existing, body, mod.name));
+  }
+  return actions;
+}
+
+const gateEntry = (mod: Manifest) => (g: Manifest['gates'][number]) => {
+  const lines = ['', '[[gates]]', `id     = "${g.id}"`, `kind   = "${g.kind}"`, `module = "${mod.name}"`];
+  if (g.engine) lines.push(`engine = "${g.engine}"`);
+  if (g.table) lines.push(`table  = "${mod.name}/${g.table.replace(/^gates\//, '')}"`);
+  if (g.command) lines.push(`command = "${g.command}"`);
+  if (g.tier) lines.push(`tier   = "${g.tier}"`);
+  if (g.trigger) lines.push(`trigger = "${g.trigger}"`);
+  if (g.matcher) lines.push(`matcher = "${g.matcher}"`);
+  // `why` is carried into the repo because ADR-0005 tier B quotes it back when
+  // a gate has never fired. A gate whose reason lives only in this CLI cannot
+  // be asked about by a repo that has it installed.
+  if (g.why) lines.push(`why    = """${g.why.trim()}"""`);
+  return lines.join('\n');
+};
+
+/** Dependency order, refusing anything unmet — naming the incident (ADR-0003). */
+export function resolveInstallOrder(requested: string[], all: Manifest[]): { order: Manifest[]; missing: string[] } {
+  const byName = new Map(all.map((m) => [m.name, m]));
+  const order: Manifest[] = [];
+  const missing: string[] = [];
+  const seen = new Set<string>();
+  const visit = (name: string) => {
+    if (seen.has(name)) return;
+    const mod = byName.get(name);
+    if (!mod) {
+      missing.push(name);
+      return;
+    }
+    seen.add(name);
+    for (const dep of mod.requires) visit(dep);
+    order.push(mod);
+  };
+  // A module's gates are inert without the runner that executes them. Installing
+  // `backlog` alone produced a `.ai/gates.toml` holding three entries and no
+  // `[runner]` block — a registry nothing reads. Rather than making every
+  // gate-shipping module declare the dependency (and `instructions`, which ships
+  // gates and is what `gates` itself requires, could not), the runner is pulled
+  // in whenever anything registers with it.
+  //
+  // It is visited **first**, not appended: installed last it arrived after other
+  // modules had already merged entries into the registry, so its own file — the
+  // one carrying `[runner]` — hit the never-overwrite rule and was skipped. The
+  // owner of a shared file has to create it before anyone merges into it.
+  const closure = new Set<string>();
+  const collect = (n: string) => {
+    if (closure.has(n)) return;
+    const m = byName.get(n);
+    if (!m) return;
+    closure.add(n);
+    m.requires.forEach(collect);
+  };
+  requested.forEach(collect);
+  if ([...closure].some((n) => byName.get(n)!.gates.length) && byName.has('gates')) {
+    visit('gates');
+  }
+
+  for (const r of requested) visit(r);
+  return { order, missing };
+}
+
+/**
+ * Content hash of what a module emitted, recorded at install.
+ *
+ * Without it `upgrade` cannot tell a file the user edited from one an older
+ * module version wrote — and those want opposite treatment: the first is a
+ * decision to respect, the second is the thing upgrade exists to replace.
+ * It is also what makes ADR-0004's `ours-current` and `ours-diverged` states
+ * decidable at all.
+ */
+export const contentHash = (s: string) => createHash('sha256').update(s.replace(/\r\n/g, '\n')).digest('hex').slice(0, 12);
+
+/**
+ * Files a module owns **outright** — not the shared ones it merges into.
+ *
+ * `AGENTS.md` and `.ai/gates.toml` are co-owned: a module creates them and then
+ * every other module merges a block in, so their content differs from what any
+ * single module emitted the moment the second module installs. Hashing them
+ * reported both as diverged on a completely untouched repo. A file carrying
+ * managed blocks is never whole-file upgraded — its **blocks** are, through the
+ * merge path.
+ */
+const SHARED = new Set(['AGENTS.md', 'CLAUDE.md', '.gitignore', '.gitattributes', '.ai/gates.toml']);
+
+export function emittedFiles(mod: Manifest, params: Params, skillsDir = '.claude/skills'): Map<string, string> {
+  const out = new Map<string, string>();
+  const sub = (t: string) => substitute(t, mod.name, params);
+  for (const [dir, prefix] of [
+    ['files', ''],
+    ['rules', '.ai/rules/'],
+    ['skills', `${skillsDir}/`],
+  ] as const) {
+    const base = join(mod.dir, dir);
+    if (!existsSync(base)) continue;
+    for (const rel of walk(base)) {
+      const target = sub(prefix + rel).split('\\').join('/');
+      if (SHARED.has(target)) continue;
+      out.set(target, sub(readFileSync(join(base, rel), 'utf8')));
+    }
+  }
+  return out;
+}
+
+export function writeInstallRecord(
+  repoRoot: string,
+  mods: Manifest[],
+  params: Params,
+  harnesses: string[],
+  stamp: string,
+  skillsDir = '.claude/skills',
+  /** Per module, the files rungs actually created — as opposed to kept. */
+  wroteByModule?: Map<string, Set<string>>,
+) {
+  const lines = [
+    '# Installed by `rungs`. Edit parameters here and re-run `rungs render`.',
+    '# Hashes are what rungs emitted; a file whose hash no longer matches is a',
+    '# divergence rungs reports and never overwrites.',
+    '',
+    '[repo]',
+    `harnesses = ${JSON.stringify(harnesses)}`,
+    `installed = "${stamp}"`,
+    '',
+  ];
+  for (const m of mods) {
+    lines.push(`[modules.${m.name}]`, `version = "${m.version}"`, 'state   = "managed"');
+    const p = params[m.name] ?? {};
+    if (Object.keys(p).length) {
+      lines.push(`params  = { ${Object.entries(p).map(([k, v]) => `${k} = ${JSON.stringify(v ?? '')}`).join(', ')} }`);
+    }
+    // Only files rungs actually **wrote** get a hash. A file that already
+    // existed was kept, and hashing it with our content would later read as a
+    // divergence the user caused — implying they broke something they never
+    // touched. Kept files are listed separately and stay theirs forever.
+    const emitted = emittedFiles(m, params, skillsDir);
+    const created = [...emitted].filter(([rel]) => (wroteByModule?.get(m.name)?.has(rel) ?? existsSync(join(repoRoot, rel))));
+    const kept = [...emitted].filter(([rel]) => !created.some(([c]) => c === rel) && existsSync(join(repoRoot, rel)));
+    if (created.length) {
+      lines.push(`[modules.${m.name}.hashes]`);
+      for (const [rel, content] of created) lines.push(`"${rel}" = "${contentHash(content)}"`);
+    }
+    if (kept.length) {
+      lines.push('', `[modules.${m.name}]`.replace(']', '.kept]'));
+      lines.push(`files = ${JSON.stringify(kept.map(([rel]) => rel))}`);
+    }
+    lines.push('');
+  }
+  writeFileSync(join(repoRoot, '.ai', 'rungs.toml'), lines.join('\n'));
+}
+
+export interface AdoptedGate {
+  id: string;
+  command: string;
+  tier: string;
+  source: string;
+}
+
+/**
+ * Turn detected `adopt_as` matches into `command` gate entries.
+ *
+ * The interpreter is chosen from the extension, and an unknown one is skipped
+ * rather than guessed at — a registry entry that cannot run is worse than one
+ * that is absent, because it reports as a failure the owner did not cause.
+ */
+export function adoptableGates(files: string[], patterns: string[], repoRoot: string): AdoptedGate[] {
+  const runner: Record<string, string> = { '.mjs': 'node', '.js': 'node', '.ps1': 'pwsh -File', '.sh': 'bash' };
+  const out: AdoptedGate[] = [];
+  for (const pattern of patterns) {
+    for (const rel of matchAny(files, pattern)) {
+      const ext = rel.slice(rel.lastIndexOf('.'));
+      const exec = runner[ext];
+      if (!exec) continue;
+      out.push({
+        id: `adopted-${rel.split('/').pop()!.replace(/\.[^.]+$/, '')}`,
+        command: `${exec} ${rel}`,
+        tier: 'fast',
+        source: rel,
+      });
+    }
+  }
+  return out;
+}

package/src/check.ts

@@ -0,0 +1,216 @@
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'smol-toml';
+import { ENGINES, isImplemented, type Finding } from './engines.ts';
+import { walk } from './glob.ts';
+import { resolveParams, substitute, type Params } from './substitute.ts';
+import { loadAllModules } from './manifest.ts';
+
+const MODULES = join(dirname(fileURLToPath(import.meta.url)), '..', 'modules');
+
+export type Status = 'pass' | 'fail' | 'unimplemented' | 'error';
+
+export interface GateRun {
+  id: string;
+  module?: string;
+  kind: string;
+  engine?: string;
+  tier: string;
+  status: Status;
+  ms: number;
+  examined: number;
+  findings: Finding[];
+  why?: string;
+}
+
+interface RegistryGate {
+  id: string;
+  kind: string;
+  module?: string;
+  engine?: string;
+  table?: string;
+  command?: string;
+  tier?: string;
+  trigger?: string;
+  why?: string;
+}
+
+export function loadRegistry(repoRoot: string): { runner: any; gates: RegistryGate[] } {
+  const path = join(repoRoot, '.ai', 'gates.toml');
+  if (!existsSync(path)) return { runner: {}, gates: [] };
+  const raw = parse(readFileSync(path, 'utf8')) as any;
+  return { runner: raw.runner ?? {}, gates: raw.gates ?? [] };
+}
+
+export function runGates(repoRoot: string, tier?: string, now = () => Date.now()): GateRun[] {
+  const { gates } = loadRegistry(repoRoot);
+  const files = walk(repoRoot);
+  const runs: GateRun[] = [];
+
+  for (const g of gates) {
+    // A hook fires on a tool call, not in the runner. Skipping it here is
+    // correct; counting it as a pass would not be.
+    if (g.trigger) continue;
+    if (tier && g.tier && g.tier !== tier) continue;
+
+    const started = now();
+    let status: Status = 'pass';
+    let findings: Finding[] = [];
+    let examined = 0;
+
+    if (g.kind === 'command' && g.command) {
+      try {
+        execSync(g.command, { cwd: repoRoot, stdio: 'pipe' });
+      } catch (e: any) {
+        status = 'fail';
+        findings = [{ message: String(e.stderr ?? e.stdout ?? e.message).trim().split('\n').slice(-3).join(' ') }];
+      }
+    } else if (!g.engine || !isImplemented(g.engine)) {
+      // Never green. An engine named in a table and missing from the CLI is an
+      // unknown, and a registry reporting green because most of its gates do
+      // nothing is the worst failure this tool could have.
+      status = 'unimplemented';
+      findings = [{ message: `engine '${g.engine ?? '(none)'}' is not implemented` }];
+    } else {
+      const table = loadTable(g.table, repoRoot);
+      if (!table) {
+        status = 'error';
+        findings = [{ message: `table '${g.table}' not found` }];
+      } else {
+        try {
+          const key = tableKey(g.engine);
+          let section = table[key] ?? table;
+          // An array table holds one entry per gate; select by trailing id.
+          if (Array.isArray(section) && section.some((s: any) => s?.id)) {
+            const mine = section.filter((s: any) => !s.id || g.id.includes(s.id));
+            if (mine.length) section = mine;
+          }
+          const r = ENGINES[g.engine](section, repoRoot, files);
+          findings = r.findings;
+          examined = r.examined;
+          status = r.findings.length ? 'fail' : 'pass';
+        } catch (e: any) {
+          status = 'error';
+          findings = [{ message: e.message }];
+        }
+      }
+    }
+
+    runs.push({
+      id: g.id,
+      module: g.module,
+      kind: g.kind,
+      engine: g.engine,
+      tier: g.tier ?? 'fast',
+      status,
+      ms: now() - started,
+      examined,
+      findings,
+      why: g.why,
+    });
+  }
+  return runs;
+}
+
+/**
+ * A table lives in the CLI's module set, not in the repo (ADR-0002) — but it is
+ * authored with `{{param}}` placeholders, so it is **not valid TOML until
+ * substituted**: `max_lines = {{core_budget}}` parses as nothing.
+ *
+ * Found by running the runner, which reported `table not found` for a file
+ * plainly on disk. Tables are substituted against the repo's own installed
+ * parameters before parsing — which is also what makes a gate honour the
+ * prefix, root and budget that repo actually chose.
+ */
+function loadTable(ref: string | undefined, repoRoot: string): any | null {
+  if (!ref) return null;
+  const [mod, file] = ref.split('/');
+  const path = join(MODULES, mod, 'gates', file);
+  if (!existsSync(path)) return null;
+  try {
+    return parse(substitute(readFileSync(path, 'utf8'), mod, installedParams(repoRoot)));
+  } catch {
+    return null;
+  }
+}
+
+let paramCache: { root: string; params: Params } | null = null;
+
+/** Parameters as the repo installed them, falling back to module defaults. */
+function installedParams(repoRoot: string): Params {
+  if (paramCache?.root === repoRoot) return paramCache.params;
+  const defaults = resolveParams(loadAllModules(MODULES));
+  const recordPath = join(repoRoot, '.ai', 'rungs.toml');
+  if (existsSync(recordPath)) {
+    try {
+      const rec = parse(readFileSync(recordPath, 'utf8')) as any;
+      for (const [name, entry] of Object.entries<any>(rec.modules ?? {})) {
+        if (entry?.params) defaults[name] = { ...(defaults[name] ?? {}), ...entry.params };
+      }
+    } catch {
+      /* a malformed record falls back to defaults rather than failing every gate */
+    }
+  }
+  paramCache = { root: repoRoot, params: defaults };
+  return defaults;
+}
+
+const tableKey = (engine: string) =>
+  ({
+    'file-budget': 'file_budget',
+    sections: 'sections',
+    'frontmatter-schema': 'frontmatter_schema',
+    'link-integrity': 'link_integrity',
+    'file-population': 'file_population',
+    'gate-meta': 'gate_meta',
+    'id-integrity': '__whole__',
+    'render-freshness': 'render_freshness',
+    'register-schema': 'register_schema',
+    'filename-schema': 'filename_schema',
+    'cross-reference': 'cross_reference',
+    'git-status-reconcile': 'merged_status',
+    'computed-claim': 'computed_claim',
+    'term-ownership': 'term_ownership',
+    'rule-propagation': 'rule_propagation',
+    'git-state': 'git_state',
+    'merge-driver-check': 'merge_driver_check',
+  })[engine] ?? engine;
+
+/**
+ * ADR-0005 tier A. One line per gate per run: what the runner directly observes
+ * and nothing that needs interpretation. Local, gitignored, never transmitted.
+ */
+export function appendLedger(repoRoot: string, runs: GateRun[], stamp: string) {
+  const { runner } = loadRegistry(repoRoot);
+  if (runner.ledger === false) return;
+  const path = join(repoRoot, '.ai', '.gate-ledger.jsonl');
+  const lines = runs
+    .map((r) => JSON.stringify({ at: stamp, id: r.id, status: r.status, ms: r.ms, examined: r.examined }))
+    .join('\n');
+  appendFileSync(path, lines + '\n');
+}
+
+/** The two questions ADR-0005 tier B allows, both binary facts. */
+export function ledgerQuestions(repoRoot: string, gates: RegistryGate[]) {
+  const path = join(repoRoot, '.ai', '.gate-ledger.jsonl');
+  if (!existsSync(path)) return { neverFired: [], alwaysFires: [], runs: 0 };
+  const rows = readFileSync(path, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => JSON.parse(l) as { id: string; status: Status });
+  const by = new Map<string, { total: number; failed: number }>();
+  for (const r of rows) {
+    const e = by.get(r.id) ?? { total: 0, failed: 0 };
+    e.total++;
+    if (r.status === 'fail') e.failed++;
+    by.set(r.id, e);
+  }
+  const whyOf = (id: string) => gates.find((g) => g.id === id)?.why;
+  const neverFired = [...by].filter(([, e]) => e.total >= 3 && e.failed === 0).map(([id]) => ({ id, why: whyOf(id) }));
+  const alwaysFires = [...by]
+    .filter(([, e]) => e.total >= 3 && e.failed / e.total > 0.9)
+    .map(([id, e]) => ({ id, why: whyOf(id), rate: `${e.failed}/${e.total}` }));
+  return { neverFired, alwaysFires, runs: rows.length };
+}