@descryy/mcp 0.11.5 → 0.11.6

package/dist/credential-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-store.js","sourceRoot":"","sources":["../src/credential-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,4BAA4B,EAAE,MAAM,sCAAsC,CAAC;AAqBpF;;;uCAGuC;AACvC,MAAM,UAAU,4BAA4B,CAAC,OAAgC;IAC3E,OAAO,IAAI,4BAA4B,CAAC,OAAO,CAAC,CAAC;AACnD,CAAC"}

package/dist/disclosure-ledger.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tracks disclosures this connection has already seen in full. Measured: the
+ * R0/class-C sentence is ~354 chars (~88 tokens), repeated on most of a 30-call
+ * session. Only the *argument* shortens — floor/cap stay on every reply (rule 7).
+ * Per connection, not per process — a second client can't inherit the first's history. */
+export interface DisclosureLedger {
+    /** `true` the first time this key is seen on this connection, `false` after —
+     *  calling it is what marks the key as disclosed. */
+    firstSighting(key: string): boolean;
+    /** Keys disclosed in full so far. For tests and diagnostics. */
+    disclosed(): readonly string[];
+}
+export declare function createDisclosureLedger(): DisclosureLedger;
+//# sourceMappingURL=disclosure-ledger.d.ts.map

package/dist/disclosure-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disclosure-ledger.d.ts","sourceRoot":"","sources":["../src/disclosure-ledger.ts"],"names":[],"mappings":"AAAA;;;;0FAI0F;AAE1F,MAAM,WAAW,gBAAgB;IAC/B;yDACqD;IACrD,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,gEAAgE;IAChE,SAAS,IAAI,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,wBAAgB,sBAAsB,IAAI,gBAAgB,CAUzD"}

package/dist/disclosure-ledger.js

@@ -0,0 +1,18 @@
+/**
+ * Tracks disclosures this connection has already seen in full. Measured: the
+ * R0/class-C sentence is ~354 chars (~88 tokens), repeated on most of a 30-call
+ * session. Only the *argument* shortens — floor/cap stay on every reply (rule 7).
+ * Per connection, not per process — a second client can't inherit the first's history. */
+export function createDisclosureLedger() {
+    const seen = new Set();
+    return {
+        firstSighting(key) {
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        },
+        disclosed: () => [...seen],
+    };
+}
+//# sourceMappingURL=disclosure-ledger.js.map

package/dist/disclosure-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disclosure-ledger.js","sourceRoot":"","sources":["../src/disclosure-ledger.ts"],"names":[],"mappings":"AAAA;;;;0FAI0F;AAU1F,MAAM,UAAU,sBAAsB;IACpC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO;QACL,aAAa,CAAC,GAAG;YACf,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,OAAO,KAAK,CAAC;YAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,OAAO,IAAI,CAAC;QACd,CAAC;QACD,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;KAC3B,CAAC;AACJ,CAAC"}

package/dist/evidence/observed-route-evidence.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Reduces raw runtime `Evidence` rows to the `{ method, path, status }` triples
+ * `checkObservedRoutes` (`@descryy/core`) reads — the mcp-package half of UAT
+ * phase 5 §5 (D2): the language-agnostic check reads only structured fields,
+ * never a framework's own log line, so this is the one place that reads a
+ * `NETWORK_RESPONSE`/`HTTP_ERROR` payload's shape at all.
+ *
+ * Two sources feed one triple, because `method` is not always on the same
+ * event as `status`:
+ *
+ * - The browser network collector (`@descryy/runtime-browser`) splits a
+ *   request into `NETWORK_REQUEST` (carries `method`) and `NETWORK_RESPONSE`/
+ *   `HTTP_ERROR` (carries `status`), joined by `requestId` or, failing that,
+ *   `url` — the identical join `playwright-driver.ts`'s own `collect()`
+ *   performs for the `browser_*` tools' evidence.
+ * - A future backend-log promotion (`descry-runtime`'s own per-language
+ *   adapters — not built; see UAT phase 5 §5's fix plan) is free to carry
+ *   `method` on the same event as `status`, since an access-log line already
+ *   has both — read first, before falling back to the join, so that shape
+ *   costs nothing extra to support once it exists.
+ */
+import type { Evidence } from "@descryy/runtime-contracts";
+import type { ObservedRouteEvidence } from "@descryy/core";
+export declare function extractObservedRouteEvidence(items: readonly Evidence[]): readonly ObservedRouteEvidence[];
+//# sourceMappingURL=observed-route-evidence.d.ts.map

package/dist/evidence/observed-route-evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observed-route-evidence.d.ts","sourceRoot":"","sources":["../../src/evidence/observed-route-evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAc3D,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,SAAS,qBAAqB,EAAE,CAqCzG"}

package/dist/evidence/observed-route-evidence.js

@@ -0,0 +1,76 @@
+/**
+ * Reduces raw runtime `Evidence` rows to the `{ method, path, status }` triples
+ * `checkObservedRoutes` (`@descryy/core`) reads — the mcp-package half of UAT
+ * phase 5 §5 (D2): the language-agnostic check reads only structured fields,
+ * never a framework's own log line, so this is the one place that reads a
+ * `NETWORK_RESPONSE`/`HTTP_ERROR` payload's shape at all.
+ *
+ * Two sources feed one triple, because `method` is not always on the same
+ * event as `status`:
+ *
+ * - The browser network collector (`@descryy/runtime-browser`) splits a
+ *   request into `NETWORK_REQUEST` (carries `method`) and `NETWORK_RESPONSE`/
+ *   `HTTP_ERROR` (carries `status`), joined by `requestId` or, failing that,
+ *   `url` — the identical join `playwright-driver.ts`'s own `collect()`
+ *   performs for the `browser_*` tools' evidence.
+ * - A future backend-log promotion (`descry-runtime`'s own per-language
+ *   adapters — not built; see UAT phase 5 §5's fix plan) is free to carry
+ *   `method` on the same event as `status`, since an access-log line already
+ *   has both — read first, before falling back to the join, so that shape
+ *   costs nothing extra to support once it exists.
+ */
+function stringField(payload, key) {
+    if (typeof payload !== "object" || payload === null)
+        return undefined;
+    const value = payload[key];
+    return typeof value === "string" ? value : undefined;
+}
+function numberField(payload, key) {
+    if (typeof payload !== "object" || payload === null)
+        return undefined;
+    const value = payload[key];
+    return typeof value === "number" ? value : undefined;
+}
+export function extractObservedRouteEvidence(items) {
+    const methodByRequestId = new Map();
+    const methodByUrl = new Map();
+    for (const item of items) {
+        if (item.eventType !== "NETWORK_REQUEST")
+            continue;
+        const method = stringField(item.payload, "method");
+        const url = stringField(item.payload, "url");
+        if (method === undefined)
+            continue;
+        if (item.requestId !== null)
+            methodByRequestId.set(item.requestId, method);
+        if (url !== undefined)
+            methodByUrl.set(url, method);
+    }
+    const results = [];
+    for (const item of items) {
+        if (item.eventType !== "NETWORK_RESPONSE" && item.eventType !== "HTTP_ERROR")
+            continue;
+        const status = numberField(item.payload, "status");
+        if (status === undefined)
+            continue;
+        const url = stringField(item.payload, "url");
+        if (url === undefined)
+            continue;
+        const method = stringField(item.payload, "method") ??
+            (item.requestId !== null ? methodByRequestId.get(item.requestId) : undefined) ??
+            methodByUrl.get(url);
+        if (method === undefined)
+            continue;
+        let path;
+        try {
+            path = new URL(url).pathname;
+        }
+        catch {
+            // Not a URL this check can reason about — never guessed at.
+            continue;
+        }
+        results.push({ method, path, status });
+    }
+    return results;
+}
+//# sourceMappingURL=observed-route-evidence.js.map

package/dist/evidence/observed-route-evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observed-route-evidence.js","sourceRoot":"","sources":["../../src/evidence/observed-route-evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,SAAS,WAAW,CAAC,OAAgB,EAAE,GAAW;IAChD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACtE,MAAM,KAAK,GAAI,OAAmC,CAAC,GAAG,CAAC,CAAC;IACxD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,SAAS,WAAW,CAAC,OAAgB,EAAE,GAAW;IAChD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACtE,MAAM,KAAK,GAAI,OAAmC,CAAC,GAAG,CAAC,CAAC;IACxD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,KAA0B;IACrE,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAkB,CAAC;IACpD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,SAAS,KAAK,iBAAiB;YAAE,SAAS;QACnD,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACnD,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC7C,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS;QACnC,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;YAAE,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAC3E,IAAI,GAAG,KAAK,SAAS;YAAE,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,SAAS,KAAK,kBAAkB,IAAI,IAAI,CAAC,SAAS,KAAK,YAAY;YAAE,SAAS;QACvF,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACnD,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS;QACnC,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC7C,IAAI,GAAG,KAAK,SAAS;YAAE,SAAS;QAEhC,MAAM,MAAM,GACV,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC;YACnC,CAAC,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC7E,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS;QAEnC,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,4DAA4D;YAC5D,SAAS;QACX,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/heap.d.ts

@@ -0,0 +1,61 @@
+/**
+ * P6-B1 — a fence in front of the V8 heap ceiling, because there is no catch behind it.
+ *
+ * `analyze` on a 7,700-file repository hit `FATAL ERROR: JavaScript heap out
+ * of memory` at V8's default ceiling and the MCP client saw a bare
+ * `Connection closed`: no state, no disclosure, no hint. A heap-limit abort is
+ * not a JavaScript exception — `try`/`catch`, `process.on("uncaughtException")`
+ * and `process.on("exit")` all fail to run, because V8 calls `abort()` rather
+ * than unwinding. So there is nothing to catch, and "report the OOM" has to
+ * mean "notice the wall before hitting it".
+ *
+ * That is what this module is: a reading of the ceiling actually in force and
+ * the bytes actually live, checked at the points where the caller's peak
+ * occurs, so an unrecoverable abort becomes a recoverable `failed` reply that
+ * names the phase and the remedy.
+ *
+ * ## Why a ratio, and why this one
+ *
+ * `heap_size_limit` is V8's hard ceiling; `heapUsed` is what survives the last
+ * collection plus whatever has been allocated since. The gap between "the
+ * guard could still run" and "the process is already dead" is one allocation,
+ * so the threshold has to leave room for the phase about to start, not for the
+ * next statement. The default is a starting value in the sense CLAUDE.md means
+ * — build against it, tune from data — and deliberately overridable, because a
+ * run refused at 90% that would have finished at 97% is a cost this guard
+ * imposes rather than prevents.
+ */
+/** Fraction of the heap ceiling past which the next large phase is refused rather than attempted. */
+export declare const HEAP_ABORT_RATIO = 0.9;
+export declare const HEAP_RATIO_ENV_VAR = "DESCRY_HEAP_ABORT_RATIO";
+export interface HeapReading {
+    /** Live bytes as of the last collection, plus anything allocated since. */
+    readonly usedBytes: number;
+    /** V8's hard ceiling — what `--max-old-space-size` sets. */
+    readonly limitBytes: number;
+    /** `usedBytes / limitBytes`, precomputed so callers cannot derive it two ways. */
+    readonly ratio: number;
+}
+/** The ceiling and the usage of the process this is called in. */
+export declare function readHeap(): HeapReading;
+/**
+ * The threshold in force, honouring `DESCRY_HEAP_ABORT_RATIO`.
+ *
+ * An unreadable or out-of-range override falls back to the default rather than
+ * disabling the guard: a typo in an env var must not silently restore the
+ * bare-`Connection closed` behaviour this module exists to remove. Setting it
+ * to `1` is the documented way to turn the guard off, and that is an explicit
+ * act rather than a typo.
+ */
+export declare function abortRatio(): number;
+/**
+ * `null` when there is headroom; otherwise the sentence to refuse with.
+ *
+ * The recommendation doubles the ceiling in force rather than adding a fixed
+ * margin: the run failed at the current size, so a hint that lands near it
+ * sends the operator round the same loop a second time. `phase` is the caller's
+ * own name for the step about to start — a heap failure with no phase named is
+ * a failure the operator cannot act on differently from the crash it replaced.
+ */
+export declare function heapGuard(reading: HeapReading, phase: string): string | null;
+//# sourceMappingURL=heap.d.ts.map

package/dist/heap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heap.d.ts","sourceRoot":"","sources":["../src/heap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,qGAAqG;AACrG,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,eAAO,MAAM,kBAAkB,4BAA4B,CAAC;AAI5D,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,kEAAkE;AAClE,wBAAgB,QAAQ,IAAI,WAAW,CAKtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAMnC;AAID;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAe5E"}

package/dist/heap.js

@@ -0,0 +1,82 @@
+/**
+ * P6-B1 — a fence in front of the V8 heap ceiling, because there is no catch behind it.
+ *
+ * `analyze` on a 7,700-file repository hit `FATAL ERROR: JavaScript heap out
+ * of memory` at V8's default ceiling and the MCP client saw a bare
+ * `Connection closed`: no state, no disclosure, no hint. A heap-limit abort is
+ * not a JavaScript exception — `try`/`catch`, `process.on("uncaughtException")`
+ * and `process.on("exit")` all fail to run, because V8 calls `abort()` rather
+ * than unwinding. So there is nothing to catch, and "report the OOM" has to
+ * mean "notice the wall before hitting it".
+ *
+ * That is what this module is: a reading of the ceiling actually in force and
+ * the bytes actually live, checked at the points where the caller's peak
+ * occurs, so an unrecoverable abort becomes a recoverable `failed` reply that
+ * names the phase and the remedy.
+ *
+ * ## Why a ratio, and why this one
+ *
+ * `heap_size_limit` is V8's hard ceiling; `heapUsed` is what survives the last
+ * collection plus whatever has been allocated since. The gap between "the
+ * guard could still run" and "the process is already dead" is one allocation,
+ * so the threshold has to leave room for the phase about to start, not for the
+ * next statement. The default is a starting value in the sense CLAUDE.md means
+ * — build against it, tune from data — and deliberately overridable, because a
+ * run refused at 90% that would have finished at 97% is a cost this guard
+ * imposes rather than prevents.
+ */
+import { getHeapStatistics } from "node:v8";
+/** Fraction of the heap ceiling past which the next large phase is refused rather than attempted. */
+export const HEAP_ABORT_RATIO = 0.9;
+export const HEAP_RATIO_ENV_VAR = "DESCRY_HEAP_ABORT_RATIO";
+const BYTES_PER_MIB = 1024 * 1024;
+/** The ceiling and the usage of the process this is called in. */
+export function readHeap() {
+    const stats = getHeapStatistics();
+    const limitBytes = stats.heap_size_limit;
+    const usedBytes = stats.used_heap_size;
+    return { usedBytes, limitBytes, ratio: limitBytes === 0 ? 0 : usedBytes / limitBytes };
+}
+/**
+ * The threshold in force, honouring `DESCRY_HEAP_ABORT_RATIO`.
+ *
+ * An unreadable or out-of-range override falls back to the default rather than
+ * disabling the guard: a typo in an env var must not silently restore the
+ * bare-`Connection closed` behaviour this module exists to remove. Setting it
+ * to `1` is the documented way to turn the guard off, and that is an explicit
+ * act rather than a typo.
+ */
+export function abortRatio() {
+    const raw = process.env[HEAP_RATIO_ENV_VAR];
+    if (raw === undefined)
+        return HEAP_ABORT_RATIO;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 1)
+        return HEAP_ABORT_RATIO;
+    return parsed;
+}
+const mib = (bytes) => Math.round(bytes / BYTES_PER_MIB);
+/**
+ * `null` when there is headroom; otherwise the sentence to refuse with.
+ *
+ * The recommendation doubles the ceiling in force rather than adding a fixed
+ * margin: the run failed at the current size, so a hint that lands near it
+ * sends the operator round the same loop a second time. `phase` is the caller's
+ * own name for the step about to start — a heap failure with no phase named is
+ * a failure the operator cannot act on differently from the crash it replaced.
+ */
+export function heapGuard(reading, phase) {
+    if (reading.ratio < abortRatio())
+        return null;
+    const inForceMib = mib(reading.limitBytes);
+    const recommendedMib = inForceMib * 2;
+    return (`${phase} was stopped before it started: ${mib(reading.usedBytes)} MiB of this process's ` +
+        `${inForceMib} MiB heap ceiling is already in use (${Math.round(reading.ratio * 100)}%), and ` +
+        "this phase allocates more than the remainder. Nothing was written to the graph, and this is " +
+        "not a statement about your code — it is this process running out of room to hold it. Raise " +
+        `the ceiling and re-run: NODE_OPTIONS="--max-old-space-size=${recommendedMib}" on the Descry ` +
+        `server process. To attempt it anyway, set ${HEAP_RATIO_ENV_VAR}=1 — the guard is what turns ` +
+        "an unrecoverable abort into this message, so without it the failure surfaces as a closed " +
+        "connection with no reason attached.");
+}
+//# sourceMappingURL=heap.js.map

package/dist/heap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heap.js","sourceRoot":"","sources":["../src/heap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5C,qGAAqG;AACrG,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC,MAAM,CAAC,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AAE5D,MAAM,aAAa,GAAG,IAAI,GAAG,IAAI,CAAC;AAWlC,kEAAkE;AAClE,MAAM,UAAU,QAAQ;IACtB,MAAM,KAAK,GAAG,iBAAiB,EAAE,CAAC;IAClC,MAAM,UAAU,GAAG,KAAK,CAAC,eAAe,CAAC;IACzC,MAAM,SAAS,GAAG,KAAK,CAAC,cAAc,CAAC;IACvC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,UAAU,EAAE,CAAC;AACzF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,gBAAgB,CAAC;IAC/C,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM,GAAG,CAAC;QAAE,OAAO,gBAAgB,CAAC;IACnF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,GAAG,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,aAAa,CAAC,CAAC;AAEzE;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,OAAoB,EAAE,KAAa;IAC3D,IAAI,OAAO,CAAC,KAAK,GAAG,UAAU,EAAE;QAAE,OAAO,IAAI,CAAC;IAE9C,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3C,MAAM,cAAc,GAAG,UAAU,GAAG,CAAC,CAAC;IACtC,OAAO,CACL,GAAG,KAAK,mCAAmC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,yBAAyB;QAC1F,GAAG,UAAU,wCAAwC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,GAAG,GAAG,CAAC,UAAU;QAC9F,8FAA8F;QAC9F,6FAA6F;QAC7F,8DAA8D,cAAc,kBAAkB;QAC9F,6CAA6C,kBAAkB,+BAA+B;QAC9F,2FAA2F;QAC3F,qCAAqC,CACtC,CAAC;AACJ,CAAC"}

package/dist/heartbeat.d.ts

@@ -0,0 +1,46 @@
+/**
+ * P6-B2 — a periodic progress beat for the duration of one long awaited step.
+ *
+ * `analyze` on a 7,700-file repository reliably exceeded the calling client's
+ * timeout even with the heap ceiling raised, and completed only when driven
+ * over stdio with no client-side timeout at all. It was not hung; it emitted
+ * one `notifications/progress` frame per *source*, so on a repo with a single
+ * language adapter the whole multi-minute read fell between two frames. MCP
+ * clients reset a request's timeout when a progress frame arrives for it, so a
+ * correct run and a wedged one were indistinguishable from the outside, and
+ * the timeout fired on the correct one.
+ *
+ * ## What this is not
+ *
+ * It does not make anything faster, and it is not a guarantee: resetting a
+ * timeout on progress is a client behaviour, not something the protocol
+ * obliges. That is why the elapsed time goes *in* the message rather than the
+ * beat being a bare ping — a caller reading the frames can see the step
+ * advancing rather than being asserted to. Honest degradation (rule 7) cuts
+ * both ways here: this discloses that work is ongoing, it does not claim
+ * progress it cannot measure. The adapter is opaque while it runs, so the
+ * count of files done is not available to report and none is invented.
+ */
+/** Interval between beats while a step is running. Well inside the 60s default most clients use. */
+export declare const HEARTBEAT_MS = 15000;
+export declare const HEARTBEAT_ENV_VAR = "DESCRY_PROGRESS_HEARTBEAT_MS";
+/**
+ * The interval in force, honouring `DESCRY_PROGRESS_HEARTBEAT_MS`.
+ *
+ * A zero, a negative or an unreadable value falls back to the default rather
+ * than being taken literally: zero is a busy loop and not a plausible way to
+ * ask for one, so reading it as "the operator meant to disable beats" would
+ * turn a typo into the exact silence this module removes.
+ */
+export declare function heartbeatMs(): number;
+/**
+ * Run `work`, beating `label` plus elapsed seconds every `intervalMs` until it
+ * settles.
+ *
+ * The timer is cleared in a `finally`, so a step that throws stops beating on
+ * the same tick it fails — a beat outliving its step would report a run that
+ * has already finished or died. `unref()` keeps a pending beat from holding
+ * the process open on its own.
+ */
+export declare function withHeartbeat<T>(label: string, beat: (message: string) => void, work: () => Promise<T>, intervalMs?: number): Promise<T>;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,oGAAoG;AACpG,eAAO,MAAM,YAAY,QAAS,CAAC;AAEnC,eAAO,MAAM,iBAAiB,iCAAiC,CAAC;AAEhE;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAMpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC/B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,UAAU,GAAE,MAAsB,GACjC,OAAO,CAAC,CAAC,CAAC,CAWZ"}

package/dist/heartbeat.js

@@ -0,0 +1,66 @@
+/**
+ * P6-B2 — a periodic progress beat for the duration of one long awaited step.
+ *
+ * `analyze` on a 7,700-file repository reliably exceeded the calling client's
+ * timeout even with the heap ceiling raised, and completed only when driven
+ * over stdio with no client-side timeout at all. It was not hung; it emitted
+ * one `notifications/progress` frame per *source*, so on a repo with a single
+ * language adapter the whole multi-minute read fell between two frames. MCP
+ * clients reset a request's timeout when a progress frame arrives for it, so a
+ * correct run and a wedged one were indistinguishable from the outside, and
+ * the timeout fired on the correct one.
+ *
+ * ## What this is not
+ *
+ * It does not make anything faster, and it is not a guarantee: resetting a
+ * timeout on progress is a client behaviour, not something the protocol
+ * obliges. That is why the elapsed time goes *in* the message rather than the
+ * beat being a bare ping — a caller reading the frames can see the step
+ * advancing rather than being asserted to. Honest degradation (rule 7) cuts
+ * both ways here: this discloses that work is ongoing, it does not claim
+ * progress it cannot measure. The adapter is opaque while it runs, so the
+ * count of files done is not available to report and none is invented.
+ */
+/** Interval between beats while a step is running. Well inside the 60s default most clients use. */
+export const HEARTBEAT_MS = 15_000;
+export const HEARTBEAT_ENV_VAR = "DESCRY_PROGRESS_HEARTBEAT_MS";
+/**
+ * The interval in force, honouring `DESCRY_PROGRESS_HEARTBEAT_MS`.
+ *
+ * A zero, a negative or an unreadable value falls back to the default rather
+ * than being taken literally: zero is a busy loop and not a plausible way to
+ * ask for one, so reading it as "the operator meant to disable beats" would
+ * turn a typo into the exact silence this module removes.
+ */
+export function heartbeatMs() {
+    const raw = process.env[HEARTBEAT_ENV_VAR];
+    if (raw === undefined)
+        return HEARTBEAT_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return HEARTBEAT_MS;
+    return parsed;
+}
+/**
+ * Run `work`, beating `label` plus elapsed seconds every `intervalMs` until it
+ * settles.
+ *
+ * The timer is cleared in a `finally`, so a step that throws stops beating on
+ * the same tick it fails — a beat outliving its step would report a run that
+ * has already finished or died. `unref()` keeps a pending beat from holding
+ * the process open on its own.
+ */
+export async function withHeartbeat(label, beat, work, intervalMs = heartbeatMs()) {
+    const started = Date.now();
+    const timer = setInterval(() => {
+        beat(`${label} — still running, ${Math.round((Date.now() - started) / 1000)}s elapsed`);
+    }, intervalMs);
+    timer.unref?.();
+    try {
+        return await work();
+    }
+    finally {
+        clearInterval(timer);
+    }
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.js","sourceRoot":"","sources":["../src/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,oGAAoG;AACpG,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AAEnC,MAAM,CAAC,MAAM,iBAAiB,GAAG,8BAA8B,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC3C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,YAAY,CAAC;IACjE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAa,EACb,IAA+B,EAC/B,IAAsB,EACtB,aAAqB,WAAW,EAAE;IAElC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,IAAI,CAAC,GAAG,KAAK,qBAAqB,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;IAC1F,CAAC,EAAE,UAAU,CAAC,CAAC;IACf,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAChB,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,EAAE,CAAC;IACtB,CAAC;YAAS,CAAC;QACT,aAAa,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/** `@descryy/mcp` — the agent-facing front door. A thin wrapper over the query layer
+ *  (DEC-002): every consumer goes through here and nothing touches storage directly —
+ *  which is why tools hold a `Session`, not a driver. */
+export { createMcpServer } from "./server.ts";
+export type { McpServer, McpServerOptions } from "./server.ts";
+export { Session, loadConfig, writeConfig, writeSources, ConfigError, CONFIG_RELATIVE_PATH, DEFAULT_GRAPH_RELATIVE_PATH, } from "./session.ts";
+export type { DescryConfig, SessionOptions, ConfigPatch } from "./session.ts";
+export { loadSources, detectSources, normaliseSpec } from "./registry.ts";
+export type { SourceSpec, LoadedSource, SourceLoadFailure, RegistryResult } from "./registry.ts";
+/** The real, at-rest credential store — see the module's own header for why this is the one
+ *  place `@descryy/cli` reaches this without depending on `@descryy/runtime-environment-profile`
+ *  itself. */
+export { createDefaultCredentialStore } from "./credential-store.ts";
+export type { CredentialStoreOptions, WritableCredentialStore } from "./credential-store.ts";
+export { renderAnswer, renderFailed, renderHandshake, renderTimedOut, renderToolError, DisclosureError, TOOL_TIERS, } from "./render.ts";
+export type { AnswerEnvelope, CallToolResult, Provenance, ResultState, ToolAnswer, ToolTier, TruncationDetail, } from "./render.ts";
+export { TOOLS, TOOLS_BY_NAME, ToolInputError, resolveOneNode } from "./tools/index.ts";
+export type { BriefNode, NodeCandidates, Progress, ToolContext, ToolDefinition, } from "./tools/index.ts";
+/** The shape each tool puts in `AnswerEnvelope.data`. `data` is `unknown` in the envelope
+ *  by design, but an AI caller can't rely on an unwritten shape — each type here describes
+ *  what its tool returns today; genuinely conditional payloads are unions, not `unknown`. */
+export type { AffectedRef, AnalyzeData, BlockedCheck, CoChangedFile, ConfigDependencyReport, ContractPathFinding, ContractShapeMismatchReport, ContractShapeStatus, ContractsData, CrossPrData, CrossPrEmptyDiff, CrossPrGitFailure, CrossPrReport, EnvFindingReport, HiddenDependencyCheck, HiddenDependencyFinding, HistoryData, HistoryFile, HistoryFileResolved, HistoryFileUnresolved, HistoryReport, ImpactData, ImpactReport, ImpactedNode, LinkWorkspaceData, MarkIncidentData, LinkedRepo, OverlapCheck, OverlapReportChecked, PrAnalysisData, PrAnalysisEmptyDiff, PrAnalysisGitFailure, PrAnalysisLists, PrAnalysisRange, PrAnalysisReport, PrAnalysisUnresolved, PropagationData, PropagationReport, QuestionsData, ReachedNode, RelatedNode, ScopeData, ScopeNotSeeded, ScopeReport, ScopeTierCount, ScopedNodeReport, SimilarIncidentReport, SimilarIncidentSignalReport, SimilarIncidentsData, SourceRun, SupersededCheck, TracedPath, ValidateData, } from "./tools/index.ts";
+export { serveStdio, guardStdout, createLineReader } from "./transport.ts";
+export type { Transport, StdioOptions } from "./transport.ts";
+export { PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, negotiateVersion, parseMessage, ProtocolError, } from "./protocol.ts";
+export type { RpcRequest, RpcNotification, RpcResponse, RpcMessage, RpcId } from "./protocol.ts";
+/** The scenario format — storage, schema, refusals. Re-exported here so `descry check`
+ *  doesn't reach past the package boundary — a second reader importing the relative path
+ *  could drift from this one the day the schema changes. */
+export { MIN_READABLE_SCHEMA_VERSION, SCENARIO_SCHEMA_VERSION, isSecretRef, isUnverifying, parseScenario, readSecretRef, referencedVariables, resolveSecretText, secretRefFor, serializeScenario, scenariosDirectory, scenarioPath, listScenarios, ScenarioListError, readScenario, writeScenario, projectScenarioToRunPlan, projectRunPlanToScenario, } from "./scenarios/index.ts";
+export type { CredentialStoreLike, Scenario, SecretEnvironment, SecretRef, SecretResolution, ScenarioStep, ScenarioAssertion, ScenarioAssertionKind, ScenarioActionKind, ScenarioParseResult, TargetDescriptor, ProjectedStep, ProjectedStepKind, ProjectedBrowserRunPlan, ProjectionRefusal, ScenarioProjection, PlanProjection, RawProjectedStep, ScenarioMeta, } from "./scenarios/index.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/** `@descryy/mcp` — the agent-facing front door. A thin wrapper over the query layer
+ *  (DEC-002): every consumer goes through here and nothing touches storage directly —
+ *  which is why tools hold a `Session`, not a driver. */
+export { createMcpServer } from "./server.js";
+export { Session, loadConfig, writeConfig, writeSources, ConfigError, CONFIG_RELATIVE_PATH, DEFAULT_GRAPH_RELATIVE_PATH, } from "./session.js";
+export { loadSources, detectSources, normaliseSpec } from "./registry.js";
+/** The real, at-rest credential store — see the module's own header for why this is the one
+ *  place `@descryy/cli` reaches this without depending on `@descryy/runtime-environment-profile`
+ *  itself. */
+export { createDefaultCredentialStore } from "./credential-store.js";
+export { renderAnswer, renderFailed, renderHandshake, renderTimedOut, renderToolError, DisclosureError, TOOL_TIERS, } from "./render.js";
+export { TOOLS, TOOLS_BY_NAME, ToolInputError, resolveOneNode } from "./tools/index.js";
+export { serveStdio, guardStdout, createLineReader } from "./transport.js";
+export { PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, negotiateVersion, parseMessage, ProtocolError, } from "./protocol.js";
+/** The scenario format — storage, schema, refusals. Re-exported here so `descry check`
+ *  doesn't reach past the package boundary — a second reader importing the relative path
+ *  could drift from this one the day the schema changes. */
+export { MIN_READABLE_SCHEMA_VERSION, SCENARIO_SCHEMA_VERSION, isSecretRef, isUnverifying, parseScenario, readSecretRef, referencedVariables, resolveSecretText, secretRefFor, serializeScenario, scenariosDirectory, scenarioPath, listScenarios, ScenarioListError, readScenario, writeScenario, projectScenarioToRunPlan, projectRunPlanToScenario, } from "./scenarios/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;yDAEyD;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,EACL,OAAO,EACP,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG1E;;cAEc;AACd,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAGrE,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,eAAe,EACf,eAAe,EACf,UAAU,GACX,MAAM,aAAa,CAAC;AAWrB,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAoExF,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAG3E,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,gBAAgB,EAChB,YAAY,EACZ,aAAa,GACd,MAAM,eAAe,CAAC;AAGvB;;4DAE4D;AAC5D,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC"}

package/dist/module-trust.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Gates `import()` of caller-named specifiers (A-F1/A-F2, three ungated call sites). Refuses path-like specifiers (exact bytes, no install step) by default.
+ * Also refuses a bare specifier resolved into the scanned repo's own git-tracked `node_modules` (real `npm install` leaves it untracked) — a repo can otherwise ship a payload merely by being cloned.
+ * Escape hatches: `DESCRY_ALLOW_PATH_ADAPTER_MODULES=1`, `DESCRY_ALLOW_TRACKED_NODE_MODULES=1` (server env only, never repo-set).
+ */
+export declare const ALLOW_PATH_MODULES_ENV_VAR = "DESCRY_ALLOW_PATH_ADAPTER_MODULES";
+export declare const ALLOW_TRACKED_NODE_MODULES_ENV_VAR = "DESCRY_ALLOW_TRACKED_NODE_MODULES";
+export type ModuleTrustDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+};
+/** Path-like: relative/absolute/drive-absolute/home-relative path, or any URL-scheme specifier (`file:`, `http:`, `data:`, …) — names exact bytes, not an installed package. Everything else resolves normally. */
+export declare function isPathLikeSpecifier(specifier: string): boolean;
+/**
+ * Whether `resolvedAbsolutePath` sits inside `repoPath` — never true for a path that
+ * merely shares a prefix (`/home/user/repo-other` is not inside `/home/user/repo`).
+ *
+ * UAT phase 5 §1b: `resolveFromRepo` anchors `createRequire` at the repo's own
+ * `package.json` and lets Node's ordinary CJS algorithm walk the entire ancestor
+ * chain — `repo/node_modules` → `$HOME/node_modules` → `/node_modules`. A stray
+ * install anywhere above the repository wins over what the repository (or the
+ * server) actually intended, and nothing previously distinguished "found inside
+ * the repo" from "found somewhere Node's upward walk happened to land". This is
+ * the containment test `resolveRepoAdapterModule` uses to draw that line.
+ */
+export declare function resolvesInsideRepo(repoPath: string, resolvedAbsolutePath: string): boolean;
+/** Decides if `specifier` may be `import()`-ed; never throws — each call site turns a refusal into its own existing failure channel (`SourceLoadFailure`, etc.). */
+export declare function checkModuleTrust(specifier: string): ModuleTrustDecision;
+/** Follow-up to `checkModuleTrust`: refuses a bare specifier resolved into the scanned repo's own git-tracked `node_modules` (real `npm install` leaves it untracked) — closes a payload-via-commit gap. A `null` git-tracked check (no `.git`) is allowed, not refused: the exploit needs a clone, and a non-git directory is a real workflow this check has no history to verify either way. */
+export declare function checkRepoResolvedModuleTrust(options: {
+    readonly specifier: string;
+    readonly repoPath: string;
+    readonly resolvedAbsolutePath: string;
+}): Promise<ModuleTrustDecision>;
+//# sourceMappingURL=module-trust.d.ts.map

package/dist/module-trust.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-trust.d.ts","sourceRoot":"","sources":["../src/module-trust.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,eAAO,MAAM,0BAA0B,sCAAsC,CAAC;AAC9E,eAAO,MAAM,kCAAkC,sCAAsC,CAAC;AAEtF,MAAM,MAAM,mBAAmB,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpH,mNAAmN;AACnN,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAK9D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAG1F;AAOD,oKAAoK;AACpK,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CAYvE;AAOD,kYAAkY;AAClY,wBAAsB,4BAA4B,CAAC,OAAO,EAAE;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAiB/B"}

package/dist/module-trust.js

@@ -0,0 +1,77 @@
+/**
+ * Gates `import()` of caller-named specifiers (A-F1/A-F2, three ungated call sites). Refuses path-like specifiers (exact bytes, no install step) by default.
+ * Also refuses a bare specifier resolved into the scanned repo's own git-tracked `node_modules` (real `npm install` leaves it untracked) — a repo can otherwise ship a payload merely by being cloned.
+ * Escape hatches: `DESCRY_ALLOW_PATH_ADAPTER_MODULES=1`, `DESCRY_ALLOW_TRACKED_NODE_MODULES=1` (server env only, never repo-set).
+ */
+import { sep } from "node:path";
+import { isPathTrackedByGit } from "@descryy/core";
+export const ALLOW_PATH_MODULES_ENV_VAR = "DESCRY_ALLOW_PATH_ADAPTER_MODULES";
+export const ALLOW_TRACKED_NODE_MODULES_ENV_VAR = "DESCRY_ALLOW_TRACKED_NODE_MODULES";
+/** Path-like: relative/absolute/drive-absolute/home-relative path, or any URL-scheme specifier (`file:`, `http:`, `data:`, …) — names exact bytes, not an installed package. Everything else resolves normally. */
+export function isPathLikeSpecifier(specifier) {
+    if (specifier.startsWith(".") || specifier.startsWith("/") || specifier.startsWith("~"))
+        return true;
+    if (/^[a-zA-Z]:[\\/]/.test(specifier))
+        return true;
+    if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(specifier))
+        return true;
+    return false;
+}
+/**
+ * Whether `resolvedAbsolutePath` sits inside `repoPath` — never true for a path that
+ * merely shares a prefix (`/home/user/repo-other` is not inside `/home/user/repo`).
+ *
+ * UAT phase 5 §1b: `resolveFromRepo` anchors `createRequire` at the repo's own
+ * `package.json` and lets Node's ordinary CJS algorithm walk the entire ancestor
+ * chain — `repo/node_modules` → `$HOME/node_modules` → `/node_modules`. A stray
+ * install anywhere above the repository wins over what the repository (or the
+ * server) actually intended, and nothing previously distinguished "found inside
+ * the repo" from "found somewhere Node's upward walk happened to land". This is
+ * the containment test `resolveRepoAdapterModule` uses to draw that line.
+ */
+export function resolvesInsideRepo(repoPath, resolvedAbsolutePath) {
+    const root = repoPath.endsWith(sep) ? repoPath : `${repoPath}${sep}`;
+    return resolvedAbsolutePath.startsWith(root);
+}
+function pathModulesAllowed() {
+    const value = process.env[ALLOW_PATH_MODULES_ENV_VAR];
+    return value === "1" || value === "true";
+}
+/** Decides if `specifier` may be `import()`-ed; never throws — each call site turns a refusal into its own existing failure channel (`SourceLoadFailure`, etc.). */
+export function checkModuleTrust(specifier) {
+    if (!isPathLikeSpecifier(specifier))
+        return { allowed: true };
+    if (pathModulesAllowed())
+        return { allowed: true };
+    return {
+        allowed: false,
+        reason: `"${specifier}" names a file path or URL rather than an installed package. Loading one executes ` +
+            "arbitrary code with no further confirmation, and this specifier can come from a scanned repository's " +
+            "own configuration or from a tool call — neither is necessarily something the operator running this " +
+            `server chose. Refused by default; set ${ALLOW_PATH_MODULES_ENV_VAR}=1 in this server's own environment ` +
+            "to allow it, and only do that for adapters and configuration you, the operator, trust.",
+    };
+}
+function trackedNodeModulesAllowed() {
+    const value = process.env[ALLOW_TRACKED_NODE_MODULES_ENV_VAR];
+    return value === "1" || value === "true";
+}
+/** Follow-up to `checkModuleTrust`: refuses a bare specifier resolved into the scanned repo's own git-tracked `node_modules` (real `npm install` leaves it untracked) — closes a payload-via-commit gap. A `null` git-tracked check (no `.git`) is allowed, not refused: the exploit needs a clone, and a non-git directory is a real workflow this check has no history to verify either way. */
+export async function checkRepoResolvedModuleTrust(options) {
+    if (trackedNodeModulesAllowed())
+        return { allowed: true };
+    const tracked = await isPathTrackedByGit(options.repoPath, options.resolvedAbsolutePath);
+    if (tracked !== true)
+        return { allowed: true };
+    return {
+        allowed: false,
+        reason: `"${options.specifier}" resolved to ${options.resolvedAbsolutePath}, inside ${options.repoPath}'s own ` +
+            "node_modules — but that file is committed to this repository's own git history, not installed by a " +
+            "package manager (a real `npm install` leaves node_modules untracked, almost universally). A " +
+            "repository that commits its own node_modules can deliver arbitrary code to anyone who merely clones " +
+            `it, with no npm install step at all. Refused by default; set ${ALLOW_TRACKED_NODE_MODULES_ENV_VAR}=1 ` +
+            "in this server's own environment to allow it, and only do that for a repository whose committed " +
+            "node_modules you, the operator, trust.",
+    };
+}
+//# sourceMappingURL=module-trust.js.map