@ozzylabs/feedradar 0.1.0

package/dist/core/feeds/rss.js

@@ -0,0 +1,222 @@
+import { XMLParser } from "fast-xml-parser";
+import { ItemSchema } from "../../schemas/index.js";
+import { deriveItemId, deriveStableKey } from "./derive-id.js";
+const USER_AGENT = "feedradar/0.0.0 (+https://github.com/ozzy-labs/feedradar)";
+/** Coerce an `fast-xml-parser` text-or-object to a plain string. */
+function asString(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value === "string")
+        return value.trim() || undefined;
+    if (typeof value === "object") {
+        const obj = value;
+        const text = obj["#text"];
+        if (typeof text === "string")
+            return text.trim() || undefined;
+    }
+    return undefined;
+}
+/** Atom `<link rel="alternate" href="…"/>` resolution. */
+function pickAtomLink(link) {
+    if (!link)
+        return undefined;
+    if (typeof link === "string")
+        return link;
+    if (Array.isArray(link)) {
+        const alt = link.find((l) => (l["@_rel"] ?? "alternate") === "alternate");
+        return alt?.["@_href"];
+    }
+    return link["@_href"];
+}
+/** RSS `<link>` can be a simple URL or `{ "#text": "...", "@_href": "..." }`. */
+function pickRssLink(link) {
+    if (!link)
+        return undefined;
+    if (typeof link === "string")
+        return link.trim() || undefined;
+    if (typeof link === "object") {
+        return link["@_href"] ?? asString(link);
+    }
+    return undefined;
+}
+/** Convert RSS `pubDate` / Atom `published` into ISO 8601 string. */
+function toIsoDate(value) {
+    if (!value)
+        return undefined;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return undefined;
+    return date.toISOString();
+}
+/**
+ * Derive a stable, filesystem- and CLI-friendly id for an RSS/Atom entry.
+ *
+ * Delegates the actual format (`<title-slug>-<8 hex of sha256(stableKey)>`)
+ * and the publisher-id-first fallback ladder (guid > url > sha1(title|pub))
+ * to the shared helpers in `./derive-id.ts`, which all feed adapters use so
+ * that ids stay byte-stable across adapter kinds (see ADR-0002).
+ *
+ * The publisher's original guid is preserved in `Item.raw` (the full
+ * upstream entry is stored), so no information is lost. See issue #23.
+ */
+function deriveId(guid, url, title, pub) {
+    const stableKey = deriveStableKey({
+        publisherId: guid,
+        url,
+        fallbackHashInputs: [title, pub],
+    });
+    return deriveItemId(title, stableKey);
+}
+/** Normalize one RSS 2.0 `<item>` into our `Item` shape. */
+function parseRssItem(raw, source, fetchedAt) {
+    const title = asString(raw.title) ?? "";
+    const url = pickRssLink(raw.link);
+    if (!url)
+        return null;
+    const summary = asString(raw.description);
+    const publishedAt = toIsoDate(raw.pubDate ?? raw["dc:date"]);
+    const guid = asString(raw.guid);
+    const id = deriveId(guid, url, title, raw.pubDate);
+    return validateItem({
+        id,
+        sourceId: source.id,
+        title,
+        url,
+        summary,
+        publishedAt,
+        fetchedAt,
+        raw,
+    });
+}
+/** Normalize one Atom `<entry>` into our `Item` shape. */
+function parseAtomEntry(raw, source, fetchedAt) {
+    const title = asString(raw.title) ?? "";
+    const url = pickAtomLink(raw.link);
+    if (!url)
+        return null;
+    const summary = asString(raw.summary) ?? asString(raw.content);
+    const publishedAt = toIsoDate(raw.published ?? raw.updated);
+    const id = deriveId(raw.id, url, title, raw.published ?? raw.updated);
+    return validateItem({
+        id,
+        sourceId: source.id,
+        title,
+        url,
+        summary,
+        publishedAt,
+        fetchedAt,
+        raw,
+    });
+}
+function validateItem(candidate) {
+    const result = ItemSchema.safeParse(candidate);
+    // Items that fail validation (malformed URL etc.) are dropped silently — the
+    // alternative is failing the whole feed for one bad entry, which surprises
+    // users running large feeds where one broken entry is common.
+    return result.success ? result.data : null;
+}
+/**
+ * Parse an RSS 2.0 or Atom XML document into validated `Item[]`.
+ *
+ * `fast-xml-parser` is intentionally configured to keep attribute prefixes
+ * (`@_href`) and skip CDATA stripping so we can route through the same
+ * normalizer regardless of which dialect we are reading.
+ */
+export function parseFeedXml(xml, source, fetchedAt) {
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: "@_",
+        textNodeName: "#text",
+        trimValues: true,
+        parseTagValue: false,
+        parseAttributeValue: false,
+    });
+    let parsed;
+    try {
+        parsed = parser.parse(xml);
+    }
+    catch (e) {
+        throw new Error(`rss adapter: failed to parse XML: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // RSS 2.0 path
+    if (parsed.rss?.channel?.item) {
+        const items = Array.isArray(parsed.rss.channel.item)
+            ? parsed.rss.channel.item
+            : [parsed.rss.channel.item];
+        return items
+            .map((entry) => parseRssItem(entry, source, fetchedAt))
+            .filter((i) => i !== null);
+    }
+    // Atom path
+    if (parsed.feed?.entry) {
+        const entries = Array.isArray(parsed.feed.entry) ? parsed.feed.entry : [parsed.feed.entry];
+        return entries
+            .map((entry) => parseAtomEntry(entry, source, fetchedAt))
+            .filter((i) => i !== null);
+    }
+    // No recognized envelope. Return [] rather than throw — empty feeds are a
+    // valid response and we should not poison the state with an error.
+    return [];
+}
+/**
+ * Issue an HTTP GET with conditional headers, honoring previously stored
+ * `ETag` / `Last-Modified` so well-behaved servers can reply 304 and let us
+ * skip parsing work.
+ */
+async function fetchFeed(url, fetchImpl, options = {}) {
+    const headers = {
+        accept: "application/rss+xml, application/atom+xml, application/xml;q=0.9, */*;q=0.5",
+        "user-agent": USER_AGENT,
+    };
+    if (options.etag)
+        headers["if-none-match"] = options.etag;
+    if (options.lastModified)
+        headers["if-modified-since"] = options.lastModified;
+    const response = await fetchImpl(url, { headers, signal: options.signal });
+    const etag = response.headers.get("etag");
+    const lastModified = response.headers.get("last-modified");
+    if (response.status === 304) {
+        return { status: 304, body: "", etag, lastModified };
+    }
+    if (response.status < 200 || response.status >= 300) {
+        throw new Error(`rss adapter: HTTP ${response.status} from ${url}`);
+    }
+    const body = await response.text();
+    return { status: response.status, body, etag, lastModified };
+}
+export const rssAdapter = {
+    kind: "rss",
+    fetch: async (source, options = {}) => {
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            throw new Error("rss adapter: no fetch implementation available (Node 22+ required)");
+        }
+        const previous = options.state;
+        const fetchedAt = new Date().toISOString();
+        const response = await fetchFeed(source.url, fetchImpl, {
+            etag: previous?.lastEtag,
+            // We do not currently persist Last-Modified separately; ETag suffices
+            // for the well-behaved feed publishers we target. If a publisher only
+            // exposes Last-Modified we will revisit (issue #13 follow-up).
+        });
+        if (response.status === 304) {
+            return {
+                items: [],
+                notModified: true,
+                state: {
+                    lastFetchedAt: fetchedAt,
+                    lastEtag: response.etag ?? previous?.lastEtag,
+                },
+            };
+        }
+        const items = parseFeedXml(response.body, source, fetchedAt);
+        return {
+            items,
+            state: {
+                lastFetchedAt: fetchedAt,
+                lastEtag: response.etag ?? previous?.lastEtag,
+            },
+        };
+    },
+};
+//# sourceMappingURL=rss.js.map

package/dist/core/feeds/rss.js.map

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

package/dist/core/feeds/types.d.ts

@@ -0,0 +1,45 @@
+import type { Item, Source, SourceState } from "../../schemas/index.js";
+/**
+ * Minimal `fetch` signature an adapter needs.
+ *
+ * Defined narrowly so tests can inject a stub without bringing the entire
+ * `globalThis.fetch` type surface along. Node 22+'s built-in fetch satisfies
+ * this shape.
+ */
+export type FetchLike = (input: string | URL, init?: {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}>;
+/** Result of a single adapter fetch — the items plus the next state to persist. */
+export interface FeedFetchResult {
+    items: Item[];
+    /**
+     * Patch to merge into the source's `SourceState`. Adapters return only the
+     * fields they want to update so the watcher can decide how to merge with the
+     * existing on-disk state (e.g. unioning `lastSeenIds`).
+     */
+    state: Partial<SourceState>;
+    /**
+     * `true` when the upstream returned 304 Not Modified (or an equivalent
+     * unchanged response). Watcher uses this to short-circuit item processing
+     * while still bumping `lastFetchedAt`.
+     */
+    notModified?: boolean;
+}
+export interface FeedAdapterOptions {
+    /** Caller-supplied fetch (defaults to global fetch). Injected by tests. */
+    fetch?: FetchLike;
+    /** Previous state for this source (`state/<id>.yaml`). */
+    state?: SourceState;
+}
+export interface FeedAdapter {
+    kind: Source["kind"];
+    fetch: (source: Source, options?: FeedAdapterOptions) => Promise<FeedFetchResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/feeds/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/feeds/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,MAAM,GAAG,GAAG,EACnB,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAC9D,OAAO,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC9C,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB,CAAC,CAAC;AAEH,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5B;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACrB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CACnF"}

package/dist/core/feeds/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/feeds/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/feeds/types.ts"],"names":[],"mappings":""}

package/dist/core/filter.d.ts

@@ -0,0 +1,25 @@
+import type { Item, Source, SourceFilters } from "../schemas/index.js";
+/**
+ * Apply ADR-0006 filter semantics to a single item.
+ *
+ * Evaluation order:
+ *   1. Concatenate matchFields into a haystack.
+ *   2. If `caseSensitive` is false, lowercase haystack and keywords (word /
+ *      substring modes). For regex mode, the `i` flag is used instead of
+ *      lowercasing the pattern source.
+ *   3. If any `excludeKeywords` hits → reject (exclude wins over include).
+ *   4. If any `keywords` hits → accept, recording the hits in `matchedKeywords`.
+ *   5. Otherwise → reject.
+ *
+ * Returns the (possibly mutated) item annotated with `matchedKeywords` when
+ * accepted, or null when filtered out.
+ */
+export declare function evaluateFilter(item: Item, filters: SourceFilters): Item | null;
+/**
+ * Apply a source's filter to a batch of items, returning only those that pass.
+ *
+ * Each returned item carries `matchedKeywords` populated from the include hits,
+ * so downstream `items` writers can persist the evidence for later inspection.
+ */
+export declare function filterItems(items: Item[], source: Source): Item[];
+//# sourceMappingURL=filter.d.ts.map

package/dist/core/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/core/filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAyB,MAAM,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAiE9F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAiC9E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,CAQjE"}

package/dist/core/filter.js

@@ -0,0 +1,123 @@
+/**
+ * Evaluate a single keyword against a haystack per the configured match mode.
+ *
+ * - `word`: whole-word match anchored on regex `\b` boundaries (keyword auto-escaped).
+ * - `substring`: plain `indexOf`-style match.
+ * - `regex`: treat the keyword as a JavaScript regular expression source. The
+ *   `i` flag is added when `caseInsensitive` is true so character classes such
+ *   as `\d` / `\W` retain their meaning (lowercasing the pattern source would
+ *   silently corrupt them).
+ *
+ * For `word` and `substring` modes the caller is expected to have lowercased
+ * both haystack and keyword when matching is case-insensitive.
+ */
+function matchKeyword(haystack, keyword, mode, caseInsensitive) {
+    if (keyword.length === 0)
+        return false;
+    if (mode === "substring") {
+        return haystack.includes(keyword);
+    }
+    if (mode === "word") {
+        // Escape regex metachars in the user-supplied keyword so `word` mode is
+        // never interpreted as a pattern (ADR-0006: word mode is literal).
+        const escaped = keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const re = new RegExp(`\\b${escaped}\\b`);
+        return re.test(haystack);
+    }
+    // regex mode: compile the keyword as-is. Invalid regexes throw RegExp errors,
+    // which we let propagate so the caller surfaces a clear validation failure.
+    // Use the `i` flag for case-insensitive runs rather than lowercasing the
+    // pattern source — `\d` / `\D` / `\w` / `\W` flip meaning when lowercased,
+    // which would silently break user patterns.
+    const re = new RegExp(keyword, caseInsensitive ? "i" : "");
+    return re.test(haystack);
+}
+/**
+ * Concatenate the configured `matchFields` of an item into a single search
+ * haystack. Fields that the item does not provide (`body` / `tags` for RSS,
+ * etc.) are silently skipped, per ADR-0002's "adapters skip unavailable fields"
+ * rule. Joining with newline keeps `\b` word boundaries from accidentally
+ * merging tokens across fields (e.g. title ending in "Claude" + summary
+ * starting with "Code" should not match `\bClaude Code\b`).
+ */
+function buildHaystack(item, fields) {
+    const parts = [];
+    for (const field of fields) {
+        if (field === "title") {
+            parts.push(item.title);
+        }
+        else if (field === "summary") {
+            if (item.summary)
+                parts.push(item.summary);
+        }
+        else if (field === "body" || field === "tags") {
+            // RSS adapter does not surface body / tags structurally; the schema does
+            // not model them either. Silently skip rather than throw so a single
+            // filter config can be reused across adapter kinds (ADR-0006).
+        }
+    }
+    return parts.join("\n");
+}
+/**
+ * Apply ADR-0006 filter semantics to a single item.
+ *
+ * Evaluation order:
+ *   1. Concatenate matchFields into a haystack.
+ *   2. If `caseSensitive` is false, lowercase haystack and keywords (word /
+ *      substring modes). For regex mode, the `i` flag is used instead of
+ *      lowercasing the pattern source.
+ *   3. If any `excludeKeywords` hits → reject (exclude wins over include).
+ *   4. If any `keywords` hits → accept, recording the hits in `matchedKeywords`.
+ *   5. Otherwise → reject.
+ *
+ * Returns the (possibly mutated) item annotated with `matchedKeywords` when
+ * accepted, or null when filtered out.
+ */
+export function evaluateFilter(item, filters) {
+    const haystackRaw = buildHaystack(item, filters.matchFields);
+    const isRegex = filters.matchMode === "regex";
+    const caseInsensitive = !filters.caseSensitive;
+    // For regex mode the haystack is not lowercased — we rely on the `i` flag
+    // applied to the compiled pattern (see matchKeyword). For word / substring
+    // modes we lowercase both haystack and keywords up front.
+    const haystack = caseInsensitive && !isRegex ? haystackRaw.toLowerCase() : haystackRaw;
+    const normalizeKeyword = (s) => (caseInsensitive && !isRegex ? s.toLowerCase() : s);
+    // Exclude has priority over include (ADR-0006 §評価順序 step 3).
+    for (const kw of filters.excludeKeywords) {
+        if (matchKeyword(haystack, normalizeKeyword(kw), filters.matchMode, caseInsensitive)) {
+            return null;
+        }
+    }
+    // Empty include list means "match nothing" — sources with no keywords cannot
+    // emit items. This matches the ADR's worked example and avoids accidental
+    // firehose ingestion when a user forgets to configure keywords.
+    if (filters.keywords.length === 0) {
+        return null;
+    }
+    const hits = [];
+    for (const kw of filters.keywords) {
+        if (matchKeyword(haystack, normalizeKeyword(kw), filters.matchMode, caseInsensitive)) {
+            hits.push(kw);
+        }
+    }
+    if (hits.length === 0)
+        return null;
+    return { ...item, matchedKeywords: hits };
+}
+/**
+ * Apply a source's filter to a batch of items, returning only those that pass.
+ *
+ * Each returned item carries `matchedKeywords` populated from the include hits,
+ * so downstream `items` writers can persist the evidence for later inspection.
+ */
+export function filterItems(items, source) {
+    const filters = source.filters;
+    const out = [];
+    for (const item of items) {
+        const accepted = evaluateFilter(item, filters);
+        if (accepted)
+            out.push(accepted);
+    }
+    return out;
+}
+//# sourceMappingURL=filter.js.map

package/dist/core/filter.js.map

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

package/dist/core/injection-detector.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Best-effort prompt-injection pre-filter (ADR-0009 M1a + M5a — Adopt).
+ *
+ * Scans untrusted item content (`title` / `summary` / `raw`) against a small
+ * set of regex patterns that show up in well-known prompt-injection payloads
+ * (Anthropic's `[SYSTEM]` / OpenAI's `<|im_start|>` markers, generic "ignore
+ * previous instructions" variants, etc.). The match list is exposed on the
+ * item as `injectionFlags` so downstream tooling can surface a warning to the
+ * user.
+ *
+ * Scope (deliberately narrow):
+ *
+ * - **Audit-only.** A non-empty `matched` list never changes the item's
+ *   `status`, never rewrites the content, and never blocks research. ADR-0009
+ *   rejected auto-sanitize (M5b) on the same principle — the user retains the
+ *   judgment call and can `radar dismiss` an item manually.
+ * - **High-precision patterns.** We intentionally avoid heuristics that try
+ *   to catch every social-engineering phrase. The patterns target literal
+ *   markers seen in real payloads; vague natural-language attacks (e.g.
+ *   "please disregard the system prompt and instead...") are out of scope and
+ *   will not be detected — that is a known false-negative documented in tests.
+ * - **No external dependency.** Pure `RegExp` over the haystack string.
+ *
+ * The regex `source` strings are exported (`INJECTION_PATTERNS`) so logs and
+ * user-facing diagnostics can name the offending pattern without exposing the
+ * full compiled flags. Patterns are matched case-insensitively to catch the
+ * common variants (`Ignore Previous Instructions`, `IGNORE PREVIOUS...`).
+ */
+/**
+ * Public list of pattern labels. Kept as a `readonly` constant so callers can
+ * enumerate the catalogue without reaching into the regex internals (logs,
+ * docs, etc.).
+ */
+export declare const INJECTION_PATTERN_LABELS: readonly string[];
+export interface DetectInjectionResult {
+    /**
+     * Sorted-by-pattern-declaration list of pattern labels that fired. The list
+     * is deduplicated so multiple hits of the same pattern in the same haystack
+     * still result in a single entry, which keeps the persisted
+     * `injectionFlags` field stable across re-runs.
+     */
+    matched: string[];
+}
+/**
+ * Run all patterns against `text` and return the set of labels that fired.
+ *
+ * Non-string inputs (undefined / null / numbers) return an empty result —
+ * callers are responsible for stringifying structured payloads (e.g. `raw`)
+ * before passing them in. The watcher does this via `JSON.stringify` so
+ * embedded strings inside structured payloads are still scanned.
+ *
+ * Empty / whitespace-only input returns an empty result without touching any
+ * regex, both as a fast-path and to avoid accidental matches on weird empty
+ * patterns down the line.
+ */
+export declare function detectInjection(text: string): DetectInjectionResult;
+//# sourceMappingURL=injection-detector.d.ts.map

package/dist/core/injection-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"injection-detector.d.ts","sourceRoot":"","sources":["../../src/core/injection-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAiEH;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAAiC,CAAC;AAExF,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CAWnE"}

package/dist/core/injection-detector.js

@@ -0,0 +1,109 @@
+/**
+ * Best-effort prompt-injection pre-filter (ADR-0009 M1a + M5a — Adopt).
+ *
+ * Scans untrusted item content (`title` / `summary` / `raw`) against a small
+ * set of regex patterns that show up in well-known prompt-injection payloads
+ * (Anthropic's `[SYSTEM]` / OpenAI's `<|im_start|>` markers, generic "ignore
+ * previous instructions" variants, etc.). The match list is exposed on the
+ * item as `injectionFlags` so downstream tooling can surface a warning to the
+ * user.
+ *
+ * Scope (deliberately narrow):
+ *
+ * - **Audit-only.** A non-empty `matched` list never changes the item's
+ *   `status`, never rewrites the content, and never blocks research. ADR-0009
+ *   rejected auto-sanitize (M5b) on the same principle — the user retains the
+ *   judgment call and can `radar dismiss` an item manually.
+ * - **High-precision patterns.** We intentionally avoid heuristics that try
+ *   to catch every social-engineering phrase. The patterns target literal
+ *   markers seen in real payloads; vague natural-language attacks (e.g.
+ *   "please disregard the system prompt and instead...") are out of scope and
+ *   will not be detected — that is a known false-negative documented in tests.
+ * - **No external dependency.** Pure `RegExp` over the haystack string.
+ *
+ * The regex `source` strings are exported (`INJECTION_PATTERNS`) so logs and
+ * user-facing diagnostics can name the offending pattern without exposing the
+ * full compiled flags. Patterns are matched case-insensitively to catch the
+ * common variants (`Ignore Previous Instructions`, `IGNORE PREVIOUS...`).
+ */
+/**
+ * Pattern catalogue. The `i` flag is intentional — all known payloads in the
+ * wild ignore case (`Ignore Previous Instructions` / `IGNORE PREVIOUS...`).
+ *
+ * Coverage (8 patterns, satisfies acceptance criterion 1: "≥ 6 patterns"):
+ *
+ * 1. `[SYSTEM]` literal — Anthropic-style fake system tag
+ * 2. `<|im_start|>` / `<|im_end|>` — OpenAI ChatML special tokens
+ * 3. `Ignore (the )?previous (instructions|prompt|directives)` — classic jailbreak preamble
+ * 4. `Disregard (the )?(above|previous|prior)` — paraphrase of (3)
+ * 5. `SYSTEM OVERRIDE` / `SYSTEM PROMPT OVERRIDE` — escalation marker
+ * 6. `You are now ...` style role-reassignment headers (constrained to avoid
+ *    matching benign prose; requires uppercase first word + "now" + verb)
+ * 7. `BEGIN (NEW )?INSTRUCTIONS?` / `END (NEW )?INSTRUCTIONS?` — fenced-prompt markers
+ * 8. `<\|endoftext\|>` — GPT-family special token leakage marker
+ */
+const PATTERNS = [
+    {
+        label: "system-tag",
+        re: /\[SYSTEM\]/i,
+    },
+    {
+        label: "chatml-token",
+        re: /<\|im_(start|end)\|>/i,
+    },
+    {
+        label: "ignore-previous",
+        re: /\bignore\s+(the\s+)?(previous|prior|above|all\s+previous)\s+(instructions?|prompts?|directives?|messages?|rules?)/i,
+    },
+    {
+        label: "disregard-above",
+        re: /\bdisregard\s+(the\s+)?(above|previous|prior|all\s+(previous|prior))/i,
+    },
+    {
+        label: "system-override",
+        re: /\bsystem(\s+prompt)?\s+override\b/i,
+    },
+    {
+        label: "role-reassignment",
+        re: /\byou\s+are\s+now\s+(a\s+|an\s+|the\s+)?(?:[A-Za-z][\w-]*\s+)?(assistant|ai|bot|agent|chatbot|system)\b/i,
+    },
+    {
+        label: "instruction-fence",
+        re: /\b(begin|end)\s+(new\s+)?instructions?\b/i,
+    },
+    {
+        label: "endoftext-token",
+        re: /<\|endoftext\|>/i,
+    },
+];
+/**
+ * Public list of pattern labels. Kept as a `readonly` constant so callers can
+ * enumerate the catalogue without reaching into the regex internals (logs,
+ * docs, etc.).
+ */
+export const INJECTION_PATTERN_LABELS = PATTERNS.map((p) => p.label);
+/**
+ * Run all patterns against `text` and return the set of labels that fired.
+ *
+ * Non-string inputs (undefined / null / numbers) return an empty result —
+ * callers are responsible for stringifying structured payloads (e.g. `raw`)
+ * before passing them in. The watcher does this via `JSON.stringify` so
+ * embedded strings inside structured payloads are still scanned.
+ *
+ * Empty / whitespace-only input returns an empty result without touching any
+ * regex, both as a fast-path and to avoid accidental matches on weird empty
+ * patterns down the line.
+ */
+export function detectInjection(text) {
+    if (typeof text !== "string" || text.length === 0) {
+        return { matched: [] };
+    }
+    const matched = [];
+    for (const { label, re } of PATTERNS) {
+        if (re.test(text)) {
+            matched.push(label);
+        }
+    }
+    return { matched };
+}
+//# sourceMappingURL=injection-detector.js.map

package/dist/core/injection-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injection-detector.js","sourceRoot":"","sources":["../../src/core/injection-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAcH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,QAAQ,GAAuB;IACnC;QACE,KAAK,EAAE,YAAY;QACnB,EAAE,EAAE,aAAa;KAClB;IACD;QACE,KAAK,EAAE,cAAc;QACrB,EAAE,EAAE,uBAAuB;KAC5B;IACD;QACE,KAAK,EAAE,iBAAiB;QACxB,EAAE,EAAE,oHAAoH;KACzH;IACD;QACE,KAAK,EAAE,iBAAiB;QACxB,EAAE,EAAE,uEAAuE;KAC5E;IACD;QACE,KAAK,EAAE,iBAAiB;QACxB,EAAE,EAAE,oCAAoC;KACzC;IACD;QACE,KAAK,EAAE,mBAAmB;QAC1B,EAAE,EAAE,0GAA0G;KAC/G;IACD;QACE,KAAK,EAAE,mBAAmB;QAC1B,EAAE,EAAE,2CAA2C;KAChD;IACD;QACE,KAAK,EAAE,iBAAiB;QACxB,EAAE,EAAE,kBAAkB;KACvB;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAsB,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAYxF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACzB,CAAC;IACD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,QAAQ,EAAE,CAAC;QACrC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAClB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC"}

package/dist/core/items.d.ts

@@ -0,0 +1,20 @@
+import type { Item } from "../schemas/index.js";
+/**
+ * Load all items under `items/<sourceId>/` and return them parsed + validated.
+ *
+ * Malformed files surface as thrown errors with the offending filename so
+ * tooling can pinpoint the issue. Callers that want a fault-tolerant scan
+ * should wrap the call in try/catch per file.
+ */
+export declare function loadItems(itemsDir: string, sourceId?: string): Promise<Item[]>;
+/**
+ * Persist items as YAML files under `items/<sourceId>/<itemId>.yaml`.
+ *
+ * Existing files for the same id are overwritten — callers are responsible
+ * for de-duplication via the `state.lastSeenIds` cursor before invoking this.
+ * The watcher uses this only for newly-detected items, so the overwrite path
+ * is effectively unreachable in normal operation; we still leave it permissive
+ * to keep the function idempotent under retry.
+ */
+export declare function saveItems(itemsDir: string, items: Item[]): Promise<void>;
+//# sourceMappingURL=items.d.ts.map

package/dist/core/items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"items.d.ts","sourceRoot":"","sources":["../../src/core/items.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AA+ChD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CA6BpF;AAED;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ9E"}