mulmoclaude 0.1.0

package/server/workspace/sources/fetchers/rssParser.ts

@@ -0,0 +1,295 @@
+// Pure RSS 2.0 + Atom 1.0 parser.
+//
+// Uses `fast-xml-parser` for the XML-decoding plumbing (CDATA,
+// entity decoding, namespaces) and layers a feed-specific
+// normalization on top. The output shape is format-agnostic:
+// both RSS and Atom resolve into the same `ParsedFeedItem[]`.
+//
+// Pure — no I/O. Unit-testable with fixture strings.
+
+import { XMLParser } from "fast-xml-parser";
+import { isNonEmptyString, isRecord } from "../../../utils/types.js";
+
+export interface ParsedFeedItem {
+  // Best-effort stable identity from the feed itself. For RSS
+  // this is <guid>; for Atom it's <id>. Falls back to <link>
+  // when neither is present. The caller normalizes via
+  // `stableItemId(normalizedUrl)` when dedup across sources is
+  // needed, so this id is informational only.
+  feedId: string | null;
+  title: string;
+  link: string | null;
+  // RFC-822-ish date string from RSS <pubDate>, or RFC-3339
+  // from Atom <updated>/<published>. Pre-normalized to a
+  // JavaScript-parseable ISO string when possible; otherwise
+  // passed through verbatim for the consumer to handle.
+  publishedAt: string | null;
+  // Short description. RSS <description> or Atom
+  // <summary>/<content>. May contain HTML — the pipeline's
+  // summarizer step will flatten it.
+  summary: string | null;
+  // Full HTML/text body when the feed provides one separately
+  // from summary. Otherwise null.
+  content: string | null;
+}
+
+export interface ParsedFeed {
+  // "rss" or "atom" — callers rarely care but logging benefits
+  // from knowing which branch parsed.
+  kind: "rss" | "atom";
+  title: string | null;
+  items: ParsedFeedItem[];
+}
+
+// Configure the XML parser once at module load.
+// - preserveOrder=false: we access elements by name, not by order
+// - ignoreAttributes=false: Atom's <link href=...> matters
+// - cdataPropName="#cdata": CDATA content lands in a predictable
+//   key; we coalesce it with plain text content below
+// - parseTagValue/parseAttributeValue=false: keep everything as
+//   strings so weird "dates" like "2026/13/45" don't silently
+//   become NaN
+const xml = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  cdataPropName: "#cdata",
+  parseTagValue: false,
+  parseAttributeValue: false,
+  trimValues: true,
+  // Some feeds emit arrays of <item>/<entry> and some emit a
+  // single one. alwaysCreateTextNode=false + isArray callbacks
+  // below normalize both shapes to arrays.
+  isArray: (name) => name === "item" || name === "entry" || name === "link",
+});
+
+// Parse an RSS or Atom feed body. Returns null when the input
+// doesn't look like a feed we understand (wrong root element,
+// unparseable XML). The pipeline treats null the same way it
+// treats "zero new items" — logged + skipped.
+export function parseFeed(body: string): ParsedFeed | null {
+  const text = stripBom(body);
+  if (!text.trim()) return null;
+  let parsed: unknown;
+  try {
+    parsed = xml.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+
+  if (isRecord(parsed.rss)) return parseRss(parsed.rss);
+  if (isRecord(parsed.feed)) return parseAtom(parsed.feed);
+  // RDF 1.0 (RSS 1.0) uses <rdf:RDF> as the root. fast-xml-parser
+  // keeps the namespace prefix on the key by default, so check
+  // both the prefixed form and the unprefixed fallback.
+  const rdf = parsed["rdf:RDF"] ?? parsed.RDF;
+  if (isRecord(rdf)) return parseRss10(rdf);
+  return null;
+}
+
+// --- RSS 2.0 ------------------------------------------------------------
+
+function parseRss(rss: Record<string, unknown>): ParsedFeed | null {
+  const channel = rss.channel;
+  if (!isRecord(channel)) return null;
+  const rawItems = Array.isArray(channel.item) ? channel.item : [];
+  const items: ParsedFeedItem[] = [];
+  for (const raw of rawItems) {
+    if (!isRecord(raw)) continue;
+    const parsed = parseRssItem(raw);
+    if (parsed) items.push(parsed);
+  }
+  return {
+    kind: "rss",
+    title: readString(channel.title),
+    items,
+  };
+}
+
+function parseRssItem(raw: Record<string, unknown>): ParsedFeedItem | null {
+  const title = readString(raw.title);
+  // <guid> can be a plain string or `{ "#text": "...",
+  // "@_isPermaLink": "false" }` depending on attributes.
+  const guid = readString(raw.guid);
+  const link = readString(raw.link);
+  // <pubDate> is RFC 822. Convert to ISO for easier downstream
+  // comparisons; fall back to the raw value if the conversion
+  // fails (a malformed date is better than no date).
+  const publishedAt = normalizeDate(readString(raw.pubDate));
+  // <description> is the short summary. Some feeds also emit
+  // <content:encoded> for the full HTML body. fast-xml-parser
+  // keeps the namespace prefix on the key by default, so we
+  // read both `content:encoded` (prefixed, the common case)
+  // and a bare `encoded` key as a fallback for parsers that
+  // stripped the namespace.
+  // Fall back to content when <description> is absent so
+  // content-only feeds (fairly common among tech blogs) don't
+  // end up with a null summary — the summarizer intentionally
+  // drops `content` so title-only items would otherwise slip in.
+  const content = readString(raw["content:encoded"]) ?? readString(raw.encoded);
+  const summary = readString(raw.description) ?? content;
+  if (!title) return null;
+  return {
+    feedId: guid ?? link ?? null,
+    title,
+    link,
+    publishedAt,
+    summary,
+    content,
+  };
+}
+
+// --- RSS 1.0 (RDF) ------------------------------------------------------
+
+function parseRss10(rdf: Record<string, unknown>): ParsedFeed | null {
+  // RDF feeds put <item> directly under <rdf:RDF>, not under a
+  // <channel>. Items are the same shape as RSS 2.0 otherwise.
+  const rawItems = Array.isArray(rdf.item) ? rdf.item : [];
+  const items: ParsedFeedItem[] = [];
+  for (const raw of rawItems) {
+    if (!isRecord(raw)) continue;
+    const parsed = parseRssItem(raw);
+    if (parsed) items.push(parsed);
+  }
+  const channel = isRecord(rdf.channel) ? rdf.channel : null;
+  return {
+    kind: "rss",
+    title: channel ? readString(channel.title) : null,
+    items,
+  };
+}
+
+// --- Atom 1.0 -----------------------------------------------------------
+
+function parseAtom(feed: Record<string, unknown>): ParsedFeed | null {
+  const rawEntries = Array.isArray(feed.entry) ? feed.entry : [];
+  const items: ParsedFeedItem[] = [];
+  for (const raw of rawEntries) {
+    if (!isRecord(raw)) continue;
+    const parsed = parseAtomEntry(raw);
+    if (parsed) items.push(parsed);
+  }
+  return {
+    kind: "atom",
+    title: readString(feed.title),
+    items,
+  };
+}
+
+function parseAtomEntry(raw: Record<string, unknown>): ParsedFeedItem | null {
+  const title = readString(raw.title);
+  const id = readString(raw.id);
+  const link = resolveAtomLink(raw.link);
+  const published = readString(raw.published) ?? readString(raw.updated) ?? null;
+  const publishedAt = published ? normalizeDate(published) : null;
+  // Same fallback story as RSS 2.0: content-only Atom entries
+  // (e.g. GitHub-generated feeds) should still surface in the
+  // summary step rather than be silently title-only.
+  const content = readString(raw.content);
+  const summary = readString(raw.summary) ?? content;
+  if (!title) return null;
+  return {
+    feedId: id ?? link ?? null,
+    title,
+    link,
+    publishedAt,
+    summary,
+    content,
+  };
+}
+
+// Atom <link> has three shapes in the wild:
+//   1. `<link>https://x.com/</link>` — plain string body (rare but
+//      real, e.g. hand-written atom feeds)
+//   2. `<link href="..." rel="alternate"/>` — attribute-bearing
+//      element, which is the spec-canonical form
+//   3. Multiple `<link>` elements with different `rel` values, a
+//      mix of the above
+//
+// Because we set `isArray: name === "link"` on the parser, every
+// link form arrives wrapped in an array. Within the array we may
+// see plain strings (form 1) and objects with `@_href` (forms 2/3).
+//
+// Preference: rel="alternate" wins (canonical web URL). Otherwise
+// we fall back to the first candidate that has a usable href /
+// string value.
+function resolveAtomLink(raw: unknown): string | null {
+  if (typeof raw === "string") return raw;
+  const candidates = Array.isArray(raw) ? raw : [raw];
+  let fallback: string | null = null;
+  for (const candidate of candidates) {
+    const outcome = classifyAtomLinkCandidate(candidate);
+    if (outcome.kind === "alternate") return outcome.href;
+    if (outcome.kind === "fallback") fallback ??= outcome.href;
+  }
+  return fallback;
+}
+
+type AtomLinkOutcome = { kind: "alternate"; href: string } | { kind: "fallback"; href: string } | { kind: "skip" };
+
+// Inspect one candidate from Atom's `<link>` list (which may be a
+// plain string or an object carrying `@_href` / `@_rel` attrs)
+// and report whether it's a rel="alternate" winner, a usable
+// fallback, or nothing we can use.
+function classifyAtomLinkCandidate(candidate: unknown): AtomLinkOutcome {
+  if (isNonEmptyString(candidate)) {
+    // Form 1: bare `<link>url</link>`. Unattributed → fallback.
+    return { kind: "fallback", href: candidate };
+  }
+  if (!isRecord(candidate)) return { kind: "skip" };
+  const href = readString(candidate["@_href"]);
+  if (!href) return { kind: "skip" };
+  const rel = readString(candidate["@_rel"]);
+  if (rel === "alternate" || rel === null) {
+    return { kind: "alternate", href };
+  }
+  return { kind: "fallback", href };
+}
+
+// --- helpers ------------------------------------------------------------
+
+// isRecord moved to server/utils/types.ts
+
+// Extract a string from a value that might be:
+//   - a plain string
+//   - an object with `#text` (tag with attributes + body text)
+//   - an object with `#cdata` (CDATA-wrapped body)
+//   - an array (pick the first non-empty)
+// Returns null when nothing plausibly-textual is found.
+function readString(value: unknown): string | null {
+  if (isNonEmptyString(value)) return value;
+  if (typeof value === "string") return null;
+  if (isRecord(value)) return readStringFromRecord(value);
+  if (Array.isArray(value)) return readStringFromArray(value);
+  return null;
+}
+
+function readStringFromRecord(record: Record<string, unknown>): string | null {
+  const text = record["#text"];
+  if (isNonEmptyString(text)) return text;
+  const cdata = record["#cdata"];
+  if (isNonEmptyString(cdata)) return cdata;
+  return null;
+}
+
+function readStringFromArray(array: readonly unknown[]): string | null {
+  for (const entry of array) {
+    const resolved = readString(entry);
+    if (resolved !== null) return resolved;
+  }
+  return null;
+}
+
+function stripBom(text: string): string {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+// Convert a date string into ISO 8601 if possible; otherwise
+// return the original. We never throw — a weird but non-empty
+// date is more useful to the pipeline than a null.
+function normalizeDate(raw: string | null): string | null {
+  if (!raw) return null;
+  const ts = Date.parse(raw);
+  if (Number.isFinite(ts)) return new Date(ts).toISOString();
+  return raw;
+}

package/server/workspace/sources/httpFetcher.ts

@@ -0,0 +1,230 @@
+// Etiquette-respecting HTTP fetcher for server-side source
+// fetchers (RSS, GitHub API, arXiv, etc.).
+//
+// Wraps `fetch` with four things phase-1 fetchers would otherwise
+// all have to reimplement:
+//
+//   1. User-Agent: `MulmoClaude-SourceBot/1.0 (+<repo url>)` on every
+//      request, so site operators can identify and contact.
+//   2. robots.txt check: before fetching `<scheme>://<host>/<path>`,
+//      read the cached robots.txt for `<host>` and consult
+//      `isAllowedByRobots`. Disallowed paths 400-reject at the
+//      library boundary — fetcher sees `RobotsDisallowedError` and
+//      can log / skip.
+//   3. Per-host rate limit: HostRateLimiter serializes same-host
+//      requests with a `Crawl-delay`-aware minimum gap.
+//   4. Timeout: each request gets a finite AbortController so a
+//      hung server can't wedge the daily pipeline.
+//
+// The robots.txt cache itself is NOT owned by this module — it's
+// a pluggable `RobotsProvider` so tests can stub it and the real
+// cache (filesystem-backed, 24h TTL) lives elsewhere.
+//
+// Every moving part has an injectable dep so tests can drive the
+// whole flow without network or disk.
+
+import { DEFAULT_MIN_DELAY_MS, HostRateLimiter, defaultRateLimiterDeps, type RateLimiterDeps } from "./rateLimiter.js";
+import { isAllowedByRobots, parseRobots } from "./robots.js";
+import { ONE_SECOND_MS } from "../../utils/time.js";
+
+// The User-Agent value sent on every fetch. Identifies us clearly
+// enough for a site operator to find the project and contact us.
+// Update the URL if the repo ever moves.
+export const USER_AGENT = "MulmoClaude-SourceBot/1.0 (+https://github.com/receptron/mulmoclaude)";
+
+// Per-request wall-clock cap. Fetchers can still cancel earlier
+// via a passed-in AbortSignal; this is the outer safety net so a
+// hung server never holds a rate-limit slot forever.
+export const DEFAULT_FETCH_TIMEOUT_MS = 30 * ONE_SECOND_MS;
+
+// Thrown when a URL would violate the target host's robots.txt
+// policy for our User-Agent. Caught by fetchers so a single
+// disallowed source doesn't look like a generic HTTP error.
+export class RobotsDisallowedError extends Error {
+  readonly url: string;
+  constructor(url: string) {
+    super(`[sources] robots.txt disallows ${url} for our User-Agent`);
+    this.name = "RobotsDisallowedError";
+    this.url = url;
+  }
+}
+
+// How the fetcher gets robots.txt for a given host. The real
+// implementation (phase-2-ish) will read from
+// `workspace/sources/_state/robots/<host>.txt` with a 24h TTL,
+// falling back to an HTTP GET. Tests inject an in-memory map.
+//
+// Returns null to signal "no robots.txt found" (or "404-equivalent")
+// which the evaluator treats as permissive — the usual convention.
+export type RobotsProvider = (host: string) => Promise<string | null>;
+
+// Cap the number of redirect hops one fetchPolite call will follow.
+// Matches the common browser default (Firefox 20, Chrome 20) and
+// RFC 7231 recommendation. Rejects with a plain Error after the cap.
+export const MAX_REDIRECTS = 5;
+
+// Thrown when the redirect chain exceeds MAX_REDIRECTS. Caller can
+// distinguish "site is mis-configured" from "network error" and log
+// appropriately.
+export class RedirectLimitError extends Error {
+  readonly startUrl: string;
+  readonly lastUrl: string;
+  constructor(startUrl: string, lastUrl: string) {
+    super(`[sources] too many redirects (>${MAX_REDIRECTS}) starting from ${startUrl}`);
+    this.name = "RedirectLimitError";
+    this.startUrl = startUrl;
+    this.lastUrl = lastUrl;
+  }
+}
+
+export interface HttpFetcherDeps {
+  // HTTP client. Defaults to global `fetch`; tests inject a
+  // response-map function.
+  fetchImpl: typeof fetch;
+  // robots.txt source. See RobotsProvider.
+  robots: RobotsProvider;
+  // Shared rate limiter so fetchers going through the same
+  // HttpFetcher instance all serialize per-host together.
+  rateLimiter: HostRateLimiter;
+  // Rate-limiter clock / sleep — usually pass through from
+  // `rateLimiter`'s deps when constructing both.
+  rateLimiterDeps: RateLimiterDeps;
+  // Per-host crawl-delay override, looked up per request. Returns
+  // null when the fetcher should fall back to its
+  // `DEFAULT_MIN_DELAY_MS`. Normally implemented by caching the
+  // robots.txt `Crawl-delay` value per host.
+  crawlDelayMs: (host: string) => number | null;
+  // Extra abort signal the caller can provide to cancel a fetch
+  // early (e.g. pipeline shutdown). Combined with the internal
+  // timeout via any-of.
+  externalSignal?: AbortSignal;
+  // Request timeout. DEFAULT_FETCH_TIMEOUT_MS unless overridden.
+  timeoutMs: number;
+  // For tests: called exactly once with every resolved URL right
+  // before `fetchImpl` runs. Production passes a no-op.
+  onWillFetch: (url: string) => void;
+}
+
+export function defaultHttpFetcherDeps(
+  robots: RobotsProvider,
+  rateLimiter?: HostRateLimiter,
+  rateLimiterDeps: RateLimiterDeps = defaultRateLimiterDeps(),
+): HttpFetcherDeps {
+  return {
+    fetchImpl: globalThis.fetch.bind(globalThis),
+    robots,
+    rateLimiter: rateLimiter ?? new HostRateLimiter(rateLimiterDeps),
+    rateLimiterDeps,
+    crawlDelayMs: () => null,
+    timeoutMs: DEFAULT_FETCH_TIMEOUT_MS,
+    onWillFetch: () => {},
+  };
+}
+
+// Fetch a URL politely. Resolves with the Response object (caller
+// decides whether to `.text()` / `.json()`); rejects with
+// `RobotsDisallowedError` when robots says no, `RedirectLimitError`
+// when the redirect chain exceeds MAX_REDIRECTS, `DOMException`
+// (AbortError) when the external signal or the internal timeout
+// fires, or whatever `fetchImpl` throws otherwise.
+//
+// Redirects are followed manually so every hop goes through the
+// same robots-check + per-host rate-limit. Auto-follow (`fetch`'s
+// default) would let a 302 to another host or another path bypass
+// those checks entirely — a silent politeness violation.
+export async function fetchPolite(rawUrl: string, deps: HttpFetcherDeps): Promise<Response> {
+  let currentUrl = rawUrl;
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const response = await fetchSingleHop(currentUrl, deps);
+    const nextUrl = redirectTarget(response, currentUrl);
+    if (nextUrl === null) return response;
+    currentUrl = nextUrl;
+  }
+  throw new RedirectLimitError(rawUrl, currentUrl);
+}
+
+// A single hop: validate scheme, check robots.txt, run the fetch
+// under the per-host rate limit. Returns whatever Response the
+// server produced (including 3xx with a Location header — the
+// caller in fetchPolite inspects and may re-enter).
+async function fetchSingleHop(rawUrl: string, deps: HttpFetcherDeps): Promise<Response> {
+  const url = new URL(rawUrl);
+  // Only http(s) reach the fetch — file://, data:, mailto: would
+  // never be legitimate source URLs and robots.txt doesn't cover
+  // them. Reject at the boundary.
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`[sources] fetchPolite: refusing non-http(s) URL ${rawUrl}`);
+  }
+  const host = url.host.toLowerCase();
+
+  const robotsText = await deps.robots(host);
+  if (robotsText !== null) {
+    const parsed = parseRobots(robotsText);
+    const pathAndQuery = url.pathname + url.search;
+    if (!isAllowedByRobots(parsed, USER_AGENT, pathAndQuery)) {
+      throw new RobotsDisallowedError(rawUrl);
+    }
+  }
+
+  const minDelay = deps.crawlDelayMs(host) ?? DEFAULT_MIN_DELAY_MS;
+  return deps.rateLimiter.run(host, () => fetchWithTimeout(rawUrl, deps), minDelay);
+}
+
+// Return the absolute URL the caller should hop to next, or null
+// when the response is not a redirect we should follow. A 3xx
+// status without a Location header is treated as terminal — the
+// server sent something unusual and it's safer to surface the
+// response than to guess.
+function redirectTarget(response: Response, currentUrl: string): string | null {
+  if (response.status < 300 || response.status >= 400) return null;
+  // 304 Not Modified is a cache response, not a redirect.
+  if (response.status === 304) return null;
+  const location = response.headers.get("location");
+  if (!location) return null;
+  try {
+    return new URL(location, currentUrl).toString();
+  } catch {
+    // Malformed Location — give up so the caller sees the 3xx
+    // instead of a recursive parse crash.
+    return null;
+  }
+}
+
+async function fetchWithTimeout(rawUrl: string, deps: HttpFetcherDeps): Promise<Response> {
+  // Combine the caller's signal with an internal timeout. Each
+  // fetch gets its own AbortController so a slow request doesn't
+  // affect the next caller.
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => {
+    controller.abort(new DOMException(`[sources] fetch timed out after ${deps.timeoutMs}ms`, "TimeoutError"));
+  }, deps.timeoutMs);
+
+  const external = deps.externalSignal;
+  let externalUnsub: (() => void) | null = null;
+  if (external) {
+    if (external.aborted) {
+      clearTimeout(timeoutHandle);
+      throw (external as AbortSignal & { reason?: unknown }).reason ?? new DOMException("Aborted", "AbortError");
+    }
+    const onAbort = () => {
+      controller.abort((external as AbortSignal & { reason?: unknown }).reason);
+    };
+    external.addEventListener("abort", onAbort, { once: true });
+    externalUnsub = () => external.removeEventListener("abort", onAbort);
+  }
+
+  deps.onWillFetch(rawUrl);
+  try {
+    return await deps.fetchImpl(rawUrl, {
+      headers: { "User-Agent": USER_AGENT },
+      signal: controller.signal,
+      // Redirects are followed manually in `fetchPolite` so each
+      // hop re-runs robots.txt + per-host rate-limit. Auto-follow
+      // would skip those checks on the second hop.
+      redirect: "manual",
+    });
+  } finally {
+    clearTimeout(timeoutHandle);
+    externalUnsub?.();
+  }
+}

package/server/workspace/sources/interests.ts

@@ -0,0 +1,120 @@
+// User interest profile for news notification filtering (#466).
+//
+// Loaded from `config/interests.json`. Claude populates this file
+// during conversation when it detects user interest in a topic.
+// The pipeline's notify phase uses it to score and filter articles.
+
+import fs from "fs";
+import path from "path";
+import { workspacePath } from "../paths.js";
+import { log } from "../../system/logger/index.js";
+import type { SourceItem } from "./types.js";
+import type { CategorySlug } from "./taxonomy.js";
+import { isCategorySlug } from "./taxonomy.js";
+import { isNonEmptyString, isRecord } from "../../utils/types.js";
+
+// ── Types ───────────────────────────────────────────────────────
+
+export interface InterestsProfile {
+  keywords: string[];
+  categories: CategorySlug[];
+  minRelevance: number;
+  maxNotificationsPerRun: number;
+}
+
+// ── Constants ───────────────────────────────────────────────────
+
+const CONFIG_FILE = "config/interests.json";
+const DEFAULT_MIN_RELEVANCE = 0.5;
+const DEFAULT_MAX_NOTIFICATIONS = 5;
+
+// Scoring weights
+const KEYWORD_TITLE_WEIGHT = 0.4;
+const KEYWORD_SUMMARY_WEIGHT = 0.2;
+const CATEGORY_MATCH_WEIGHT = 0.3;
+const SEVERITY_CRITICAL_WEIGHT = 0.3;
+const SEVERITY_WARN_WEIGHT = 0.1;
+
+// ── Load ────────────────────────────────────────────────────────
+
+export function loadInterests(root?: string): InterestsProfile | null {
+  const base = root ?? workspacePath;
+  const filePath = path.join(base, CONFIG_FILE);
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const parsed: unknown = JSON.parse(raw);
+    return validateInterests(parsed);
+  } catch (err) {
+    log.warn("interests", "failed to load interests.json", {
+      error: String(err),
+    });
+    return null;
+  }
+}
+
+function validateInterests(raw: unknown): InterestsProfile | null {
+  if (!isRecord(raw)) return null;
+  const obj = raw as Record<string, unknown>;
+
+  // Filter out blank/whitespace-only keywords — "" matches every title
+  const keywords = Array.isArray(obj.keywords) ? obj.keywords.filter((k): k is string => isNonEmptyString(k)) : [];
+
+  const categories = Array.isArray(obj.categories) ? obj.categories.filter((c): c is CategorySlug => isCategorySlug(c)) : [];
+
+  if (keywords.length === 0 && categories.length === 0) return null;
+
+  // Clamp minRelevance to [0, 1] — values > 1 would make notifications
+  // impossible since scores are clamped to 1.0
+  const rawMin = typeof obj.minRelevance === "number" ? obj.minRelevance : DEFAULT_MIN_RELEVANCE;
+  const minRelevance = Math.max(0, Math.min(1, rawMin));
+
+  // Floor to integer, minimum 1
+  const rawMax = typeof obj.maxNotificationsPerRun === "number" ? obj.maxNotificationsPerRun : DEFAULT_MAX_NOTIFICATIONS;
+  const maxNotificationsPerRun = Math.max(1, Math.floor(rawMax));
+
+  return { keywords, categories, minRelevance, maxNotificationsPerRun };
+}
+
+// ── Scoring ─────────────────────────────────────────────────────
+
+export interface ScoredItem {
+  item: SourceItem;
+  score: number;
+}
+
+export function scoreItem(item: SourceItem, profile: InterestsProfile): number {
+  let score = 0;
+  const titleLower = item.title.toLowerCase();
+  const summaryLower = (item.summary ?? "").toLowerCase();
+
+  for (const kw of profile.keywords) {
+    const kwLower = kw.toLowerCase();
+    if (titleLower.includes(kwLower)) {
+      score += KEYWORD_TITLE_WEIGHT;
+    } else if (summaryLower.includes(kwLower)) {
+      score += KEYWORD_SUMMARY_WEIGHT;
+    }
+  }
+
+  const hasCategory = item.categories.some((c) => profile.categories.includes(c));
+  if (hasCategory) {
+    score += CATEGORY_MATCH_WEIGHT;
+  }
+
+  if (item.severity === "critical") {
+    score += SEVERITY_CRITICAL_WEIGHT;
+  } else if (item.severity === "warn") {
+    score += SEVERITY_WARN_WEIGHT;
+  }
+
+  return Math.min(score, 1.0);
+}
+
+export function scoreAndFilter(items: readonly SourceItem[], profile: InterestsProfile): ScoredItem[] {
+  return items
+    .map((item) => ({ item, score: scoreItem(item, profile) }))
+    .filter((s) => s.score >= profile.minRelevance)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, profile.maxNotificationsPerRun);
+}