narai-primitives 2.0.0-rc.1

package/dist/toolkit/fetch_attachment.js

@@ -0,0 +1,169 @@
+/**
+ * fetch_attachment — single-call primitive that fetches a URL, reads the
+ * bytes (under a size cap), dispatches to `extractBinary` or UTF-8 decode
+ * based on content-type, and returns a structured envelope.
+ *
+ * Used by REST connectors (Confluence/Notion/Jira/GitHub) to implement
+ * `get_attachment` actions without each reimplementing the fetch +
+ * extract + checksum pipeline.
+ *
+ * Contract:
+ *   - Never throws on unsupported mime types or missing optional extraction
+ *     deps. Surfaces `extracted.format = "skipped"` + a populated `warning`.
+ *   - Throws on invalid URL scheme (anything but http/https) before
+ *     making the network call.
+ *   - Throws when response body exceeds `maxBytes`.
+ *   - Returns `{ rawBytes, contentType, filename, checksum, extracted,
+ *     sizeBytes, sourceUrl }`. Filename is sanitized via `sanitizeLabel`.
+ *
+ * For tests, `fetchImpl` can be injected to bypass the real network.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { validateUrl, sanitizeLabel } from "./security_check.js";
+import { FETCH_MAX_BYTES_DEFAULT, FETCH_TIMEOUT_MS_DEFAULT, FetchCapExceeded } from "./fetch_helper.js";
+import { extract as extractBinary, FORMAT_MAP } from "./extract_binary.js";
+const MIME_TO_FORMAT = {
+    "application/pdf": "pdf",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
+};
+function parseContentDispositionFilename(header) {
+    if (!header)
+        return null;
+    // Handle quoted: `attachment; filename="a.txt"` and unquoted: `attachment; filename=a.txt`.
+    const match = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(header);
+    return match && match[1] ? match[1].trim() : null;
+}
+function filenameFromUrl(url) {
+    try {
+        const u = new URL(url);
+        const tail = u.pathname.split("/").filter(Boolean).pop();
+        return tail ?? "attachment";
+    }
+    catch {
+        return "attachment";
+    }
+}
+function formatExtension(fmt) {
+    if (fmt === "pdf")
+        return ".pdf";
+    if (fmt === "docx")
+        return ".docx";
+    return ".pptx";
+}
+export async function fetchAttachment(url, opts = {}) {
+    if (!validateUrl(url)) {
+        throw new Error(`fetchAttachment: invalid URL scheme for '${url}' (only http/https allowed)`);
+    }
+    const maxBytes = opts.maxBytes ?? FETCH_MAX_BYTES_DEFAULT;
+    const timeoutMs = opts.timeoutMs ?? FETCH_TIMEOUT_MS_DEFAULT;
+    const doFetch = opts.fetchImpl ?? globalThis.fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const init = { signal: controller.signal };
+    if (opts.headers !== undefined) {
+        init.headers = opts.headers;
+    }
+    let response;
+    try {
+        response = await doFetch(url, init);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const contentLength = Number(response.headers.get("content-length") ?? "0");
+    if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+        throw new FetchCapExceeded(maxBytes, contentLength, url);
+    }
+    const buffer = await response.arrayBuffer();
+    const rawBytes = new Uint8Array(buffer);
+    if (rawBytes.byteLength > maxBytes) {
+        throw new FetchCapExceeded(maxBytes, rawBytes.byteLength, url);
+    }
+    const contentType = (response.headers.get("content-type") ?? "application/octet-stream")
+        .split(";")[0]
+        ?.trim()
+        .toLowerCase() ?? "application/octet-stream";
+    const dispositionFilename = parseContentDispositionFilename(response.headers.get("content-disposition"));
+    const rawFilename = dispositionFilename ?? filenameFromUrl(url);
+    const filename = sanitizeLabel(rawFilename, 255);
+    const checksum = createHash("sha256").update(rawBytes).digest("hex");
+    let extracted;
+    if (contentType.startsWith("text/")) {
+        extracted = {
+            format: "text",
+            text: new TextDecoder("utf-8").decode(rawBytes),
+        };
+    }
+    else if (contentType in MIME_TO_FORMAT) {
+        const fmt = MIME_TO_FORMAT[contentType];
+        const ext = formatExtension(fmt);
+        const tmp = path.join(os.tmpdir(), `toolkit-attach-${randomUUID()}${ext}`);
+        try {
+            fs.writeFileSync(tmp, rawBytes);
+            const r = await extractBinary(tmp, fmt, { maxBytes });
+            extracted = { format: r.format, text: r.text };
+        }
+        catch (e) {
+            extracted = {
+                format: "skipped",
+                text: null,
+                warning: e instanceof Error ? e.message : String(e),
+            };
+        }
+        finally {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        }
+    }
+    else if (FORMAT_MAP[path.extname(filename).toLowerCase()]) {
+        // Server advertised a generic mime (octet-stream etc.) but the filename
+        // extension is one we can extract — still try.
+        const fmt = FORMAT_MAP[path.extname(filename).toLowerCase()];
+        const tmp = path.join(os.tmpdir(), `toolkit-attach-${randomUUID()}${formatExtension(fmt)}`);
+        try {
+            fs.writeFileSync(tmp, rawBytes);
+            const r = await extractBinary(tmp, fmt, { maxBytes });
+            extracted = { format: r.format, text: r.text };
+        }
+        catch (e) {
+            extracted = {
+                format: "skipped",
+                text: null,
+                warning: e instanceof Error ? e.message : String(e),
+            };
+        }
+        finally {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        }
+    }
+    else {
+        extracted = {
+            format: "skipped",
+            text: null,
+            warning: `Unsupported mime type '${contentType}' — no extractor configured`,
+        };
+    }
+    return {
+        rawBytes,
+        contentType,
+        filename,
+        checksum,
+        extracted,
+        sizeBytes: rawBytes.byteLength,
+        sourceUrl: url,
+    };
+}
+//# sourceMappingURL=fetch_attachment.js.map

package/dist/toolkit/fetch_attachment.js.map

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

package/dist/toolkit/fetch_helper.d.ts

@@ -0,0 +1,47 @@
+/**
+ * fetch_helper — shared HTTP fetch wrapper with size + timeout caps.
+ *
+ * Behaviour:
+ *   - `AbortController` enforces the timeout. On overrun, the returned
+ *     promise rejects with the underlying `AbortError`.
+ *   - Body size is enforced by streaming the response and counting
+ *     bytes. If `content-length` is present and already exceeds the
+ *     cap, we short-circuit before reading. Otherwise we read chunks;
+ *     once the running total exceeds `maxBytes`, we abort and throw
+ *     `FetchCapExceeded`.
+ *   - Consumers receive a plain `Response` whose `body` has been
+ *     replaced by a `ReadableStream` that reads from an in-memory
+ *     buffer; calling `.text()` or `.arrayBuffer()` on that Response
+ *     returns exactly the (capped) bytes.
+ */
+export declare const FETCH_MAX_BYTES_DEFAULT: number;
+export declare const FETCH_TIMEOUT_MS_DEFAULT = 60000;
+/** Options controlling the caps. Missing fields fall back to defaults. */
+export interface FetchCapsOptions {
+    maxBytes?: number;
+    timeoutMs?: number;
+    /** Optional external signal composed with the internal timeout. */
+    signal?: AbortSignal;
+}
+/** Thrown when the response body grows past `maxBytes`. */
+export declare class FetchCapExceeded extends Error {
+    readonly capBytes: number;
+    readonly observedBytes: number;
+    constructor(capBytes: number, observedBytes: number, url: string);
+}
+/**
+ * Perform a cap-limited fetch. The returned Response is safe to treat
+ * as a normal `Response`; its body has already been read into memory
+ * (bounded by `maxBytes`), and the Response is rebuilt around that
+ * buffer so downstream `.text()` / `.json()` / `.arrayBuffer()` calls
+ * work without re-hitting the network.
+ *
+ * Throws:
+ *   - `FetchCapExceeded` when `content-length` or streamed bytes
+ *     exceed `maxBytes`.
+ *   - `DOMException` / `AbortError` when the timeout fires or an
+ *     external signal is aborted.
+ *   - Any other error thrown by `fetch` itself (network, DNS, etc.).
+ */
+export declare function fetchWithCaps(url: string, init?: RequestInit, caps?: FetchCapsOptions): Promise<Response>;
+//# sourceMappingURL=fetch_helper.d.ts.map

package/dist/toolkit/fetch_helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch_helper.d.ts","sourceRoot":"","sources":["../../src/toolkit/fetch_helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,uBAAuB,QAAmB,CAAC;AACxD,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,2DAA2D;AAC3D,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBACnB,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CASjE;AAsBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,WAAgB,EACtB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,QAAQ,CAAC,CAuDnB"}

package/dist/toolkit/fetch_helper.js

@@ -0,0 +1,124 @@
+/**
+ * fetch_helper — shared HTTP fetch wrapper with size + timeout caps.
+ *
+ * Behaviour:
+ *   - `AbortController` enforces the timeout. On overrun, the returned
+ *     promise rejects with the underlying `AbortError`.
+ *   - Body size is enforced by streaming the response and counting
+ *     bytes. If `content-length` is present and already exceeds the
+ *     cap, we short-circuit before reading. Otherwise we read chunks;
+ *     once the running total exceeds `maxBytes`, we abort and throw
+ *     `FetchCapExceeded`.
+ *   - Consumers receive a plain `Response` whose `body` has been
+ *     replaced by a `ReadableStream` that reads from an in-memory
+ *     buffer; calling `.text()` or `.arrayBuffer()` on that Response
+ *     returns exactly the (capped) bytes.
+ */
+export const FETCH_MAX_BYTES_DEFAULT = 50 * 1024 * 1024; // 50 MB
+export const FETCH_TIMEOUT_MS_DEFAULT = 60_000; // 60 s
+/** Thrown when the response body grows past `maxBytes`. */
+export class FetchCapExceeded extends Error {
+    capBytes;
+    observedBytes;
+    constructor(capBytes, observedBytes, url) {
+        super(`fetch_helper: response body exceeded cap of ${capBytes} bytes ` +
+            `(observed ${observedBytes} while fetching ${url})`);
+        this.name = "FetchCapExceeded";
+        this.capBytes = capBytes;
+        this.observedBytes = observedBytes;
+    }
+}
+function mergeSignals(internal, external) {
+    if (external === undefined)
+        return internal;
+    const anyFn = AbortSignal.any;
+    if (typeof anyFn === "function") {
+        return anyFn([internal, external]);
+    }
+    const controller = new AbortController();
+    const onAbort = (reason) => {
+        controller.abort(reason);
+    };
+    if (internal.aborted)
+        controller.abort(internal.reason);
+    else
+        internal.addEventListener("abort", () => onAbort(internal.reason), { once: true });
+    if (external.aborted)
+        controller.abort(external.reason);
+    else
+        external.addEventListener("abort", () => onAbort(external.reason), { once: true });
+    return controller.signal;
+}
+/**
+ * Perform a cap-limited fetch. The returned Response is safe to treat
+ * as a normal `Response`; its body has already been read into memory
+ * (bounded by `maxBytes`), and the Response is rebuilt around that
+ * buffer so downstream `.text()` / `.json()` / `.arrayBuffer()` calls
+ * work without re-hitting the network.
+ *
+ * Throws:
+ *   - `FetchCapExceeded` when `content-length` or streamed bytes
+ *     exceed `maxBytes`.
+ *   - `DOMException` / `AbortError` when the timeout fires or an
+ *     external signal is aborted.
+ *   - Any other error thrown by `fetch` itself (network, DNS, etc.).
+ */
+export async function fetchWithCaps(url, init = {}, caps = {}) {
+    const maxBytes = caps.maxBytes ?? FETCH_MAX_BYTES_DEFAULT;
+    const timeoutMs = caps.timeoutMs ?? FETCH_TIMEOUT_MS_DEFAULT;
+    const timeoutCtl = new AbortController();
+    const timer = setTimeout(() => timeoutCtl.abort(new Error("fetch_helper timeout")), timeoutMs);
+    const signal = mergeSignals(timeoutCtl.signal, caps.signal ?? init.signal ?? undefined);
+    let response;
+    try {
+        response = await fetch(url, { ...init, signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const clHeader = response.headers.get("content-length");
+    if (clHeader !== null) {
+        const cl = Number(clHeader);
+        if (Number.isFinite(cl) && cl > maxBytes) {
+            try {
+                await response.body?.cancel();
+            }
+            catch { /* best-effort */ }
+            throw new FetchCapExceeded(maxBytes, cl, url);
+        }
+    }
+    const reader = response.body?.getReader();
+    if (reader === undefined) {
+        return response;
+    }
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value === undefined)
+            continue;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            try {
+                await reader.cancel();
+            }
+            catch { /* best-effort */ }
+            throw new FetchCapExceeded(maxBytes, total, url);
+        }
+        chunks.push(value);
+    }
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new Response(merged, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}
+//# sourceMappingURL=fetch_helper.js.map

package/dist/toolkit/fetch_helper.js.map

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

package/dist/toolkit/guardrail.d.ts

@@ -0,0 +1,63 @@
+/**
+ * guardrail — connector-side rules for blocking dangerous Bash invocations,
+ * reusable from any plugin's PreToolUse hook.
+ *
+ * This module supplies:
+ *   - The data shapes for a guardrail manifest (one JSON file per connector
+ *     under `plugin/hooks/guardrails.json`).
+ *   - A loader that reads + validates a manifest from disk.
+ *   - A matching engine extracted from db-agent-connector's db-guard hook
+ *     so every consumer (the per-connector hooks AND the hub's unified hook)
+ *     evaluates the same way.
+ *
+ * Best-effort, not a security boundary. The engine fails open on parse
+ * errors; callers are expected to handle missing/invalid manifests gracefully.
+ */
+export interface GuardrailRule {
+    /**
+     * Match when the first whitespace-separated token of a Bash segment, after
+     * stripping env-var prefixes and shell openers, has a basename in this list.
+     */
+    block_first_token_basename?: readonly string[];
+    /**
+     * Match when the first two tokens (joined by a single space) of a Bash
+     * segment match one of these strings. Used for things like
+     * `aws dynamodb` where the program is `aws` but only the dynamodb subcommand
+     * should be blocked.
+     */
+    block_two_token_command?: readonly string[];
+    /** Optional redirect/help string appended to the default deny message. */
+    redirect?: string;
+    /** Override the default deny message entirely. `${blocked}` is substituted with the matched token. */
+    deny_message?: string;
+}
+export interface GuardrailManifest {
+    /** Schema version. Always `1` for now. */
+    version: 1;
+    /** Source connector name; surfaces in deny messages. */
+    name: string;
+    rules: GuardrailRule[];
+}
+export interface BlockMatch {
+    manifest: GuardrailManifest;
+    rule: GuardrailRule;
+    /** What was matched, e.g. `"psql"` or `"aws dynamodb"`. */
+    blockedToken: string;
+    /** The original full command string from `tool_input.command`. */
+    command: string;
+}
+/**
+ * Read a guardrail manifest JSON file from disk and validate its shape.
+ * Throws on parse/validation errors; the caller is responsible for fail-open
+ * behaviour in PreToolUse hooks (catch + ignore).
+ */
+export declare function loadGuardrailManifest(filePath: string): GuardrailManifest;
+/**
+ * Walk a Bash command, including `&&`/`||`/`;`/`|` segments and nested
+ * `bash -c "..."` invocations, and return the first matching block, or
+ * null if nothing matches.
+ */
+export declare function findBlockingRule(command: string, manifests: readonly GuardrailManifest[], depth?: number): BlockMatch | null;
+/** Compose the deny message — uses `rule.deny_message` if set, otherwise a default. */
+export declare function defaultDenyMessage(match: BlockMatch): string;
+//# sourceMappingURL=guardrail.d.ts.map

package/dist/toolkit/guardrail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrail.d.ts","sourceRoot":"","sources":["../../src/toolkit/guardrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,0BAA0B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,OAAO,EAAE,CAAC,CAAC;IACX,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACjB;AAID;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CASzE;AAyBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,SAAS,iBAAiB,EAAE,EACvC,KAAK,SAAI,GACR,UAAU,GAAG,IAAI,CAwCnB;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAW5D"}

package/dist/toolkit/guardrail.js

@@ -0,0 +1,166 @@
+/**
+ * guardrail — connector-side rules for blocking dangerous Bash invocations,
+ * reusable from any plugin's PreToolUse hook.
+ *
+ * This module supplies:
+ *   - The data shapes for a guardrail manifest (one JSON file per connector
+ *     under `plugin/hooks/guardrails.json`).
+ *   - A loader that reads + validates a manifest from disk.
+ *   - A matching engine extracted from db-agent-connector's db-guard hook
+ *     so every consumer (the per-connector hooks AND the hub's unified hook)
+ *     evaluates the same way.
+ *
+ * Best-effort, not a security boundary. The engine fails open on parse
+ * errors; callers are expected to handle missing/invalid manifests gracefully.
+ */
+import * as fs from "node:fs";
+const SHELLS = new Set(["bash", "sh", "zsh", "ksh", "dash"]);
+/**
+ * Read a guardrail manifest JSON file from disk and validate its shape.
+ * Throws on parse/validation errors; the caller is responsible for fail-open
+ * behaviour in PreToolUse hooks (catch + ignore).
+ */
+export function loadGuardrailManifest(filePath) {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse guardrail manifest at ${filePath}: ${err.message}`);
+    }
+    return validateManifest(parsed, filePath);
+}
+function validateManifest(value, filePath) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Guardrail manifest at ${filePath} must be a JSON object.`);
+    }
+    const obj = value;
+    if (obj["version"] !== 1) {
+        throw new Error(`Guardrail manifest at ${filePath} must have version: 1.`);
+    }
+    if (typeof obj["name"] !== "string" || obj["name"] === "") {
+        throw new Error(`Guardrail manifest at ${filePath} must have a non-empty 'name'.`);
+    }
+    if (!Array.isArray(obj["rules"])) {
+        throw new Error(`Guardrail manifest at ${filePath} must have a 'rules' array.`);
+    }
+    const rules = obj["rules"].map((r, i) => {
+        if (r === null || typeof r !== "object" || Array.isArray(r)) {
+            throw new Error(`Guardrail manifest at ${filePath}: rules[${i}] must be an object.`);
+        }
+        return r;
+    });
+    return { version: 1, name: obj["name"], rules };
+}
+/**
+ * Walk a Bash command, including `&&`/`||`/`;`/`|` segments and nested
+ * `bash -c "..."` invocations, and return the first matching block, or
+ * null if nothing matches.
+ */
+export function findBlockingRule(command, manifests, depth = 0) {
+    if (depth > 3)
+        return null;
+    const segments = splitSegments(command);
+    for (const seg of segments) {
+        const cleaned = stripOpeners(stripEnvPrefix(seg));
+        if (cleaned === "")
+            continue;
+        const tokens = tokenize(cleaned);
+        if (tokens.length === 0)
+            continue;
+        const head = basename(tokens[0] ?? "");
+        // Recurse into shell -c "..." subcommands.
+        const nested = unwrapShellDashC(tokens);
+        if (nested !== null) {
+            const inner = findBlockingRule(nested, manifests, depth + 1);
+            if (inner !== null)
+                return inner;
+            continue;
+        }
+        // Two-token prefix match (e.g., "aws dynamodb").
+        if (tokens.length >= 2) {
+            const twoToken = `${head} ${tokens[1] ?? ""}`;
+            for (const m of manifests) {
+                for (const r of m.rules) {
+                    if (r.block_two_token_command?.includes(twoToken)) {
+                        return { manifest: m, rule: r, blockedToken: twoToken, command };
+                    }
+                }
+            }
+        }
+        // First-token basename match.
+        for (const m of manifests) {
+            for (const r of m.rules) {
+                if (r.block_first_token_basename?.includes(head)) {
+                    return { manifest: m, rule: r, blockedToken: head, command };
+                }
+            }
+        }
+    }
+    return null;
+}
+/** Compose the deny message — uses `rule.deny_message` if set, otherwise a default. */
+export function defaultDenyMessage(match) {
+    if (typeof match.rule.deny_message === "string" && match.rule.deny_message !== "") {
+        return match.rule.deny_message.replace(/\$\{blocked\}/g, match.blockedToken);
+    }
+    const redirect = match.rule.redirect !== undefined && match.rule.redirect !== ""
+        ? ` ${match.rule.redirect}`
+        : "";
+    return (`${match.manifest.name} guardrail: direct \`${match.blockedToken}\` invocation blocked.` +
+        `${redirect} Do NOT bypass this guardrail by obfuscating the invocation — reformulate the intent.`);
+}
+// ── internal helpers (extracted from db-guard.mjs so every hook agrees) ──
+function splitSegments(cmd) {
+    return cmd
+        .split(/\|\||&&|;|\|/)
+        .map((s) => s.trim())
+        .filter((s) => s !== "");
+}
+function tokenize(s) {
+    return s.split(/\s+/).filter((t) => t !== "");
+}
+function basename(tok) {
+    const i = tok.lastIndexOf("/");
+    return i === -1 ? tok : tok.slice(i + 1);
+}
+function stripEnvPrefix(segment) {
+    let s = segment.trimStart();
+    if (s.startsWith("env "))
+        s = s.slice(4).trimStart();
+    while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(s)) {
+        const m = s.match(/^\S+\s*/);
+        if (m === null)
+            break;
+        s = s.slice(m[0].length);
+    }
+    return s;
+}
+function stripOpeners(segment) {
+    let s = segment.trimStart();
+    while (s.length > 0) {
+        const c = s[0];
+        if (c === "(" || c === "{" || c === "!" || c === "`") {
+            s = s.slice(1).trimStart();
+        }
+        else {
+            break;
+        }
+    }
+    return s;
+}
+function unwrapShellDashC(tokens) {
+    if (tokens.length < 3)
+        return null;
+    const shell = basename(tokens[0] ?? "");
+    if (!SHELLS.has(shell))
+        return null;
+    const ci = tokens.indexOf("-c");
+    if (ci === -1 || ci + 1 >= tokens.length)
+        return null;
+    let inner = tokens.slice(ci + 1).join(" ").trim();
+    inner = inner.replace(/^(['"])([\s\S]*)\1$/, "$2");
+    return inner;
+}
+//# sourceMappingURL=guardrail.js.map

package/dist/toolkit/guardrail.js.map

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

package/dist/toolkit/hardship/curate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Curation helpers. Cluster raw JSONL hardships into proposed MD promotions.
+ *
+ * Curation happens in two phases:
+ *
+ *   1. Cluster — deterministic, no LLM: group entries by
+ *      (connector, action, kind, normalized context key). Pure text work.
+ *   2. Promote — LLM-assisted: given clusters, propose which section of the
+ *      MD file they belong in (Auth & Tokens / Rate Limits / ...) and write
+ *      a human-readable summary. This module provides the *structure*;
+ *      the actual LLM prompting is invoked by the `/connector-curate`
+ *      slash command (which embeds prompt text that reads + invokes these
+ *      helpers via the connector CLI).
+ */
+import type { HardshipEntry } from "./record.js";
+export interface HardshipCluster {
+    signature: string;
+    connector: string;
+    action: string;
+    kind: string;
+    scope: string | null;
+    count: number;
+    first_ts: string;
+    last_ts: string;
+    sample_contexts: string[];
+    sample_resolutions: string[];
+    sessions: string[];
+}
+/**
+ * Normalize a free-form context string so minor differences (whitespace,
+ * timestamps, UUIDs) collapse into the same cluster.
+ */
+export declare function normalizeContext(raw: string): string;
+/**
+ * Cluster a flat list of entries. Stable output: clusters are sorted by
+ * count descending, then by last_ts descending.
+ */
+export declare function clusterHardships(entries: readonly HardshipEntry[]): HardshipCluster[];
+export interface CurationMarker {
+    last_curated_ts: string | null;
+    last_curated_count: number;
+}
+export declare function readCurationMarker(md: string): CurationMarker;
+export declare function writeCurationMarker(md: string, marker: CurationMarker): string;
+/** Filter entries newer than the last-curated timestamp. */
+export declare function entriesSinceLastCuration(entries: readonly HardshipEntry[], marker: CurationMarker): HardshipEntry[];
+//# sourceMappingURL=curate.d.ts.map

package/dist/toolkit/hardship/curate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"curate.d.ts","sourceRoot":"","sources":["../../../src/toolkit/hardship/curate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQpD;AAiBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,aAAa,EAAE,GAChC,eAAe,EAAE,CAiCnB;AAQD,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,CAmB7D;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAU9E;AAED,4DAA4D;AAC5D,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,MAAM,EAAE,cAAc,GACrB,aAAa,EAAE,CAGjB"}