@veda-hq/kavach 0.0.0-stage → 0.5.6

package/dist/rule-checks/live-runs.js

@@ -0,0 +1,282 @@
+/**
+ * Is a push or a preflight running in this worktree? Checks that refuse
+ * commits or heavy work while one runs read it from here.
+ *
+ * A push: the consumer's pre-push hook runs `cli.js push-marker write
+ * <git-dir> <pid>` when a real push starts and `cli.js push-marker clear
+ * <git-dir> <pid>` on exit. Each push writes its own marker, named by its pid
+ * ({@link markerName}), into the worktree's own git folder, so a second push
+ * in the same worktree neither overwrites nor clears the first's. A
+ * preflight: a background preflight keeps the run that owns the copy in a
+ * run record ({@link PREFLIGHT_RECORD} by default). Both records name a pid
+ * and its start identity, judged as {@link isGone} judges them: a dead pid,
+ * or a live one that provably started later (a reused pid), is no run. So a
+ * marker a killed push left behind blocks nothing, and a push in another
+ * worktree, with its own git folder, never blocks this one.
+ *
+ * `clear` removes that pid's marker only, and `write` first removes the
+ * markers of pushes that ended.
+ */
+import { execFileSync } from 'node:child_process';
+import { readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+/** The push markers' name prefix, in the worktree's git folder. */
+export const PUSH_MARKER_PREFIX = 'kavach-push-in-progress.';
+/** The default preflight run record, relative to the worktree. */
+export const PREFLIGHT_RECORD = join('.tmp', 'preflight-bg', 'current.json');
+/**
+ * The format every start identity is written in, as a prefix of the identity.
+ *
+ * Two identities are only comparable when they were read the same way. A
+ * record written by a reader that read `lstart` in local time, or in any
+ * future format, would differ from this reading for a process that is still
+ * the same one, and a difference is what declares a run ended. So an identity
+ * in any other format is treated like an unknown one: liveness alone decides.
+ */
+export const START_IDENTITY_FORMAT = 'lstart-utc-c/1';
+function isCurrentIdentity(identity) {
+    return identity !== null && identity.startsWith(`${START_IDENTITY_FORMAT} `);
+}
+/**
+ * Has the run provably ended: its pid is dead, or now belongs to a process
+ * that started later (a reused pid)?
+ *
+ * An unreadable current start is asked about liveness once more: a reused pid
+ * held by a short-lived process can pass the first probe and exit before `ps`
+ * reads its start, and the first answer is then stale. The recheck is
+ * `kill(0)` again, so a process that still runs, but whose start `ps` cannot
+ * read, stays live (a stale push marker once refused an edit this way).
+ */
+export function isGone(run, probe) {
+    if (!probe.isAlive(run.pid))
+        return true;
+    if (!isCurrentIdentity(run.startIdentity))
+        return false;
+    const current = probe.startIdentityOf(run.pid);
+    if (current === null)
+        return !probe.isAlive(run.pid);
+    return isCurrentIdentity(current) && current !== run.startIdentity;
+}
+function errorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error ? String(error.code) : undefined;
+}
+/** The real probe over `calls`. A `ps` reading is decoded with `String()`, which reads a Buffer as UTF-8. */
+export function processProbe(calls) {
+    return {
+        isAlive: (pid) => {
+            try {
+                calls.kill(pid, 0);
+            }
+            catch (error) {
+                // Only ESRCH says no such process. EPERM (it exists and belongs to
+                // someone else) or anything else is no evidence, so `ps` decides.
+                if (errorCode(error) === 'ESRCH')
+                    return false;
+            }
+            // Signal 0 also reaches a zombie (exited, not yet reaped), which would
+            // read as a live run for as long as its parent never waits. Only a
+            // state that says `Z` is dead; a `ps` that fails or prints nothing is
+            // not evidence, and the conservative reading of "unknown" is alive.
+            try {
+                const state = String(calls.exec('ps', ['-o', 'stat=', '-p', String(pid)], {
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                    env: { ...process.env, LC_ALL: 'C' },
+                })).trim();
+                return !state.startsWith('Z');
+            }
+            catch {
+                return true;
+            }
+        },
+        startIdentityOf: (pid) => {
+            try {
+                // Pinned to UTC and the C locale. `lstart` is printed in local time, so
+                // without this two readers whose shells carry different TZ values read
+                // different strings for the same live process, and the second judges
+                // a live run a reused pid.
+                const started = String(calls.exec('ps', ['-o', 'lstart=', '-p', String(pid)], {
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                    env: { ...process.env, TZ: 'UTC', LC_ALL: 'C' },
+                })).trim();
+                return started === '' ? null : `${START_IDENTITY_FORMAT} ${started}`;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+/** The real probe. */
+export const defaultProbe = processProbe({
+    exec: (file, args, options) => execFileSync(file, args, options),
+    kill: (pid, signal) => {
+        process.kill(pid, signal);
+    },
+});
+/** A run record's pid and start identity; `null` for anything else. */
+export function parseRun(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        // fail-open: a torn or foreign record names no run.
+        return null;
+    }
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const { pid, startIdentity } = value;
+    if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 1)
+        return null;
+    if (startIdentity !== null && typeof startIdentity !== 'string')
+        return null;
+    return { pid, startIdentity };
+}
+/** The live run recorded at `path`; `null` when none is recorded or it ended. */
+export function liveRun(path, read, probe) {
+    let raw;
+    try {
+        raw = read(path);
+    }
+    catch {
+        // fail-open: no record (or none readable) is no run.
+        return null;
+    }
+    const run = parseRun(raw);
+    return run === null || isGone(run, probe) ? null : run;
+}
+/**
+ * The git folder of the checkout at `root`, read from `root/.git` without
+ * running git: a folder in the primary checkout, a `gitdir:` file in a
+ * linked worktree.
+ */
+export function gitDir(root, read) {
+    const dotGit = join(root, '.git');
+    let text;
+    try {
+        text = read(dotGit);
+    }
+    catch {
+        // fail-open: a folder (the primary checkout) or nothing reads as .git itself.
+        return dotGit;
+    }
+    const named = /^gitdir: (.+)$/m.exec(text)?.[1];
+    if (named === undefined)
+        return dotGit;
+    return isAbsolute(named) ? named : resolve(root, named);
+}
+/** The marker push `pid` writes: one per push, so two pushes never share one. */
+export function markerName(pid) {
+    return `${PUSH_MARKER_PREFIX}${pid}.json`;
+}
+const MARKER_NAME = /^kavach-push-in-progress\.\d+\.json$/;
+/** A live push in the checkout at `root`, read from the first marker whose pid still runs. */
+export function livePush(root, read, list, probe) {
+    const dir = gitDir(root, read);
+    let names;
+    try {
+        names = list(dir);
+    }
+    catch {
+        // fail-open: an unreadable git folder names no push.
+        return null;
+    }
+    for (const name of names.filter((entry) => MARKER_NAME.test(entry))) {
+        const run = liveRun(join(dir, name), read, probe);
+        if (run !== null)
+            return run;
+    }
+    return null;
+}
+/** The live preflight in the checkout at `root`, from its run record (relative to `root`). */
+export function livePreflight(root, read, probe, record = PREFLIGHT_RECORD) {
+    return liveRun(resolve(root, record), read, probe);
+}
+export const readText = (path) => readFileSync(path, 'utf8');
+export const listDir = (dir) => readdirSync(dir);
+/**
+ * Remove the markers in `dir` whose push provably ended: a push killed before
+ * its exit trap ran leaves one, and each left behind is one more pid to be
+ * reused. A marker that does not parse names no push and stays.
+ */
+export function sweepMarkers(dir, effects) {
+    let names;
+    try {
+        names = effects.list(dir);
+    }
+    catch {
+        // fail-open: an unreadable git folder has nothing to sweep.
+        return;
+    }
+    for (const name of names.filter((entry) => MARKER_NAME.test(entry))) {
+        const path = join(dir, name);
+        try {
+            const run = parseRun(effects.read(path));
+            if (run !== null && isGone(run, effects.probe))
+                effects.remove(path);
+        }
+        catch {
+            // fail-open: a marker another sweep took first is already gone.
+        }
+    }
+}
+/**
+ * Write the marker for `pid`, atomically, after sweeping the ended pushes'
+ * markers. Throws when its start is unknown.
+ */
+export function writeMarker(dir, pid, effects) {
+    const startIdentity = effects.probe.startIdentityOf(pid);
+    if (startIdentity === null)
+        throw new Error(`no process ${pid}`);
+    sweepMarkers(dir, effects);
+    const path = join(dir, markerName(pid));
+    const staging = `${path}.tmp`;
+    effects.write(staging, `${JSON.stringify({ pid, startIdentity, startedAt: effects.now().toISOString() })}\n`);
+    effects.rename(staging, path);
+}
+/** Remove the marker `pid` wrote; another push's marker stays. */
+export function clearMarker(dir, pid, effects) {
+    effects.remove(join(dir, markerName(pid)));
+}
+export const liveEffects = {
+    probe: defaultProbe,
+    read: readText,
+    list: listDir,
+    write: (path, text) => writeFileSync(path, text),
+    rename: renameSync,
+    remove: (path) => rmSync(path, { force: true }),
+    now: () => new Date(),
+};
+/** A caught value as text, never throwing. */
+function errorDetail(error) {
+    try {
+        if (error instanceof Error)
+            return error.message || error.name || 'Error';
+        return String(error);
+    }
+    catch {
+        // fail-open: describing the error must not raise a second one.
+        return '[unprintable error]';
+    }
+}
+/** `push-marker write|clear <git-dir> <pid>`; returns the exit status. Never fails a push: errors only warn. */
+export function main(args, effects, warn) {
+    const [verb, dir, pidText] = args;
+    const pid = Number(pidText);
+    if ((verb !== 'write' && verb !== 'clear') || dir === undefined || dir === '' || !(pid > 1)) {
+        warn('usage: push-marker write|clear <git-dir> <pid>');
+        return 2;
+    }
+    try {
+        if (verb === 'write')
+            writeMarker(dir, pid, effects);
+        else
+            clearMarker(dir, pid, effects);
+        return 0;
+    }
+    catch (error) {
+        // fail-open: the marker is advisory; the push carries on after the warning.
+        warn(`push marker: could not ${verb} (${errorDetail(error)})`);
+        return 1;
+    }
+}

package/dist/rule-checks/registry.js

@@ -0,0 +1,163 @@
+/**
+ * The rule registry: every checkable rule a consumer's agents learned the
+ * hard way, the agent-memory notes it came from, where it came from, and what
+ * enforces it now. The consumer owns the file; kavach validates it, words
+ * refusals from it, and answers the count of rules still unenforced.
+ *
+ * A registry is JSON:
+ *
+ * ```json
+ * {
+ *   "owner": "the release manager",
+ *   "rules": [
+ *     {
+ *       "id": "H-01",
+ *       "title": "Resolve review threads only after fixes are pushed",
+ *       "notes": ["never-sync-threads-before-pushing-fixes"],
+ *       "origin": "work 12",
+ *       "enforcer": { "pr": 34, "files": ["rules/threads-after-push.ts"] }
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * `owner` (optional) is who a refusal without a pass tells the agent to ask;
+ * absent, "the repository owner". `origin` (optional) is printed after the
+ * rule's title. `enforcer` is `null` for a rule nothing checks yet. Other keys
+ * are left alone, so a consumer may keep its own bookkeeping beside these.
+ *
+ * A rule counts as enforced only when its enforcer names files that exist in
+ * the checkout, so a renamed or deleted enforcer reads as unenforced instead
+ * of being trusted from the record.
+ *
+ * CLI: `cli.js count --registry <json> [--root <dir>] [--json]` prints the
+ * count and the unenforced rules; `--json` prints the same as JSON.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { onlyKnown, option } from './args.js';
+/** Who a refusal says to ask when the registry names no one. */
+export const DEFAULT_OWNER = 'the repository owner';
+/** The environment variable the CLIs read the registry path from. */
+export const REGISTRY_ENV = 'KAVACH_RULE_REGISTRY';
+const RULE_ID = /^[A-Z]-\d{2}$/;
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const REPO_PATH = /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[^\s]+$/;
+function record(value, where) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`${where}: expected an object`);
+    }
+    return value;
+}
+function text(value, where, shape) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${where}: expected a non-empty string`);
+    }
+    if (shape !== undefined && !shape.test(value)) {
+        throw new Error(`${where}: ${JSON.stringify(value)} does not match ${shape}`);
+    }
+    return value;
+}
+function texts(value, where, shape) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`${where}: expected a non-empty list`);
+    }
+    return value.map((item, i) => text(item, `${where}[${i}]`, shape));
+}
+function enforcer(value, where) {
+    if (value === null)
+        return null;
+    const raw = record(value, where);
+    const pr = raw['pr'];
+    if (typeof pr !== 'number' || !Number.isSafeInteger(pr) || pr <= 0) {
+        throw new Error(`${where}.pr: expected a positive integer`);
+    }
+    return { pr, files: texts(raw['files'], `${where}.files`, REPO_PATH) };
+}
+/** Validate a parsed registry file; throws naming the first bad field. */
+export function parseRegistry(value) {
+    const raw = record(value, 'registry');
+    const owner = raw['owner'] === undefined ? undefined : text(raw['owner'], 'registry.owner');
+    if (!Array.isArray(raw['rules'])) {
+        throw new Error('registry.rules: expected a list');
+    }
+    const seen = new Set();
+    const rules = raw['rules'].map((item, i) => {
+        const where = `registry.rules[${i}]`;
+        const row = record(item, where);
+        const id = text(row['id'], `${where}.id`, RULE_ID);
+        if (seen.has(id))
+            throw new Error(`${where}.id: ${id} is listed twice`);
+        seen.add(id);
+        const origin = row['origin'] === undefined ? undefined : text(row['origin'], `${where}.origin`);
+        return {
+            id,
+            title: text(row['title'], `${where}.title`),
+            notes: texts(row['notes'], `${where}.notes`, SLUG),
+            ...(origin === undefined ? {} : { origin }),
+            enforcer: enforcer(row['enforcer'], `${where}.enforcer`),
+        };
+    });
+    return { ...(owner === undefined ? {} : { owner }), rules };
+}
+export function loadRegistry(path) {
+    return parseRegistry(JSON.parse(readFileSync(path).toString()));
+}
+/** Is the rule enforced in the checkout at `root`: an enforcer whose paths are all files. */
+export function isEnforced(rule, root) {
+    return (rule.enforcer !== null &&
+        rule.enforcer.files.every((file) => statSync(join(root, file), { throwIfNoEntry: false })?.isFile() === true));
+}
+export function count(registry, root) {
+    return {
+        total: registry.rules.length,
+        unenforced: registry.rules.filter((rule) => !isEnforced(rule, root)),
+    };
+}
+export function renderCount(result) {
+    const lines = [`${result.unenforced.length} of ${result.total} checkable memory rules unenforced`];
+    for (const rule of result.unenforced) {
+        lines.push(`  ${rule.id}  ${rule.title}${rule.origin === undefined ? '' : `  (${rule.origin})`}`);
+    }
+    return lines.join('\n');
+}
+/** Lines to standard output and standard error, for the CLIs. */
+export const STDIO = {
+    out: (line) => {
+        process.stdout.write(`${line}\n`);
+    },
+    err: (line) => {
+        process.stderr.write(`${line}\n`);
+    },
+};
+const USAGE = 'usage: count --registry <json> [--root <dir>] [--json]';
+/**
+ * `count`: the registry from `--registry` (else `KAVACH_RULE_REGISTRY`), the
+ * checkout from `--root` (else `cwd`), both relative to `cwd`. Exit 2 on a
+ * usage error or a registry that does not load.
+ */
+export function main(argv, io, cwd = process.cwd(), env = process.env) {
+    let result;
+    try {
+        onlyKnown(argv, ['--registry', '--root'], ['--json']);
+        const path = option(argv, '--registry') ?? env[REGISTRY_ENV];
+        if (path === undefined || path === '')
+            throw new Error(`no registry: pass --registry or set ${REGISTRY_ENV}`);
+        result = count(loadRegistry(resolve(cwd, path)), resolve(cwd, option(argv, '--root') ?? '.'));
+    }
+    catch (error) {
+        io.err(`count: ${error instanceof Error ? error.message : String(error)}`);
+        io.err(USAGE);
+        return 2;
+    }
+    if (argv.includes('--json')) {
+        io.out(JSON.stringify({
+            total: result.total,
+            unenforced: result.unenforced.map((rule) => rule.id),
+        }));
+    }
+    else {
+        io.out(renderCount(result));
+    }
+    return 0;
+}