@veda-hq/dvara 0.0.0-stage → 0.5.4

package/dist/supervisor.js

@@ -0,0 +1,371 @@
+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 hook supervisor: runs a git hook under bash, forwards the terminal's
+// signals to it, and writes one history row per run. It never changes the
+// hook's verdict except to report a signalled run as cancelled; every failure
+// of its own (telemetry, watchdog, quiet output) is fail-open.
+import { execFileSync, spawn, spawnSync, } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { cpus, totalmem } from "node:os";
+import { relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { hookKind, invocationContext, perfLevelNames } from "./context.js";
+import { isQuiet, successLine, successNotices } from "./quiet.js";
+import { parseRecords, parseStages, treeUsage } from "./records.js";
+/** Exit code per signal, shared by the pre-launch path and the exit handler. */
+export const SIGNAL_EXIT_CODES = {
+    SIGINT: 130,
+    SIGTERM: 143,
+    SIGHUP: 129,
+    SIGQUIT: 131,
+};
+const FORWARDED = Object.keys(SIGNAL_EXIT_CODES);
+// A hung `ps` must not hang the supervisor that exists to report hangs.
+const psTable = () => execFileSync("ps", ["-axo", "pid=,ppid=,rss="], {
+    encoding: "utf8",
+    timeout: 10_000,
+});
+const readOrNull = (path) => {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+};
+const importWatchdog = async (path) => (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
+/** What a run is judged against, read once before the hook starts. */
+export const judgedAgainst = (root, env, baseRefs) => {
+    const git = (args) => {
+        try {
+            // A fact git cannot give is null; its complaint is not the hook's output.
+            return execFileSync("git", args, {
+                cwd: root,
+                env,
+                stdio: "pipe",
+            }).toString();
+        }
+        catch {
+            return null;
+        }
+    };
+    const revision = git(["rev-parse", "HEAD"]);
+    // A detached HEAD abbreviates to the literal "HEAD", which is no branch.
+    const branchName = git(["rev-parse", "--abbrev-ref", "HEAD"])?.trim();
+    const branch = !branchName || branchName === "HEAD" ? null : branchName;
+    const diff = revision === null ? null : git(["diff", "--binary", "HEAD"]);
+    // Diagnostic identity only: it never authorizes reusing a result.
+    const fingerprint = revision === null || diff === null
+        ? null
+        : createHash("sha256").update(revision).update(diff).digest("hex");
+    // The merge-base is taken with the captured commit, not the ref, so a peer's
+    // fetch between the two calls cannot pair two versions of the base. Exit 1
+    // is "no common ancestor", a real state; any other failure is unknown.
+    const mergeBaseOf = (commit) => {
+        const result = spawnSync("git", ["merge-base", commit, "HEAD"], {
+            cwd: root,
+            env,
+            encoding: "utf8",
+        });
+        if (result.status === 0)
+            return result.stdout.trim() || null;
+        return result.status === 1 ? "none" : null;
+    };
+    let base = null;
+    for (const ref of baseRefs) {
+        const commit = git([
+            "rev-parse",
+            "--verify",
+            "--quiet",
+            `${ref}^{commit}`,
+        ])?.trim();
+        if (commit) {
+            base = { ref, commit, mergeBase: mergeBaseOf(commit) };
+            break;
+        }
+    }
+    const tree = git(["rev-parse", "HEAD^{tree}"])?.trim() || null;
+    const untracked = git(["ls-files", "--others", "--exclude-standard"]);
+    const clean = diff === null || untracked === null
+        ? null
+        : diff === "" && untracked === "";
+    return { branch, fingerprint, base, tree, clean };
+};
+/**
+ * Run `hook` under supervision and resolve with the exit code git must see.
+ * One row per run goes to `<root>/<historyDir>/history.jsonl`.
+ */
+export const supervise = async ([hook, ...args], options) => {
+    if (hook === undefined)
+        throw new Error("supervise: no hook given");
+    const { root, config, env = process.env, signals = process, exit = (code) => process.exit(code), platform = process.platform, sampleIntervalMs = 5000, drainLimitMs = 2000, ppid = process.ppid, loadWatchdog = importWatchdog, stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), processTable = psTable, } = options;
+    const dir = resolve(root, config.historyDir);
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        /* telemetry cannot block the hook */
+    }
+    const id = randomUUID();
+    const events = resolve(dir, `${id}.stages`);
+    const records = resolve(dir, `${id}.records`);
+    // The seconds the hook spent selecting its runtime before it started this
+    // supervisor; unset, junk and negative count as none.
+    const bootstrapSeconds = Number(env.DVARA_BOOTSTRAP_SECONDS);
+    const bootstrapMs = Math.max(0, Number.isFinite(bootstrapSeconds) ? bootstrapSeconds : 0) *
+        1000;
+    const started = Date.now() - bootstrapMs;
+    const hookName = hook.split("/").at(-1) ?? hook;
+    const kind = hookKind(hookName, args, env);
+    const invocation = invocationContext(kind, env, ppid);
+    // The handlers go in BEFORE the hook is spawned and before the first await.
+    // The child is detached, in its own process group, so it does not receive
+    // the terminal's signals: forwarding them is the only thing that stops it.
+    // Registered after the spawn, a signal in between kills this supervisor by
+    // default instead, writing no row and orphaning the hook. Under load that
+    // window opens wide.
+    let child;
+    let watchdog;
+    let signal = null;
+    const listeners = [];
+    for (const name of FORWARDED) {
+        const listener = () => {
+            signal = name;
+            // A person cancelled the run: the watchdog must neither act on nor relabel it.
+            watchdog?.disarm();
+            if (child?.pid === undefined) {
+                // Nothing has run, so there is no group to signal and no row to write.
+                exit(SIGNAL_EXIT_CODES[name] ?? 1);
+                return;
+            }
+            try {
+                process.kill(-child.pid, name);
+            }
+            catch (error) {
+                if (error.code !== "ESRCH") {
+                    stderr(`Process-group signal forwarding failed: ${error.code}; forwarding to the hook directly.\n`);
+                    child.kill(name);
+                }
+            }
+        };
+        listeners.push([name, listener]);
+        signals.on(name, listener);
+    }
+    // A settled run answers no more signals: each run removes only its own.
+    const release = () => {
+        for (const [name, listener] of listeners)
+            signals.off(name, listener);
+    };
+    const { branch, fingerprint, base, tree, clean } = judgedAgainst(root, env, config.baseRefs);
+    let watchdogModule = null;
+    if (config.watchdog) {
+        try {
+            watchdogModule = await loadWatchdog(resolve(root, config.watchdog));
+        }
+        catch {
+            /* the watchdog is a safety net, never a prerequisite for running the hook */
+        }
+    }
+    // Signalled while the watchdog loaded: `exit` has ended the CLI already.
+    if (signal) {
+        release();
+        return SIGNAL_EXIT_CODES[signal] ?? 1;
+    }
+    const quiet = isQuiet(kind, config.quietHooks, env);
+    const held = [];
+    const spawned = spawn("bash", [hook, ...args], {
+        cwd: root,
+        // stdin stays inherited: pre-push reads its refs from it.
+        stdio: quiet ? ["inherit", "pipe", "pipe"] : "inherit",
+        detached: true,
+        env: {
+            ...env,
+            DVARA_MEASURED_HOOK: hookName,
+            DVARA_STAGE_FILE: events,
+            DVARA_RECORD_FILE: records,
+        },
+    });
+    child = spawned;
+    if (quiet)
+        for (const stream of [spawned.stdout, spawned.stderr])
+            stream?.on("data", (chunk) => held.push(chunk));
+    if (watchdogModule && spawned.pid !== undefined) {
+        try {
+            watchdog = watchdogModule.createWatchdog({
+                rootPid: spawned.pid,
+                stageFile: events,
+                hangsDir: resolve(dir, "hangs"),
+                runId: id,
+                config: watchdogModule.resolveWatchdogConfig(env, platform, perfLevelNames(platform)),
+            });
+        }
+        catch {
+            watchdog = undefined;
+        }
+    }
+    let peakTreeRssKiB = 0;
+    let peakProcesses = 0;
+    let resourceSamples = 0;
+    const sample = () => {
+        try {
+            const table = processTable();
+            const usage = treeUsage(table, spawned.pid ?? -1);
+            peakTreeRssKiB = Math.max(peakTreeRssKiB, usage.rssKiB);
+            peakProcesses = Math.max(peakProcesses, usage.processes);
+            resourceSamples++;
+        }
+        catch {
+            /* an unavailable measurement is not a verdict */
+        }
+    };
+    const timer = setInterval(sample, sampleIntervalMs);
+    /** A quiet hook's held output: all of it when the run did not pass, else its warnings and one line. */
+    const report = (code, durationMs) => {
+        const output = Buffer.concat(held);
+        const log = resolve(dir, `${kind}.log`);
+        try {
+            writeFileSync(log, output);
+        }
+        catch {
+            /* the log is a convenience; the verdict is printed regardless */
+        }
+        if (code !== 0) {
+            stderr(output);
+            return;
+        }
+        const lines = [
+            ...successNotices(output.toString("utf8")),
+            successLine(kind, durationMs, relative(root, log)),
+        ];
+        stdout(`${lines.join("\n")}\n`);
+    };
+    /**
+     * Wait for a quiet hook's pipes to empty after it exits. A process the hook
+     * left running can hold them open forever, so the wait is bounded and the
+     * pipes are then closed.
+     */
+    const drained = async () => {
+        if (!quiet)
+            return;
+        const streams = [spawned.stdout, spawned.stderr].filter((s) => s !== null);
+        const closed = Promise.all(streams.map((stream) => stream.closed
+            ? null
+            : new Promise((done) => stream.once("close", done))));
+        const limit = new Promise((done) => setTimeout(() => done("limit"), drainLimitMs).unref());
+        const outcome = await Promise.race([closed, limit]);
+        if (outcome === "limit")
+            held.push(Buffer.from(`[output truncated: a process the hook started still held its output open ${drainLimitMs / 1000} s after it exited]\n`));
+        for (const stream of streams)
+            stream.destroy();
+    };
+    const finish = (exitCode, error) => {
+        let code = exitCode;
+        clearInterval(timer);
+        watchdog?.stop();
+        const watchdogSummary = watchdog?.summary() ?? {
+            mode: "unavailable",
+        };
+        // An enforced stop decides the outcome: the hook exited because the
+        // watchdog stopped it, so its own status is not the story.
+        const imposed = watchdogModule?.exitDisposition(watchdogSummary) ?? null;
+        if (imposed)
+            code = imposed.code;
+        const ended = Date.now();
+        if (quiet)
+            report(code, ended - started);
+        const marks = parseStages(readOrNull(events), bootstrapMs);
+        const { pushed, declared, proof, proofDiagnostics } = parseRecords(readOrNull(records));
+        const verdict = (last) => imposed
+            ? imposed.status
+            : signal
+                ? "cancelled"
+                : code === 0
+                    ? "success"
+                    : last
+                        ? "failed"
+                        : "failure";
+        // A stage's input is what it declared, else the whole tree when that tree
+        // is exactly a commit: coarse, but recomputable.
+        const treeInput = clean && tree ? { kind: "tree", digest: tree } : null;
+        const stages = marks.map((stage, index) => ({
+            ...stage,
+            input: declared.get(stage.name) ?? treeInput,
+            durationMs: Math.max(0, (marks[index + 1]?.startMs ?? ended - started) - stage.startMs),
+            status: index === marks.length - 1 ? verdict(true) : "completed",
+        }));
+        try {
+            appendFileSync(resolve(dir, "history.jsonl"), `${JSON.stringify({
+                schema: 1,
+                id,
+                kind,
+                invocation,
+                startedAt: new Date(started).toISOString(),
+                durationMs: ended - started,
+                exitCode: code,
+                signal,
+                error,
+                status: verdict(false),
+                branch,
+                fingerprint,
+                fingerprintPurpose: "diagnostic-head-and-tracked-diff-only",
+                base,
+                tree,
+                clean,
+                pushed,
+                stages,
+                proof,
+                proofDiagnostics,
+                node: process.version,
+                platform: process.platform,
+                arch: process.arch,
+                cpus: cpus().length,
+                totalMemoryBytes: totalmem(),
+                sampledPeakTreeRssKiB: peakTreeRssKiB || null,
+                peakProcesses: peakProcesses || null,
+                resourceSamples,
+                sampleIntervalMs,
+                watchdog: watchdogSummary,
+            })}\n`);
+            rmSync(events, { force: true });
+            rmSync(records, { force: true });
+        }
+        catch (failure) {
+            stderr(`History unavailable: ${failure.message}\n`);
+        }
+        return code;
+    };
+    // One row per run, whichever of `error` and `exit` arrives first.
+    let outcome;
+    return new Promise((done, fail) => {
+        const settle = (code, error) => {
+            try {
+                outcome ??= finish(code, error);
+                done(outcome);
+            }
+            catch (failure) {
+                fail(failure);
+            }
+            finally {
+                release();
+            }
+        };
+        spawned.on("error", (error) => settle(127, error.message));
+        spawned.on("exit", (code, childSignal) => {
+            // The watchdog's own stop is not a cancellation; `finish` reports its verdict instead.
+            if (!watchdog?.enforced())
+                signal ??= childSignal;
+            // A signal outranks the code the hook chose: a hook that traps its
+            // signal and exits 0 was still cancelled, and reporting 0 would let a
+            // push through a gate its operator had just interrupted.
+            const verdict = (signal ? SIGNAL_EXIT_CODES[signal] : undefined) ?? code ?? 1;
+            void drained().then(() => settle(verdict));
+        });
+    });
+};

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@veda-hq/dvara",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.4",
+  "description": "Git hooks for repositories coding agents work in: runs each hook under a supervisor that times its stages, forwards signals and keeps one history row per run, with quiet output on success and a keep-going mode for preflights.",
+  "keywords": [
+    "git hooks",
+    "pre-push",
+    "pre-commit",
+    "coding agents",
+    "telemetry"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24.15"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/veda-hq/veda.git",
+    "directory": "packages/dvara"
+  },
+  "homepage": "https://github.com/veda-hq/veda/tree/main/packages/dvara#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "dvara": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/supervisor.js",
+    "./config": "./dist/config.js",
+    "./shell/stages.sh": "./shell/stages.sh",
+    "./shell/keep-going.sh": "./shell/keep-going.sh",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "shell/*.sh"
+  ],
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "typescript": "7.0.2"
+  },
+  "dependencies": {
+    "mdast-util-from-markdown": "2.0.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test --experimental-test-coverage --test-coverage-lines=95 --test-coverage-functions=95 --test-coverage-branches=90 --test-coverage-exclude='src/**/*.test.ts' --test-coverage-include='src/**/*.ts' 'src/**/*.test.ts'",
+    "smoke": "node dist/cli.js --version && node dist/cli.js shell stages",
+    "check": "pnpm typecheck && pnpm test && pnpm build && pnpm smoke"
+  }
 }

package/shell/keep-going.sh

@@ -0,0 +1,86 @@
+# shellcheck shell=bash
+# Keep-going mode, for a preflight: the push hook itself, run ahead of the
+# push, so the preflight and the push cannot drift apart. Only what a refusal
+# does differs. In a push, a stage's `exit 1` ends the hook at its first
+# failure. Here the same `exit 1` is recorded against the stage that raised it
+# (DVARA_CURRENT_STAGE, stages.sh) and the hook carries on, so one run lists
+# every failure. dvara_keep_going_report ends the run.
+#
+# Source it only in keep-going mode, after the runtimes the hook needs are in
+# place, so a missing runtime still ends the run at once.
+#
+# How: a function named `exit` runs in place of the builtin. It takes over one
+# case only, status 1 in the hook's own shell. In a subshell or a command
+# substitution (BASH_SUBSHELL > 0) `exit` must still end that subshell, and
+# every other status (0, a trap's 130 or 143, a probe's 124) is a real end, so
+# those go to the builtin. Whatever `set -e` aborts on never calls `exit` and
+# still ends the run. A stage written as a function keeps this behaviour: the
+# function runs in the hook's shell, and execution continues after the `exit`.
+#
+# Plain strings, not arrays: macOS runs hooks under /bin/bash 3.2, where an
+# empty array is an unbound variable under `set -u`.
+
+DVARA_KEEP_GOING_FAILED=""
+DVARA_KEEP_GOING_HELD=""
+DVARA_KEEP_GOING_SKIPPED=""
+
+# shellcheck disable=SC2034 # DVARA_UNREPORTED_REFUSAL is read by stages.sh
+exit() {
+  local status="${1:-$?}"
+  if [ "$status" = 1 ] && [ "${BASH_SUBSHELL:-0}" -eq 0 ]; then
+    local stage="${DVARA_CURRENT_STAGE:-unknown}"
+    DVARA_KEEP_GOING_FAILED="${DVARA_KEEP_GOING_FAILED}${stage}"$'\n'
+    DVARA_UNREPORTED_REFUSAL=1
+    echo "✗ ${DVARA_KEEP_GOING_NAME:-preflight}: ${stage} failed; carrying on to the next check"
+    return 0
+  fi
+  builtin exit "$status"
+}
+
+# A check not run because an earlier result makes its verdict meaningless.
+dvara_keep_going_held() {
+  DVARA_KEEP_GOING_HELD="${DVARA_KEEP_GOING_HELD}$1: not run: $2"$'\n'
+  echo "→ $1: not run: $2"
+}
+
+# A check this run was asked not to run: not a failure, and not a pass.
+dvara_keep_going_skipped() {
+  DVARA_KEEP_GOING_SKIPPED="${DVARA_KEEP_GOING_SKIPPED}$1: skipped: $2"$'\n'
+  echo "⏭  $1: skipped: $2"
+}
+
+# The end of the run: every check skipped, held and failed, and the verdict.
+# Fails when any check failed or was held; passes, saying so, when the only
+# gaps are skips.
+dvara_keep_going_report() {
+  local line failed=0
+  echo ""
+  echo "━━━ ${DVARA_KEEP_GOING_TITLE:-Preflight} summary ━━━"
+  while IFS= read -r line; do
+    if [ -n "$line" ]; then echo "  ⏭  ${line}"; fi
+  done <<< "$DVARA_KEEP_GOING_SKIPPED"
+  while IFS= read -r line; do
+    if [ -n "$line" ]; then echo "  ⏸  ${line}"; fi
+  done <<< "$DVARA_KEEP_GOING_HELD"
+  while IFS= read -r line; do
+    if [ -n "$line" ]; then
+      echo "  ❌ ${line}"
+      failed=$((failed + 1))
+    fi
+  done <<< "$DVARA_KEEP_GOING_FAILED"
+  if [ "$failed" -gt 0 ]; then
+    echo "  ${failed} check(s) failed. Fix them all, commit, and run the preflight again."
+    echo "  Nothing was pushed."
+    builtin exit 1
+  fi
+  if [ -n "$DVARA_KEEP_GOING_HELD" ]; then
+    echo "  No check failed, but the checks above did not run. Nothing was pushed."
+    builtin exit 1
+  fi
+  if [ -n "$DVARA_KEEP_GOING_SKIPPED" ]; then
+    echo "  ✅ Every check that ran passed; the push runs the skipped ones. Nothing was pushed."
+    builtin exit 0
+  fi
+  echo "  ✅ Every check passed. Nothing was pushed and no pull request was opened."
+  builtin exit 0
+}

package/shell/stages.sh

@@ -0,0 +1,52 @@
+# shellcheck shell=bash
+# dvara's hook helpers, sourced by a hook that runs under `dvara run`.
+# Builtins only: one-second resolution, no subprocesses, and a failed write
+# never fails the hook. Outside the supervisor the files are unset and every
+# helper is a no-op, so the hook runs the same either way.
+
+# Mark the start of a stage. DVARA_CURRENT_STAGE is the stage a refusal is
+# recorded against in keep-going mode (keep-going.sh).
+# shellcheck disable=SC2034 # read by keep-going.sh
+dvara_stage() {
+  DVARA_CURRENT_STAGE="$1"
+  if [ -n "${DVARA_STAGE_FILE:-}" ]; then
+    printf '%s\t%s\n' "$SECONDS" "$1" >> "$DVARA_STAGE_FILE" || true
+  fi
+}
+
+# A fact for the run's history row that only the hook knows: its fields,
+# tab-separated, one record per call (records.ts lists the kinds).
+dvara_record() {
+  if [ -n "${DVARA_RECORD_FILE:-}" ]; then
+    local IFS=$'\t'
+    printf '%s\n' "$*" >> "$DVARA_RECORD_FILE" || true
+  fi
+}
+
+# Record the commits a push updates, from the ref lines git passes pre-push
+# on stdin ("<local_ref> <local_sha> <remote_ref> <remote_sha>"): each line's
+# two commit ids, never its ref names. An empty argument means a manual run.
+dvara_record_refs() {
+  local _local_ref local_sha _remote_ref remote_sha
+  if [ -z "${1:-}" ]; then
+    dvara_record refs-source none
+    return 0
+  fi
+  dvara_record refs-source stdin
+  while read -r _local_ref local_sha _remote_ref remote_sha; do
+    dvara_record ref "$local_sha" "$remote_sha"
+  done <<< "$1"
+}
+
+# Guards a "✅" line: false once after keep-going mode carried on past a
+# refusal, so a failed check is never reported as passed. A run that stops at
+# its first failure never carries on, so there it is always true.
+dvara_passed() {
+  if [ "${DVARA_UNREPORTED_REFUSAL:-0}" = 1 ]; then
+    DVARA_UNREPORTED_REFUSAL=0
+    return 1
+  fi
+  return 0
+}
+
+dvara_stage startup