@mulmoclaude/core 0.2.9 → 0.2.10

package/dist/feeds/ingestTypes.d.ts

@@ -0,0 +1,57 @@
+import { CollectionIngest, INGEST_KINDS, FEED_SCHEDULES, IngestKind, FeedSchedule } from '../collection/index.js';
+export declare const AGENT_INGEST_KIND: "agent";
+export type AgentIngestKind = typeof AGENT_INGEST_KIND;
+export { INGEST_KINDS, FEED_SCHEDULES, type IngestKind, type FeedSchedule };
+export declare function isFeedSchedule(value: unknown): value is FeedSchedule;
+/** Default cap on stored records per feed when `ingest.maxItems` is
+ *  omitted. Keeps high-volume feeds (news / podcasts) bounded. */
+export declare const DEFAULT_FEED_MAX_ITEMS = 100;
+/** Declarative field map: target collection field name → source path
+ *  into the raw item (dot/bracket path, e.g. `"title"` or
+ *  `"data.name"`). */
+export type IngestFieldMap = Record<string, string>;
+/** Declarative retrieval (`rss`/`atom`/`http-json`): the host fetches `url`
+ *  and projects each item through `map`. The canonical schema (in
+ *  `../collection`) only promises the minimal `CollectionIngest`; this
+ *  feeds-only subtype narrows those + adds the retrieval fields the engine
+ *  needs. */
+export interface DeclarativeIngestSpec extends CollectionIngest {
+    /** Which declarative retriever handles this feed. */
+    kind: IngestKind;
+    /** Endpoint to fetch (http/https). */
+    url: string;
+    /** Refresh cadence. */
+    schedule: FeedSchedule;
+    /** `http-json` only: dot/bracket path to the array of items in the
+     *  response (e.g. `"hourly[]"` or `"data.results[]"`). Ignored for
+     *  `rss`/`atom`, which yield items natively. */
+    itemsAt?: string;
+    /** target field → source path. Projects each raw item into a record
+     *  whose keys match the schema's `fields`. */
+    map: IngestFieldMap;
+    /** Optional source path used to derive the primaryKey value when the
+     *  mapped record's primaryKey is empty (e.g. `"feedId"`). Falls back
+     *  to a content hash of the record. */
+    idFrom?: string;
+    /** Cap on stored records. After each fetch the feed keeps only the
+     *  newest `maxItems` (ordered by the schema's first `date` field) and
+     *  deletes the rest. Defaults to {@link DEFAULT_FEED_MAX_ITEMS} when
+     *  omitted; `0` disables the cap (keep everything). Pruning is skipped
+     *  when the schema has no `date` field to order by. */
+    maxItems?: number;
+}
+/** Agent-performed retrieval (`kind: "agent"`). No `url`/`map`: the host seeds
+ *  a hidden background worker (origin `system`) in `role` with `template` + a
+ *  summary of every record, and the worker edits the records itself via the
+ *  collections io layer. Valid on any collection (primarily skill-backed). */
+export interface AgentIngestSpec extends CollectionIngest {
+    kind: AgentIngestKind;
+    /** Refresh cadence (same vocabulary as declarative feeds). */
+    schedule: FeedSchedule;
+    /** Role id the scheduled hidden worker runs in. */
+    role: string;
+    /** Skill-relative template path (under `templates/`) seeding the worker. */
+    template: string;
+}
+/** The `ingest` block carried on a `CollectionSchema`, discriminated on `kind`. */
+export type IngestSpec = DeclarativeIngestSpec | AgentIngestSpec;

package/dist/feeds/paths.cjs

@@ -0,0 +1,48 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_rolldown_runtime = require("../rolldown-runtime-D6vf50IK.cjs");
+let node_path = require("node:path");
+node_path = require_rolldown_runtime.__toESM(node_path, 1);
+//#region src/feeds/paths.ts
+var FEEDS_DIR = "feeds";
+var FEED_STATE_FILE = "_state.json";
+/** Where retrieval state for NON-feed collections with an `ingest` block
+*  (`kind: "agent"`) lives — one file per collection, OUTSIDE the collection's
+*  dataDir (where `listItems` would read it as a record) and outside `feeds/`
+*  (a schema-less `feeds/<slug>/` dir confuses feed discovery). Mirrors the
+*  host's `WORKSPACE_DIRS.ingestState`. */
+var INGEST_STATE_DIR = "data/ingest-state";
+/** Absolute path to the feeds registry root for a workspace. */
+function feedsRoot(workspaceRoot) {
+	return node_path.default.join(workspaceRoot, FEEDS_DIR);
+}
+/** Absolute path to one feed's directory (`<root>/<slug>/`). */
+function feedDir(slug, workspaceRoot) {
+	return node_path.default.join(feedsRoot(workspaceRoot), slug);
+}
+/** Absolute path to one feed's retrieval-state file. */
+function feedStatePath(slug, workspaceRoot) {
+	return node_path.default.join(feedsRoot(workspaceRoot), slug, FEED_STATE_FILE);
+}
+/** Directory holding retrieval state for NON-feed collections with an
+*  `ingest` block (`kind: "agent"`). One file per collection. */
+function ingestStateDir(workspaceRoot) {
+	return node_path.default.join(workspaceRoot, INGEST_STATE_DIR);
+}
+/** Absolute path to a non-feed collection's ingest-state file
+*  (`data/ingest-state/<slug>.json`). Kept OUT of the collection's dataDir
+*  (where `listItems` would read it as a record) and out of `feeds/` (a
+*  schema-less `feeds/<slug>/` dir confuses feed discovery). */
+function ingestStatePath(slug, workspaceRoot) {
+	return node_path.default.join(ingestStateDir(workspaceRoot), `${slug}.json`);
+}
+//#endregion
+exports.FEEDS_DIR = FEEDS_DIR;
+exports.FEED_STATE_FILE = FEED_STATE_FILE;
+exports.INGEST_STATE_DIR = INGEST_STATE_DIR;
+exports.feedDir = feedDir;
+exports.feedStatePath = feedStatePath;
+exports.feedsRoot = feedsRoot;
+exports.ingestStateDir = ingestStateDir;
+exports.ingestStatePath = ingestStatePath;
+
+//# sourceMappingURL=paths.cjs.map

package/dist/feeds/paths.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.cjs","names":[],"sources":["../../src/feeds/paths.ts"],"sourcesContent":["// Path helpers for the non-skill Feeds registry. Each feed lives at\n// `<workspace>/feeds/<slug>/schema.json` (a CollectionSchema + `ingest`\n// block) with its retrieval state alongside at\n// `<workspace>/feeds/<slug>/_state.json`. Records land wherever the\n// schema's `dataPath` points (validated by `resolveDataDir`), exactly\n// like every other collection.\n//\n// Pure root→path functions: `workspaceRoot` is always passed in (the host\n// supplies its default). Slugs reaching these helpers must already have\n// passed `safeSlugName` — these joins do not re-sanitize.\n\nimport path from \"node:path\";\n\nexport const FEEDS_DIR = \"feeds\";\nexport const FEED_STATE_FILE = \"_state.json\";\n\n/** Where retrieval state for NON-feed collections with an `ingest` block\n *  (`kind: \"agent\"`) lives — one file per collection, OUTSIDE the collection's\n *  dataDir (where `listItems` would read it as a record) and outside `feeds/`\n *  (a schema-less `feeds/<slug>/` dir confuses feed discovery). Mirrors the\n *  host's `WORKSPACE_DIRS.ingestState`. */\nexport const INGEST_STATE_DIR = \"data/ingest-state\";\n\n/** Absolute path to the feeds registry root for a workspace. */\nexport function feedsRoot(workspaceRoot: string): string {\n  return path.join(workspaceRoot, FEEDS_DIR);\n}\n\n/** Absolute path to one feed's directory (`<root>/<slug>/`). */\nexport function feedDir(slug: string, workspaceRoot: string): string {\n  return path.join(feedsRoot(workspaceRoot), slug);\n}\n\n/** Absolute path to one feed's retrieval-state file. */\nexport function feedStatePath(slug: string, workspaceRoot: string): string {\n  return path.join(feedsRoot(workspaceRoot), slug, FEED_STATE_FILE);\n}\n\n/** Directory holding retrieval state for NON-feed collections with an\n *  `ingest` block (`kind: \"agent\"`). One file per collection. */\nexport function ingestStateDir(workspaceRoot: string): string {\n  return path.join(workspaceRoot, INGEST_STATE_DIR);\n}\n\n/** Absolute path to a non-feed collection's ingest-state file\n *  (`data/ingest-state/<slug>.json`). Kept OUT of the collection's dataDir\n *  (where `listItems` would read it as a record) and out of `feeds/` (a\n *  schema-less `feeds/<slug>/` dir confuses feed discovery). */\nexport function ingestStatePath(slug: string, workspaceRoot: string): string {\n  return path.join(ingestStateDir(workspaceRoot), `${slug}.json`);\n}\n"],"mappings":";;;;;AAaA,IAAa,YAAY;AACzB,IAAa,kBAAkB;;;;;;AAO/B,IAAa,mBAAmB;;AAGhC,SAAgB,UAAU,eAA+B;CACvD,OAAO,UAAA,QAAK,KAAK,eAAe,SAAS;AAC3C;;AAGA,SAAgB,QAAQ,MAAc,eAA+B;CACnE,OAAO,UAAA,QAAK,KAAK,UAAU,aAAa,GAAG,IAAI;AACjD;;AAGA,SAAgB,cAAc,MAAc,eAA+B;CACzE,OAAO,UAAA,QAAK,KAAK,UAAU,aAAa,GAAG,MAAM,eAAe;AAClE;;;AAIA,SAAgB,eAAe,eAA+B;CAC5D,OAAO,UAAA,QAAK,KAAK,eAAe,gBAAgB;AAClD;;;;;AAMA,SAAgB,gBAAgB,MAAc,eAA+B;CAC3E,OAAO,UAAA,QAAK,KAAK,eAAe,aAAa,GAAG,GAAG,KAAK,MAAM;AAChE"}

package/dist/feeds/paths.d.ts

@@ -0,0 +1,22 @@
+export declare const FEEDS_DIR = "feeds";
+export declare const FEED_STATE_FILE = "_state.json";
+/** Where retrieval state for NON-feed collections with an `ingest` block
+ *  (`kind: "agent"`) lives — one file per collection, OUTSIDE the collection's
+ *  dataDir (where `listItems` would read it as a record) and outside `feeds/`
+ *  (a schema-less `feeds/<slug>/` dir confuses feed discovery). Mirrors the
+ *  host's `WORKSPACE_DIRS.ingestState`. */
+export declare const INGEST_STATE_DIR = "data/ingest-state";
+/** Absolute path to the feeds registry root for a workspace. */
+export declare function feedsRoot(workspaceRoot: string): string;
+/** Absolute path to one feed's directory (`<root>/<slug>/`). */
+export declare function feedDir(slug: string, workspaceRoot: string): string;
+/** Absolute path to one feed's retrieval-state file. */
+export declare function feedStatePath(slug: string, workspaceRoot: string): string;
+/** Directory holding retrieval state for NON-feed collections with an
+ *  `ingest` block (`kind: "agent"`). One file per collection. */
+export declare function ingestStateDir(workspaceRoot: string): string;
+/** Absolute path to a non-feed collection's ingest-state file
+ *  (`data/ingest-state/<slug>.json`). Kept OUT of the collection's dataDir
+ *  (where `listItems` would read it as a record) and out of `feeds/` (a
+ *  schema-less `feeds/<slug>/` dir confuses feed discovery). */
+export declare function ingestStatePath(slug: string, workspaceRoot: string): string;

package/dist/feeds/server/fetch/httpClient.d.ts

@@ -0,0 +1,8 @@
+/** Identifies the bot to site operators. */
+export declare const FEED_USER_AGENT = "MulmoClaude-FeedBot/1.0 (+https://github.com/receptron/mulmoclaude)";
+/** Per-request wall-clock cap so a hung server can't wedge a refresh. */
+export declare const DEFAULT_FEED_TIMEOUT_MS: number;
+/** Fetch a URL as text, throwing on guard rejection, network error, or non-2xx. */
+export declare function fetchText(url: string, timeoutMs?: number): Promise<string>;
+/** Fetch a URL as parsed JSON, throwing on guard rejection, network error, or non-2xx. */
+export declare function fetchJson(url: string, timeoutMs?: number): Promise<unknown>;

package/dist/feeds/server/fetch/rssParser.d.ts

@@ -0,0 +1,12 @@
+export interface ParsedFeedItem {
+    /** The raw parsed XML <item>/<entry> object, verbatim. */
+    raw: Record<string, unknown>;
+}
+export interface ParsedFeed {
+    kind: "rss" | "atom";
+    title: string | null;
+    items: ParsedFeedItem[];
+}
+/** Parse an RSS/Atom/RDF feed body. Returns null when the input doesn't
+ *  look like a feed we understand. */
+export declare function parseFeed(body: string): ParsedFeed | null;