@reticlehq/server 2.14.0 → 3.2.0

package/dist/hooks/hook-commands.js

@@ -0,0 +1,184 @@
+/**
+ * The config surface: `.reticle/hooks.json` says what to run, this runs it.
+ *
+ * A subscriber on the bus like any other, which is the point — it has no privileges the in-process
+ * API does not have, and if this file were deleted the bus would carry on. That is what keeps the
+ * two surfaces honest about being adapters rather than two half-implementations of one idea.
+ *
+ * ── TRUST ───────────────────────────────────────────────────────────────────────────────────────
+ * The command is read from a file inside the user's own repository and run with a shell, which is
+ * exactly the trust level `package.json` scripts and git hooks already have there: cloning a repo
+ * runs nothing, and a command runs only when the event it is attached to actually happens.
+ *
+ * The payload NEVER touches the command line. It is written to the child's stdin as JSON, so a
+ * defect's own text — a page title, an assertion message, anything the app under test produced —
+ * cannot become part of a command. That is the one place a plausible injection could enter, and it
+ * is closed by construction rather than by escaping, because escaping is a thing you get wrong once.
+ *
+ * ── NEVER IN THE WAY ────────────────────────────────────────────────────────────────────────────
+ * Detached from the caller entirely: nothing awaits the child, a non-zero exit is reported and not
+ * raised, and a child that hangs is killed on a timeout rather than held. A user whose script is
+ * broken gets a log line; their verdicts keep working.
+ */
+import { spawn } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { HOOK_EVENT_NAMES, HookConfigSchema } from '@reticlehq/core/hooks';
+import { ReticleDir } from '@reticlehq/core';
+import { log } from '../log.js';
+import { onHook } from './hook-bus.js';
+import { setHookProjectId } from './hook-emit.js';
+/**
+ * How long a hook command may run before it is killed.
+ *
+ * Generous, because a hook that posts to an API over a slow connection is a legitimate use and the
+ * cost of killing it early is a silently missing notification. Bounded, because a child that never
+ * exits would otherwise accumulate one process per verdict for the life of the daemon.
+ */
+const HOOK_TIMEOUT_MS = 30_000;
+/**
+ * How many hook processes may be in flight at once.
+ *
+ * A drive can produce verdicts faster than a script can finish, and without a cap a slow hook turns
+ * a busy session into hundreds of processes — which is not a hook misbehaving, it is us handing a
+ * user a foot-gun and calling it configuration. Over the cap, the event is DROPPED and said so:
+ * queueing would mean delivering a notification about a bug long after the session that found it,
+ * and a late notification reads as a current one.
+ */
+const MAX_IN_FLIGHT = 8;
+let inFlight = 0;
+const reported = new Set();
+function reportOnce(key, message) {
+    if (reported.has(key))
+        return;
+    reported.add(key);
+    log(`hook: ${message}`);
+}
+/** Cached config plus the mtime it was read at, so an edit takes effect without a daemon restart. */
+let cached;
+/**
+ * Read `.reticle/hooks.json`, or nothing.
+ *
+ * Re-read when the file's mtime moves. A `stat` per event is nothing next to spawning a process,
+ * and the alternative — read once at startup — means a user editing their hooks has to know to
+ * restart a daemon they never started by hand.
+ */
+export function readHookConfig(reticleRoot) {
+    const path = join(reticleRoot, ReticleDir.HOOKS_FILE);
+    let mtime;
+    try {
+        mtime = statSync(path).mtimeMs;
+    }
+    catch {
+        cached = undefined;
+        return {};
+    }
+    if (cached !== undefined && cached.at === mtime)
+        return cached.config;
+    try {
+        const parsed = HookConfigSchema.safeParse(JSON.parse(readFileSync(path, 'utf8')));
+        if (!parsed.success) {
+            reportOnce(`config:${String(mtime)}`, `${ReticleDir.HOOKS_FILE} is not a map of event→command`);
+            cached = { at: mtime, config: {} };
+            return {};
+        }
+        // An unknown event name is the likeliest mistake in this file and the one that is otherwise
+        // invisible — the hook simply never runs, which looks identical to Reticle not finding bugs.
+        const known = {};
+        for (const [event, command] of Object.entries(parsed.data)) {
+            if (HOOK_EVENT_NAMES.includes(event)) {
+                known[event] = command;
+                continue;
+            }
+            reportOnce(`unknown:${event}`, `${ReticleDir.HOOKS_FILE} names "${event}", which is not a Reticle event. Known events: ${HOOK_EVENT_NAMES.join(', ')}`);
+        }
+        cached = { at: mtime, config: known };
+        return known;
+    }
+    catch (error) {
+        reportOnce(`parse:${String(mtime)}`, `${ReticleDir.HOOKS_FILE} could not be read: ${error instanceof Error ? error.message : String(error)}`);
+        cached = { at: mtime, config: {} };
+        return {};
+    }
+}
+/** Run one command with the payload on stdin. Returns immediately; nothing here is awaited. */
+export function runHookCommand(command, payload, cwd) {
+    if (inFlight >= MAX_IN_FLIGHT) {
+        reportOnce(`saturated:${command}`, `dropping ${payload.event}: ${String(MAX_IN_FLIGHT)} hook commands already running. A hook that cannot keep up with a drive should hand off to something that queues.`);
+        return;
+    }
+    inFlight += 1;
+    let child;
+    try {
+        child = spawn(command, {
+            cwd,
+            shell: true,
+            // The payload goes in on stdin; the child's own output is inherited so a user's `echo` lands
+            // where they expect rather than vanishing into a daemon nobody is watching.
+            stdio: ['pipe', 'inherit', 'inherit'],
+            timeout: HOOK_TIMEOUT_MS,
+        });
+    }
+    catch (error) {
+        inFlight -= 1;
+        reportOnce(`spawn:${command}`, `could not start "${command}": ${String(error)}`);
+        return;
+    }
+    const done = () => {
+        inFlight = Math.max(0, inFlight - 1);
+    };
+    child.on('error', (error) => {
+        done();
+        reportOnce(`run:${command}`, `"${command}" failed to run: ${error.message}`);
+    });
+    child.on('close', (code) => {
+        done();
+        if (null !== code && 0 !== code) {
+            reportOnce(`exit:${command}:${String(code)}`, `"${command}" exited ${String(code)}`);
+        }
+    });
+    // A child that closed stdin early (or never read it) must not take the daemon down with EPIPE.
+    child.stdin?.on('error', () => undefined);
+    try {
+        child.stdin?.end(`${JSON.stringify(payload)}\n`);
+    }
+    catch {
+        /* the child is already gone; its exit is reported above */
+    }
+}
+/**
+ * Attach the config surface to the bus.
+ *
+ * Subscribes once, for every event, and decides per payload — rather than reading the config now
+ * and subscribing to the events it names. Those differ the moment somebody edits the file: the
+ * eager version would keep running yesterday's hooks and ignore today's.
+ */
+export function installCommandHooks(reticleRoot) {
+    return onHook(undefined, (payload) => {
+        const command = readHookConfig(reticleRoot)[payload.event];
+        if (command === undefined || 0 === command.trim().length)
+            return;
+        runHookCommand(command, payload, reticleRoot);
+    });
+}
+/**
+ * Wire BOTH halves of hooks for one entry point: the config surface, and the project id payloads
+ * carry.
+ *
+ * Exists because `start()` and `startDaemon()` each wire their own world, and a line added to one
+ * of them is not added to the other. `installCommandHooks` was in `startDaemon` alone, so
+ * `.reticle/hooks.json` did nothing under `reticle drive`, `reticle verify` and `reticle demo` —
+ * three commands that run a whole verification and emit every event a hook subscribes to. The
+ * in-process surface (`onHook`) worked on both, so the feature looked wired; only the
+ * file-configured half was dead, and it is the half a user who has not written code can reach.
+ *
+ * `initImpact` had already been fixed for exactly this, one line at a time, and the comment left
+ * beside it in `startDaemon` says so. One function is what stops the next one.
+ *
+ * Costs nothing when unused: with no `.reticle/hooks.json` the listener reads an absent file, gets
+ * an empty map and returns.
+ */
+export function wireHooks(reticleRoot, projectId) {
+    setHookProjectId(projectId);
+    return installCommandHooks(reticleRoot);
+}

package/dist/hooks/hook-emit.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Turning what just happened inside the daemon into what Reticle says happened.
+ *
+ * A separate file from the dispatcher on purpose. The mapping from an internal object to a public
+ * payload is the part that has to stay stable while the internals move, and keeping it beside the
+ * call sites would make every change to a result shape look like a change to the contract. Here,
+ * a field disappearing from a result is a visible edit to a mapping rather than a silent one.
+ *
+ * Every function is fire-and-forget and returns `void`: these are called from the verdict path, and
+ * the bus's promise — that a hook cannot break or slow a verification — is only true if the code
+ * feeding it makes the same promise.
+ */
+import { HookEvent } from '@reticlehq/core/hooks';
+/** Told once at daemon start; there is no per-call plumbing for something that does not change. */
+export declare function setHookProjectId(projectId: string | undefined): void;
+/** A verdict landed, in the protocol's own four-valued words. */
+export declare function emitVerdictHook(toolName: string, result: Record<string, unknown>, verified: string, sessionId?: string): void;
+/** One defect. The caller has already decided this is a defect and whether it is a repeat. */
+export declare function emitBugFoundHook(toolName: string, bug: {
+    kind: string;
+    source?: string | undefined;
+}, extra: {
+    repeat: boolean;
+    fingerprint?: string | undefined;
+    route?: string | undefined;
+    sessionId?: string | undefined;
+}): void;
+/** A browser session attached or detached. */
+export declare function emitSessionHook(kind: typeof HookEvent.SESSION_STARTED | typeof HookEvent.SESSION_ENDED, session: {
+    id: string;
+    url?: string | undefined;
+    runtime?: string | undefined;
+}): void;
+/**
+ * A sync cycle finished, including the ones that moved nothing.
+ *
+ * `runsPushed: 0, ok: true` is the common and useful case: from outside, "nothing changed" and
+ * "sync has been broken since Tuesday" are indistinguishable without it.
+ */
+export declare function emitSyncHook(report: {
+    runsPushed: number;
+    ok: boolean;
+    error?: string | undefined;
+}): void;

package/dist/hooks/hook-emit.js

@@ -0,0 +1,85 @@
+/**
+ * Turning what just happened inside the daemon into what Reticle says happened.
+ *
+ * A separate file from the dispatcher on purpose. The mapping from an internal object to a public
+ * payload is the part that has to stay stable while the internals move, and keeping it beside the
+ * call sites would make every change to a result shape look like a change to the contract. Here,
+ * a field disappearing from a result is a visible edit to a mapping rather than a silent one.
+ *
+ * Every function is fire-and-forget and returns `void`: these are called from the verdict path, and
+ * the bus's promise — that a hook cannot break or slow a verification — is only true if the code
+ * feeding it makes the same promise.
+ */
+import { HookEvent } from '@reticlehq/core/hooks';
+import { emitHook } from './hook-bus.js';
+const str = (value) => 'string' === typeof value && value.length > 0 ? value : undefined;
+/** Read once per emit so a payload's `at` is the moment it happened, not the moment it was written. */
+const nowIso = () => new Date().toISOString();
+/**
+ * The project this happened in.
+ *
+ * Read from the daemon's own resolved project rather than passed down through every call site.
+ * Absent is normal and correct: a session driven outside a wired project has no project id, and
+ * inventing one would make a consumer's grouping wrong in a way they could not detect.
+ */
+let currentProjectId;
+/** Told once at daemon start; there is no per-call plumbing for something that does not change. */
+export function setHookProjectId(projectId) {
+    currentProjectId = projectId;
+}
+const withProject = (payload) => currentProjectId === undefined ? payload : { ...payload, projectId: currentProjectId };
+/** A verdict landed, in the protocol's own four-valued words. */
+export function emitVerdictHook(toolName, result, verified, sessionId) {
+    const facts = result;
+    // The RESOLVED session wins over anything the result happens to echo. The dispatcher knows which
+    // session it actually drove; a result's own field is whatever that tool chose to include.
+    const session = sessionId ?? str(facts.sessionId);
+    emitHook(withProject({
+        event: HookEvent.VERDICT,
+        at: nowIso(),
+        tool: toolName,
+        verified,
+        ...(str(facts.because) === undefined ? {} : { because: str(facts.because) }),
+        ...(session === undefined ? {} : { sessionId: session }),
+        ...(str(facts.url) === undefined ? {} : { url: str(facts.url) }),
+    }));
+}
+/** One defect. The caller has already decided this is a defect and whether it is a repeat. */
+export function emitBugFoundHook(toolName, bug, extra) {
+    emitHook(withProject({
+        event: HookEvent.BUG_FOUND,
+        at: nowIso(),
+        kind: bug.kind,
+        repeat: extra.repeat,
+        tool: toolName,
+        ...(bug.source === undefined ? {} : { source: bug.source }),
+        ...(extra.fingerprint === undefined ? {} : { fingerprint: extra.fingerprint }),
+        ...(extra.route === undefined ? {} : { route: extra.route }),
+        ...(extra.sessionId === undefined ? {} : { sessionId: extra.sessionId }),
+    }));
+}
+/** A browser session attached or detached. */
+export function emitSessionHook(kind, session) {
+    emitHook(withProject({
+        event: kind,
+        at: nowIso(),
+        sessionId: session.id,
+        ...(session.url === undefined ? {} : { url: session.url }),
+        ...(session.runtime === undefined ? {} : { runtime: session.runtime }),
+    }));
+}
+/**
+ * A sync cycle finished, including the ones that moved nothing.
+ *
+ * `runsPushed: 0, ok: true` is the common and useful case: from outside, "nothing changed" and
+ * "sync has been broken since Tuesday" are indistinguishable without it.
+ */
+export function emitSyncHook(report) {
+    emitHook(withProject({
+        event: HookEvent.SYNC_COMPLETED,
+        at: nowIso(),
+        runsPushed: report.runsPushed,
+        ok: report.ok,
+        ...(report.error === undefined ? {} : { error: report.error }),
+    }));
+}

package/dist/import-graph.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Walk this package's own import graph.
+ *
+ * Used by the boundary guards. Both of them ask the same question in different words: "starting from
+ * this entry file, which modules can actually be reached?" — and both need the real graph rather than
+ * a grep, because the reach that matters is the transitive one. Nobody writes a forbidden import in
+ * `index.ts`; they write it four modules down, in something `index.ts` happens to pull in.
+ *
+ * Deliberately simple. It reads text and matches import specifiers rather than parsing TypeScript,
+ * because a guard nobody can read is a guard nobody maintains. That means it sees a specifier inside
+ * a string literal or a comment too. For a guard that is the safe direction to be wrong in: it can
+ * report a crossing that is not real (someone looks, and says so), never miss one that is.
+ */
+/**
+ * Turn an import specifier into a path relative to the source root.
+ *
+ * Returns undefined for bare package names like `zod` — those are somebody else's code, and this
+ * walker only cares about modules inside this package.
+ *
+ * `@/x` IS inside this package: it is the alias for this package's own `src`, resolved by tsconfig
+ * at compile time and rewritten to a relative path at build time. It has to resolve here, and the
+ * reason is not tidiness. Two callers of this function are boundary guards — one keeps the free
+ * build from reaching separately-licensed code, the other polices the library path — and both ask
+ * "where does this import land". An alias answered `undefined` reads as "somebody else's package",
+ * so every aliased import became invisible to them the moment the convention landed: the licence
+ * boundary would have kept passing while no longer checking anything. A guard that goes quiet as its
+ * subject changes underneath it is the failure this repository keeps paying for.
+ *
+ * Imports here are always written with a `.js` extension even though the file on disk is `.ts`
+ * (that is how Node resolves ES modules after they are compiled), so the extension is swapped back.
+ */
+export declare function resolveImport(fromFile: string, specifier: string): string | undefined;
+/**
+ * Every import specifier written in one file, in the order they appear.
+ *
+ * Covers static imports, type-only imports, re-exports (`export ... from`) and dynamic `import(...)`.
+ * A file that cannot be read yields nothing rather than throwing — a stale path in a list should not
+ * take the whole guard down with it.
+ */
+export declare function importsOf(sourceRoot: string, file: string): string[];
+/**
+ * Every module reachable from `entry`, breadth-first.
+ *
+ * The returned map is `module -> the module that first reached it`, so a guard can report the EDGE
+ * that broke the rule ("cli.ts imported it") rather than just the file. When a boundary breaks, the
+ * useful question is always "who pulled this in", and the answer is otherwise a manual search.
+ */
+export declare function reachableFrom(sourceRoot: string, entry: string): Map<string, string>;

package/dist/import-graph.js

@@ -0,0 +1,106 @@
+/**
+ * Walk this package's own import graph.
+ *
+ * Used by the boundary guards. Both of them ask the same question in different words: "starting from
+ * this entry file, which modules can actually be reached?" — and both need the real graph rather than
+ * a grep, because the reach that matters is the transitive one. Nobody writes a forbidden import in
+ * `index.ts`; they write it four modules down, in something `index.ts` happens to pull in.
+ *
+ * Deliberately simple. It reads text and matches import specifiers rather than parsing TypeScript,
+ * because a guard nobody can read is a guard nobody maintains. That means it sees a specifier inside
+ * a string literal or a comment too. For a guard that is the safe direction to be wrong in: it can
+ * report a crossing that is not real (someone looks, and says so), never miss one that is.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join, normalize, sep } from 'node:path';
+/**
+ * Turn an import specifier into a path relative to the source root.
+ *
+ * Returns undefined for bare package names like `zod` — those are somebody else's code, and this
+ * walker only cares about modules inside this package.
+ *
+ * `@/x` IS inside this package: it is the alias for this package's own `src`, resolved by tsconfig
+ * at compile time and rewritten to a relative path at build time. It has to resolve here, and the
+ * reason is not tidiness. Two callers of this function are boundary guards — one keeps the free
+ * build from reaching separately-licensed code, the other polices the library path — and both ask
+ * "where does this import land". An alias answered `undefined` reads as "somebody else's package",
+ * so every aliased import became invisible to them the moment the convention landed: the licence
+ * boundary would have kept passing while no longer checking anything. A guard that goes quiet as its
+ * subject changes underneath it is the failure this repository keeps paying for.
+ *
+ * Imports here are always written with a `.js` extension even though the file on disk is `.ts`
+ * (that is how Node resolves ES modules after they are compiled), so the extension is swapped back.
+ */
+export function resolveImport(fromFile, specifier) {
+    // `@/x` is already relative to the source root, which is exactly what this returns.
+    if (specifier.startsWith('@/'))
+        return specifier.slice(2).replace(/\.js$/, '.ts');
+    if (!specifier.startsWith('.'))
+        return undefined;
+    return normalize(join(dirname(fromFile), specifier))
+        .split(sep)
+        .join('/')
+        .replace(/\.js$/, '.ts');
+}
+/**
+ * Every import specifier written in one file, in the order they appear.
+ *
+ * Covers static imports, type-only imports, re-exports (`export ... from`) and dynamic `import(...)`.
+ * A file that cannot be read yields nothing rather than throwing — a stale path in a list should not
+ * take the whole guard down with it.
+ */
+export function importsOf(sourceRoot, file) {
+    let text;
+    try {
+        text = readFileSync(join(sourceRoot, file), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const specifiers = [];
+    for (const match of text.matchAll(/(?:from|import)\s*\(?\s*['"]([^'"]+)['"]/g)) {
+        const specifier = match[1];
+        if (specifier !== undefined)
+            specifiers.push(specifier);
+    }
+    return specifiers;
+}
+/**
+ * Every module reachable from `entry`, breadth-first.
+ *
+ * The returned map is `module -> the module that first reached it`, so a guard can report the EDGE
+ * that broke the rule ("cli.ts imported it") rather than just the file. When a boundary breaks, the
+ * useful question is always "who pulled this in", and the answer is otherwise a manual search.
+ */
+export function reachableFrom(sourceRoot, entry) {
+    /*
+     * The entry is normalised the same way `resolveImport` normalises everything this walker
+     * DISCOVERS, because callers build it with `join()` and on Windows that yields `features\ee\x.ts`
+     * while every other key in the map is `features/ee/x.ts`. A caller then filters the result with
+     * `startsWith('features/ee/')` and the seed — the one path it did not walk to — silently drops
+     * out. That is how `ee-boundary`, the guard that says the free build cannot reach the
+     * separately-licensed code, passed on Windows while checking nothing at all: both of its real
+     * assertions expect an EMPTY list, so a walker that finds nothing agrees with them. Only its
+     * negative control could see it, and that is the whole reason the negative control exists.
+     *
+     * Both separators, not `sep`: on a POSIX machine `sep` is `/`, so splitting on it leaves a
+     * backslash path untouched and the rule stays untestable exactly where everybody develops. The
+     * first version of this fix did that and the test written to catch it went red immediately.
+     */
+    const start = entry.split(/[\\/]/).join('/');
+    const reachedVia = new Map([[start, start]]);
+    const queue = [start];
+    while (queue.length > 0) {
+        const file = queue.shift();
+        if (file === undefined)
+            continue;
+        for (const specifier of importsOf(sourceRoot, file)) {
+            const target = resolveImport(file, specifier);
+            if (target === undefined || reachedVia.has(target))
+                continue;
+            reachedVia.set(target, file);
+            queue.push(target);
+        }
+    }
+    return reachedVia;
+}