@veda-hq/kavach 0.0.0-stage → 0.3.0

package/dist/rule-checks/args.js

@@ -0,0 +1,26 @@
+/** Command-line options of the rule-check CLIs: `--name value` pairs and bare flags. */
+/** The value after `--name`; undefined when the option is absent. Throws when it has no value. */
+export function option(argv, name) {
+    const at = argv.indexOf(name);
+    if (at === -1)
+        return undefined;
+    const value = argv[at + 1];
+    if (value === undefined || value.startsWith('--'))
+        throw new Error(`${name} needs a value`);
+    return value;
+}
+/**
+ * Refuse any word that is neither one of `options` (with its value) nor one
+ * of `flags`, so a mistyped option fails loudly instead of being ignored.
+ */
+export function onlyKnown(argv, options, flags = []) {
+    let value = false;
+    for (const word of argv) {
+        if (value)
+            value = false;
+        else if (options.includes(word))
+            value = true;
+        else if (!flags.includes(word))
+            throw new Error(`unknown argument ${JSON.stringify(word)}`);
+    }
+}

package/dist/rule-checks/cli-entry.js

@@ -0,0 +1,42 @@
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Is this module the script node was asked to run, rather than an import?
+ *
+ * Every CLI needs this: run when invoked, stay inert when a test imports it.
+ * Getting it wrong in the "inert" direction is silent gate death: the hook
+ * invokes the file, nothing runs, and the call passes with a successful exit
+ * status and no output at all. A guard that compares `process.argv[1]` to
+ * `import.meta.url` by path equality does exactly that through a symlink.
+ *
+ * The trap: node resolves symlinks when it builds `import.meta.url`, but
+ * `process.argv[1]` stays whatever path the caller typed. Any repo reached
+ * through a symlink (a linked worktree, a symlinked checkout, `/tmp` on
+ * macOS, a package manager's `node_modules/.bin` link) makes the two unequal
+ * for the same file. Comparing real paths is what closes it.
+ *
+ * @param entryPath  `process.argv[1]` from the calling module.
+ * @param moduleUrl  `import.meta.url` from the calling module.
+ */
+export function isCliEntry(entryPath, moduleUrl) {
+    if (entryPath === undefined)
+        return false;
+    const self = fileURLToPath(moduleUrl);
+    // Fast path: the common, non-symlinked invocation, and the only one that
+    // still works if the module were deleted from disk mid-run.
+    if (resolve(entryPath) === self)
+        return true;
+    try {
+        return realpathSync(entryPath) === realpathSync(self);
+    }
+    catch {
+        // An entry path that does not resolve cannot be this file: node resolves
+        // argv[1] to a real path before executing it. So this is an import whose
+        // host has an exotic argv[1] (a worker thread, a bundler's virtual
+        // module), and returning true would run the CLI body during import.
+        // Returning false cannot hide a CLI run either: a real invocation always
+        // has a resolvable entry.
+        return false;
+    }
+}

package/dist/rule-checks/cli.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * The rule-check CLI, `dist/rule-checks/cli.js`.
+ *
+ *   cli.js [--checks <module>] [--registry <json>] [--fires-dir <dir>]
+ *     The hook. Reads one Claude Code hook event on stdin, runs the
+ *     consumer's checks on it (runtime.ts) and answers on stdout; exits 0.
+ *     --checks     the consumer's checks module, a file Node can import
+ *                  (`.js`, `.mjs`, or `.ts` that Node strips types from). It
+ *                  exports `CHECKS`, or a default export, a list of `Check`
+ *                  (runtime.ts). Env: KAVACH_RULE_CHECKS.
+ *     --registry   the consumer's rule registry JSON (registry.ts). Optional:
+ *                  without one every rule reads as unregistered and a refusal
+ *                  says to ask "the repository owner". Env: KAVACH_RULE_REGISTRY.
+ *     --fires-dir  the fire-log folder. Default: `.tmp/rule-checks` in the
+ *                  primary checkout of the session's `cwd`. Env:
+ *                  KAVACH_RULE_FIRES_DIR.
+ *     A flag wins over its variable. Relative paths resolve against
+ *     CLAUDE_PROJECT_DIR, else the current folder.
+ *     Fails open: a missing or broken checks module, a bad flag, or any crash
+ *     is answered with a warning and a crash row in the fire log, and the call
+ *     goes ahead. A crash it could not catch exits non-zero, which Claude Code
+ *     reports as a non-blocking error.
+ *
+ *   cli.js count [--registry <json>] [--root <dir>] [--json]
+ *     How many registry rules no enforcer file in the checkout enforces.
+ *   cli.js latency [--root <dir>] [--rounds N]
+ *     Time the checkout's Bash PreToolUse hooks (latency.ts).
+ *   cli.js push-marker write|clear <git-dir> <pid>
+ *     Write or clear a push's marker, from a pre-push hook (live-runs.ts).
+ *
+ * A hook registration, in `.claude/settings.json`:
+ *   "command": "node node_modules/@veda-hq/kavach/dist/rule-checks/cli.js
+ *               --checks rules/checks.ts --registry rules/registry.json"
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { onlyKnown, option } from './args.js';
+import { isCliEntry } from './cli-entry.js';
+import { FIRES_DIR_ENV } from './fire-log.js';
+import { main as latency } from './latency.js';
+import { liveEffects, main as pushMarker } from './live-runs.js';
+import { main as count, REGISTRY_ENV, STDIO } from './registry.js';
+import { liveDeps, runHook } from './runtime.js';
+/** The environment variable the hook reads the checks module from. */
+export const CHECKS_ENV = 'KAVACH_RULE_CHECKS';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isTexts = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string');
+/** Does `value` have the shape of a `Check`? */
+export function isCheck(value) {
+    return (isRecord(value) &&
+        typeof value['rule'] === 'string' &&
+        isTexts(value['events']) &&
+        (value['tools'] === undefined || isTexts(value['tools'])) &&
+        typeof value['cost'] === 'string' &&
+        typeof value['instead'] === 'string' &&
+        typeof value['run'] === 'function');
+}
+/** The checks a loaded module exports as `CHECKS`, else as its default export; throws naming what is wrong. */
+export function checksOf(loaded, where) {
+    const exported = isRecord(loaded) ? (loaded['CHECKS'] ?? loaded['default']) : undefined;
+    if (!Array.isArray(exported)) {
+        throw new Error(`${where} exports no list of checks (as CHECKS or its default export)`);
+    }
+    const checks = [];
+    for (const [i, item] of exported.entries()) {
+        if (!isCheck(item)) {
+            throw new Error(`${where}: check ${i} is not a check (rule, events, cost, instead and run)`);
+        }
+        checks.push(item);
+    }
+    return checks;
+}
+/** Import the consumer's checks module at `path`. */
+export async function loadChecks(path) {
+    const loaded = await import(__rewriteRelativeImportExtension(pathToFileURL(path).href));
+    return checksOf(loaded, path);
+}
+/** A flag's value, else its variable's; undefined when neither names one. */
+function chosen(argv, flag, env, name) {
+    const value = option(argv, flag) ?? env[name];
+    return value === '' ? undefined : value;
+}
+/** The hook: the answer to one hook event on `stdin`. Never throws. */
+export async function hook(argv, stdin, env) {
+    const base = env['CLAUDE_PROJECT_DIR'] ?? process.cwd();
+    const at = (path) => (path === undefined ? undefined : resolve(base, path));
+    let registry;
+    let firesDir;
+    let checks;
+    try {
+        // The fire-log folder first, so that any failure after it is logged there.
+        firesDir = at(chosen(argv, '--fires-dir', env, FIRES_DIR_ENV));
+        registry = at(chosen(argv, '--registry', env, REGISTRY_ENV));
+        onlyKnown(argv, ['--checks', '--registry', '--fires-dir']);
+        const path = at(chosen(argv, '--checks', env, CHECKS_ENV));
+        if (path === undefined)
+            throw new Error(`no checks module: pass --checks or set ${CHECKS_ENV}`);
+        checks = await loadChecks(path);
+    }
+    catch (error) {
+        // fail-open: the runtime logs the failure as its own crash, under the event.
+        const failure = error instanceof Error ? error : new Error(String(error));
+        checks = () => {
+            throw failure;
+        };
+    }
+    return runHook(stdin, { ...liveDeps(env, { registry, firesDir }), checks });
+}
+/** The CLI; returns the exit status. */
+export async function run(argv, io, stdin, env) {
+    const [command, ...rest] = argv;
+    if (command === 'count')
+        return count(rest, io, process.cwd(), env);
+    if (command === 'push-marker')
+        return pushMarker(rest, liveEffects, io.err);
+    if (command === 'latency') {
+        try {
+            await latency(rest, process.cwd(), io.out);
+            return 0;
+        }
+        catch (error) {
+            io.err(`latency: ${error instanceof Error ? error.message : String(error)}`);
+            return 2;
+        }
+    }
+    io.write(await hook(argv, stdin(), env));
+    return 0;
+}
+if (isCliEntry(process.argv[1], import.meta.url)) {
+    process.exitCode = await run(process.argv.slice(2), {
+        ...STDIO,
+        write: (text) => {
+            process.stdout.write(text);
+        },
+    }, () => readFileSync(0).toString(), process.env);
+}

package/dist/rule-checks/edit-text.js

@@ -0,0 +1,23 @@
+/**
+ * The text a file-writing tool call proposes: what an edit-time check judges
+ * before the tool runs.
+ */
+/**
+ * The file's text once the tool has run: a Write's content; an Edit applied to
+ * `current`. An Edit whose old text is not in the file fails anyway, so its
+ * new text is judged beside the current file.
+ */
+export function afterEdit(tool, given, current) {
+    const text = (key) => {
+        const value = given[key];
+        return typeof value === 'string' ? value : '';
+    };
+    if (tool === 'Write')
+        return text('content');
+    const before = current ?? '';
+    const old = text('old_string');
+    const next = text('new_string');
+    if (old === '' || !before.includes(old))
+        return `${before}\n${next}`;
+    return given['replace_all'] === true ? before.split(old).join(next) : before.replace(old, () => next);
+}

package/dist/rule-checks/fire-log.js

@@ -0,0 +1,81 @@
+/**
+ * The fire log: one JSON line per check that refused, warned, was passed with
+ * a stated reason, or crashed.
+ *
+ * Where: the folder the caller names (`firesDir`'s override: the runtime's
+ * `firesDir` option, the CLI's `--fires-dir` or `KAVACH_RULE_FIRES_DIR`), else
+ * `<primary checkout>/.tmp/rule-checks/fires.jsonl`, the checkout that owns
+ * the git common directory, so rows from every worktree land in one file and
+ * outlive the worktree.
+ *
+ * Shared state, written by hooks running in parallel across sessions:
+ * - Ordering: nothing claims or waits on the file; readers only read history.
+ * - Failure cleanup: a failed or short append leaves no row or one partial
+ *   line, never a stale record another process trusts, and throws so the
+ *   runtime reports the missed row. A short write is not retried: a second
+ *   append could land after another writer's row and split this one. The next
+ *   append starts on a fresh line, so only the partial line fails to parse,
+ *   and a reader skips it.
+ * - Overlap: every append is one write of whole lines (O_APPEND);
+ *   rows are short (the excerpt is capped), nothing truncates, rewrites or
+ *   sweeps the file, so writers cannot erase each other's rows. Two writers
+ *   that both find a partial line both start a fresh one: one empty line.
+ * - Input validity: rows are built here from typed values; nothing in this
+ *   module reads the file back.
+ * Accepted limit: an append on a network filesystem may interleave; keep the
+ *   folder on a local disk.
+ */
+import { closeSync, fstatSync, mkdirSync, openSync, readSync, writeSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const EXCERPT_MAX = 120;
+export const FIRES_FILE = 'fires.jsonl';
+/** The environment variable the CLI reads the fire-log folder from. */
+export const FIRES_DIR_ENV = 'KAVACH_RULE_FIRES_DIR';
+/** `value` on one line, at most `max` characters, an ellipsis marking a cut. */
+export function clip(value, max = EXCERPT_MAX) {
+    const line = value.replace(/\s+/g, ' ').trim();
+    return line.length <= max ? line : `${line.slice(0, max - 1)}…`;
+}
+/**
+ * The folder the fire log lives in for a session whose checkout is `root`:
+ * `override` when it names one, else `.tmp/rule-checks` in the primary checkout.
+ */
+export function firesDir(override, root, git) {
+    if (override !== undefined && override !== '')
+        return override;
+    const common = git(root, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    return join(dirname(common), '.tmp', 'rule-checks');
+}
+/** The branch checked out at `root`; `HEAD` when detached, `unknown` outside git. */
+export function branchAt(root, git) {
+    try {
+        return git(root, ['branch', '--show-current']) || 'HEAD';
+    }
+    catch {
+        // fail-open: a row without its branch still records the fire.
+        return 'unknown';
+    }
+}
+/** A newline when the log ends in a partial line a failed append left. */
+function freshLine(fd) {
+    const { size } = fstatSync(fd);
+    if (size === 0)
+        return '';
+    const last = Buffer.alloc(1);
+    readSync(fd, last, 0, 1, size - 1);
+    return last.toString() === '\n' ? '' : '\n';
+}
+export function appendFires(dir, rows, write = writeSync) {
+    mkdirSync(dir, { recursive: true });
+    const fd = openSync(join(dir, FIRES_FILE), 'a+');
+    try {
+        const lines = rows.map((row) => `${JSON.stringify(row)}\n`).join('');
+        const bytes = Buffer.from(freshLine(fd) + lines);
+        const wrote = write(fd, bytes);
+        if (wrote !== bytes.length)
+            throw new Error(`fire log: wrote ${wrote} of ${bytes.length} bytes`);
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/rule-checks/latency.js

@@ -0,0 +1,192 @@
+/**
+ * Hook latency on the Bash path: every PreToolUse hook the checkout's
+ * `.claude/settings.json` registers for Bash, fed a fixed set of everyday
+ * commands, timed alone and all together.
+ *
+ * Claude Code runs the hooks that match one call in parallel
+ * (https://code.claude.com/docs/en/hooks, "All matching hooks run in
+ * parallel"), so the "per call" line, every hook started at once and timed to
+ * the last exit, is what a Bash call waits; the per-hook lines say which hook
+ * sets it. A budget worth holding each check to is p95 ≤ 150 ms.
+ *
+ * Hooks only read the command they are handed, so replaying these commands
+ * runs none of them. The load average and the interpreters on PATH are printed
+ * with the numbers, because both move them.
+ *
+ * The timed hooks run with `KAVACH_RULE_FIRES_DIR` pointed at
+ * {@link LATENCY_FIRES}, so their refusals stay out of the real fire log; a
+ * hook registered with its own `--fires-dir` keeps writing there.
+ *
+ * `cli.js latency [--root <dir>] [--rounds N]` (default: the current folder,
+ * 5 rounds over the corpus).
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { loadavg } from 'node:os';
+import { join, resolve } from 'node:path';
+import { FIRES_DIR_ENV } from './fire-log.js';
+/** Commands an agent runs every hour, from cheap reads to pushes. */
+export const CORPUS = [
+    'git status --short',
+    'ls src',
+    'grep -n "export" src/index.ts',
+    'node --version',
+    'git log --oneline -5',
+    'git diff --stat origin/main',
+    'git add README.md',
+    'git commit -m "docs: note"',
+    'git push -u origin HEAD',
+    'gh pr view --json number,state',
+];
+/** The PreToolUse hook commands whose matcher selects the Bash tool. */
+export function bashHooks(settings) {
+    return (settings.hooks?.['PreToolUse'] ?? [])
+        .filter((entry) => new RegExp(`^(?:${entry.matcher ?? '.*'})$`).test('Bash'))
+        .flatMap((entry) => entry.hooks.map((hook) => hook.command));
+}
+/** Nearest-rank percentile of ascending `sorted`; 0 for no samples. */
+export function percentile(sorted, p) {
+    return sorted[Math.min(sorted.length, Math.ceil((p / 100) * sorted.length)) - 1] ?? 0;
+}
+export function hookInput(root, command) {
+    return JSON.stringify({
+        hook_event_name: 'PreToolUse',
+        tool_name: 'Bash',
+        cwd: root,
+        tool_input: { command, description: 'latency probe' },
+    });
+}
+/** A hook that has not exited by now is hung, not slow. */
+export const HOOK_TIMEOUT_MS = 30_000;
+/**
+ * `bash -c command` with `input` on stdin, in its own process group so a
+ * hook that hangs is killed with everything it started.
+ */
+function runBash(command, input, env, timeoutMs) {
+    return new Promise((done) => {
+        const child = spawn('bash', ['-c', command], { env, stdio: ['pipe', 'ignore', 'ignore'], detached: true });
+        let settled = false;
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            done(outcome);
+        };
+        const timer = setTimeout(() => {
+            try {
+                // Never `kill(-0)`: without a pid that would signal this process's own group.
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                // fail-open: a group that already ended has nothing left to kill.
+            }
+            settle('timeout');
+        }, timeoutMs);
+        child.on('error', () => settle('spawn-error'));
+        child.on('exit', () => settle('exit'));
+        // A hook may exit without reading its input; the broken pipe is no failure.
+        child.stdin.on('error', () => undefined);
+        child.stdin.end(input);
+    });
+}
+/**
+ * Milliseconds from starting `command` under bash with `input` on stdin to its
+ * exit, whatever its status: a refusal is as much an answer as a pass.
+ */
+export async function timeHook(command, input, env, timeoutMs = HOOK_TIMEOUT_MS, clock = () => performance.now()) {
+    const start = clock();
+    const outcome = await runBash(command, input, env, timeoutMs);
+    if (outcome !== 'exit')
+        throw new Error(`${command}: ${outcome}`);
+    return clock() - start;
+}
+/** Where the timed hooks' fires go, under the measured checkout. */
+export const LATENCY_FIRES = '.tmp/rule-checks/latency-fires';
+/** Run `steps` one after another: timings taken side by side would load each other. */
+function inTurn(steps) {
+    return steps.reduce((done, step) => done.then(step), Promise.resolve());
+}
+/** Every hook alone, then all at once, `rounds` times over `corpus`. */
+export async function measure(hooks, corpus, rounds, root, clock = () => performance.now()) {
+    // The corpus's foreground push may be refused; timing runs must not write
+    // those refusals into the fire log the count and reviews read.
+    const env = {
+        ...process.env,
+        CLAUDE_PROJECT_DIR: root,
+        [FIRES_DIR_ENV]: join(root, LATENCY_FIRES),
+    };
+    const alone = hooks.map((name) => ({ name, ms: [] }));
+    const together = { name: 'per call (all in parallel)', ms: [] };
+    const calls = Array.from({ length: rounds }, () => corpus).flat();
+    await inTurn(calls.flatMap((command) => {
+        const input = hookInput(root, command);
+        return [
+            ...alone.map((series) => async () => {
+                series.ms.push(await timeHook(series.name, input, env));
+            }),
+            async () => {
+                const start = clock();
+                await Promise.all(hooks.map((hook) => timeHook(hook, input, env)));
+                together.ms.push(clock() - start);
+            },
+        ];
+    }));
+    return [...alone, together];
+}
+/** Where an interpreter resolves on PATH; `missing` when it does not. */
+export function which(program) {
+    const found = spawnSync('bash', ['-c', `command -v ${program}`], {
+        encoding: 'utf8',
+    });
+    return found.stdout.trim() || 'missing';
+}
+export function render(series, load, tools) {
+    const lines = [
+        `load average ${load.map((value) => value.toFixed(2)).join(' ')}`,
+        ...Object.entries(tools).map(([name, path]) => `${name}: ${path}`),
+        '',
+        'hook | samples | p50 ms | p95 ms | max ms',
+    ];
+    for (const { name, ms } of series) {
+        const sorted = [...ms].sort((a, b) => a - b);
+        lines.push([
+            name,
+            sorted.length,
+            percentile(sorted, 50).toFixed(0),
+            percentile(sorted, 95).toFixed(0),
+            percentile(sorted, 100).toFixed(0),
+        ].join(' | '));
+    }
+    return lines.join('\n');
+}
+export function rounds(argv) {
+    const at = argv.indexOf('--rounds');
+    if (at === -1)
+        return 5;
+    const value = Number(argv[at + 1]);
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error('--rounds needs a positive whole number');
+    }
+    return value;
+}
+/** The checkout whose settings and hooks are timed: `--root`, else `fallback`. */
+export function rootOf(argv, fallback) {
+    const at = argv.indexOf('--root');
+    if (at === -1)
+        return fallback;
+    const value = argv[at + 1];
+    if (value === undefined)
+        throw new Error('--root needs a folder');
+    return resolve(value);
+}
+export async function main(argv, fallbackRoot, out) {
+    const root = rootOf(argv, fallbackRoot);
+    const settings = JSON.parse(readFileSync(join(root, '.claude', 'settings.json'), 'utf8'));
+    const series = await measure(bashHooks(settings), CORPUS, rounds(argv), root);
+    out(render(series, loadavg(), {
+        node: which('node'),
+        python3: which('python3'),
+    }));
+}