@mulmoclaude/core 0.2.2 → 0.2.5

package/assets/helps/custom-view.md

@@ -69,19 +69,36 @@ window.__MC_VIEW = {
 
 ### Reading records
 
+> **Always project `fields`.** The host refuses any read of more than 200
+> records that does not pass `?fields=…` or `?ids=…`, because an unscoped
+> fetch wastes work and bandwidth on columns your view never reads. Once a
+> user's collection grows past the threshold an unprojected view starts
+> returning `400` instead of records — write the projection from day one so
+> the same view keeps working forever.
+
 ```js
 const { token, dataUrl } = window.__MC_VIEW;
-const res = await fetch(dataUrl, { headers: { Authorization: "Bearer " + token } });
-if (!res.ok) throw new Error("load failed: " + res.status);
+// List the columns this view actually reads — never send `dataUrl` raw.
+const url = dataUrl + "?fields=" + encodeURIComponent("title,start,end,status");
+const res = await fetch(url, { headers: { Authorization: "Bearer " + token } });
+if (!res.ok) {
+  // Surface the server's reason (the 400 carries `{ error: "<message>" }`),
+  // not just the status code — that text is what tells the user / Claude
+  // how to fix the call (e.g. "pass `fields` to project only the columns").
+  const detail = await res.text();
+  throw new Error("load failed (" + res.status + "): " + detail);
+}
 const { items } = await res.json(); // { collection, count, items: [...] }
 ```
 
 Records come back **with computed fields already resolved** (derived formulas,
 toggles, embeds) — the same numbers the user sees elsewhere.
 
-- Narrow large reads: `dataUrl + "?fields=title,start,end"` or `?ids=a,b,c`
-  (comma-separated). A read of **more than 200 records** without `ids`/`fields`
-  is refused — always project `fields` for big collections.
+- **`?fields=a,b,c`** — only these columns per record (the primary key is always
+  included). Use this on every read; it is mandatory above 200 records.
+- **`?ids=x,y,z`** — only these specific record ids. Use it when the view edits
+  / shows one record at a time. Combinable with `fields`.
+- The primary key is always returned regardless of `fields`.
 
 ### Writing records (only with the `write` capability)
 
@@ -111,9 +128,11 @@ By default a view paints once, on load. To keep it fresh, register a callback
 it runs whenever the collection's data changes on the server:
 
 ```js
+// Same projection rule as the initial read — list the columns this view uses.
+const url = dataUrl + "?fields=" + encodeURIComponent("title,start,end,status");
 async function render() {
-  const res = await fetch(dataUrl, { headers: { Authorization: "Bearer " + token } });
-  if (!res.ok) return; // handle the error per your UI
+  const res = await fetch(url, { headers: { Authorization: "Bearer " + token } });
+  if (!res.ok) return; // surface the body if you want a richer error UI
   const { items } = await res.json();
   // …draw items…
 }
@@ -303,8 +322,9 @@ fields `start` / `end` and a `title`. `capabilities: ["read"]`.
       const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
       async function main() {
         const { token, dataUrl } = window.__MC_VIEW;
-        const res = await fetch(dataUrl, { headers: { Authorization: "Bearer " + token } });
-        if (!res.ok) throw new Error("HTTP " + res.status);
+        const url = dataUrl + "?fields=" + encodeURIComponent("title,start");
+        const res = await fetch(url, { headers: { Authorization: "Bearer " + token } });
+        if (!res.ok) throw new Error("HTTP " + res.status + ": " + (await res.text()));
         const { items } = await res.json();
         const buckets = MONTHS.map(() => []);
         for (const it of items) {
@@ -382,10 +402,11 @@ writes it back. `capabilities: ["read","write"]`.
       const DAYS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
       const { token, dataUrl } = window.__MC_VIEW;
       const auth = { Authorization: "Bearer " + token, "Content-Type": "application/json" };
+      const readUrl = dataUrl + "?fields=" + encodeURIComponent("title,start");
 
       async function read() {
-        const res = await fetch(dataUrl, { headers: { Authorization: "Bearer " + token } });
-        if (!res.ok) throw new Error("HTTP " + res.status);
+        const res = await fetch(readUrl, { headers: { Authorization: "Bearer " + token } });
+        if (!res.ok) throw new Error("HTTP " + res.status + ": " + (await res.text()));
         return (await res.json()).items;
       }
       async function bump(item) {

package/dist/collection/server/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_server = require("../../server-Bego8VyU.cjs");
+const require_server = require("../../server-D27UzXug.cjs");
 const require_collection_paths = require("../paths.cjs");
 exports.COMPUTED_TYPES = require_server.COMPUTED_TYPES;
 exports.CollectionSchemaZ = require_server.CollectionSchemaZ;

package/dist/collection/server/index.js

@@ -1,3 +1,3 @@
-import { A as readSkillTemplate, B as safeSlugName, C as buildActionSeedPrompt, D as listItems, E as generateItemId, F as isContainedInWorkspace, G as setCollectionChangePublisher, H as getWorkspaceRoot, I as itemFilePath, L as resolveDataDir, M as writeItem, N as SCHEMA_FILE, O as readCustomViewHtml, P as isContainedInRoot, R as resolveTemplatePath, S as validateRecordObject, T as deleteItem, U as log, V as configureCollectionHost, W as publishCollectionChange, _ as loadCollection, a as computeSuccessor, b as COMPUTED_TYPES, c as isTriggerDue, d as resolveEvery, f as successorId, g as discoverCollections, h as acceptParsedSchema, i as advanceTriggerDate, j as resolveCreateItemId, k as readItem, l as maybeSpawnSuccessor, m as CollectionSchemaZ, n as deleteCollection, o as daysInMonth, p as enrichItems, r as deleteCollectionRefusalMessage, s as formatCivil, t as deleteCustomView, u as parseCivil, v as toDetail, w as buildCollectionActionSeedPrompt, x as validateCollectionRecords, y as toSummary, z as safeRecordId } from "../../server-BPDCdvOI.js";
+import { A as readSkillTemplate, B as safeSlugName, C as buildActionSeedPrompt, D as listItems, E as generateItemId, F as isContainedInWorkspace, G as setCollectionChangePublisher, H as getWorkspaceRoot, I as itemFilePath, L as resolveDataDir, M as writeItem, N as SCHEMA_FILE, O as readCustomViewHtml, P as isContainedInRoot, R as resolveTemplatePath, S as validateRecordObject, T as deleteItem, U as log, V as configureCollectionHost, W as publishCollectionChange, _ as loadCollection, a as computeSuccessor, b as COMPUTED_TYPES, c as isTriggerDue, d as resolveEvery, f as successorId, g as discoverCollections, h as acceptParsedSchema, i as advanceTriggerDate, j as resolveCreateItemId, k as readItem, l as maybeSpawnSuccessor, m as CollectionSchemaZ, n as deleteCollection, o as daysInMonth, p as enrichItems, r as deleteCollectionRefusalMessage, s as formatCivil, t as deleteCustomView, u as parseCivil, v as toDetail, w as buildCollectionActionSeedPrompt, x as validateCollectionRecords, y as toSummary, z as safeRecordId } from "../../server-B2YkcCwl.js";
 import { isSafeActionTemplatePath, isSafeCustomViewPath, isSafeTemplatePath } from "../paths.js";
 export { COMPUTED_TYPES, CollectionSchemaZ, SCHEMA_FILE, acceptParsedSchema, advanceTriggerDate, buildActionSeedPrompt, buildCollectionActionSeedPrompt, computeSuccessor, configureCollectionHost, daysInMonth, deleteCollection, deleteCollectionRefusalMessage, deleteCustomView, deleteItem, discoverCollections, enrichItems, formatCivil, generateItemId, getWorkspaceRoot, isContainedInRoot, isContainedInWorkspace, isSafeActionTemplatePath, isSafeCustomViewPath, isSafeTemplatePath, isTriggerDue, itemFilePath, listItems, loadCollection, log, maybeSpawnSuccessor, parseCivil, publishCollectionChange, readCustomViewHtml, readItem, readSkillTemplate, resolveCreateItemId, resolveDataDir, resolveEvery, resolveTemplatePath, safeRecordId, safeSlugName, setCollectionChangePublisher, successorId, toDetail, toSummary, validateCollectionRecords, validateRecordObject, writeItem };

package/dist/collection/server/io.d.ts

@@ -82,12 +82,18 @@ export declare function generateItemId(): string;
  *  schema-validated `views/*.html` path, resolved with realpath containment.
  *  Returns the HTML, or null when the path is unsafe or the file is missing.
  *
- *  The base dir is source-aware: a **project** collection authors views in the
- *  `data/skills/<slug>/` staging dir (custom-view HTML is staging-only — NOT
- *  mirrored to `.claude/skills`, because rendering is host-side; see
- *  plans/done/feat-collections-custom-views.md), whereas a **user** / **feed**
- *  collection is authored directly in its own discovered `skillDir`. Reading
- *  relative to the wrong tree would 404 a perfectly valid view. */
+ *  The base dir is source-aware. A **project** collection AUTHORED in-place
+ *  keeps its views in the `data/skills/<slug>/` staging dir (host-side
+ *  rendering; see plans/done/feat-collections-custom-views.md). A **project**
+ *  collection that was IMPORTED via the discover panel (rename-on-conflict)
+ *  carries its views inside `.claude/skills/<slug>/views/` — the skill folder
+ *  itself — without a staging-dir mirror; reading only the staging path would
+ *  404 a perfectly valid imported view. We try staging first, then fall back
+ *  to the discovered `skillDir`, so both layouts read cleanly. A **user** /
+ *  **feed** collection is always authored in its own discovered `skillDir`,
+ *  so it only needs the single lookup. `resolveTemplatePath` does the
+ *  containment / `..` defense per base, so the fallback never broadens the
+ *  attack surface. */
 export declare function readCustomViewHtml(collection: Pick<LoadedCollection, "slug" | "source" | "skillDir">, viewFile: string, opts?: IoOptions): Promise<string | null>;
 /** The item id a CREATE should use for `schema`, or null when the
  *  caller should generate one. A singleton collection pins every

package/dist/collection-watchers/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_collection_index = require("../collection/index.cjs");
-const require_server = require("../server-Bego8VyU.cjs");
+const require_server = require("../server-D27UzXug.cjs");
 const require_notifier = require("../notifier-bS8IEeLA.cjs");
 let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");

package/dist/collection-watchers/index.js

@@ -1,5 +1,5 @@
 import { whenMatches } from "../collection/index.js";
-import { D as listItems, _ as loadCollection, c as isTriggerDue, g as discoverCollections, k as readItem, l as maybeSpawnSuccessor } from "../server-BPDCdvOI.js";
+import { D as listItems, _ as loadCollection, c as isTriggerDue, g as discoverCollections, k as readItem, l as maybeSpawnSuccessor } from "../server-B2YkcCwl.js";
 import { d as publish, m as updateForPlugin, n as clear, s as listAll } from "../notifier-ChpY0XrY.js";
 import { watch } from "node:fs";
 import { mkdir } from "node:fs/promises";

package/dist/feeds/index.cjs

@@ -0,0 +1,17 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_deriveAll = require("../deriveAll-VRWrs3SF.cjs");
+const require_ingestTypes = require("../ingestTypes-DDOVhOYC.cjs");
+const require_feeds_paths = require("./paths.cjs");
+exports.AGENT_INGEST_KIND = require_ingestTypes.AGENT_INGEST_KIND;
+exports.DEFAULT_FEED_MAX_ITEMS = require_ingestTypes.DEFAULT_FEED_MAX_ITEMS;
+exports.FEEDS_DIR = require_feeds_paths.FEEDS_DIR;
+exports.FEED_SCHEDULES = require_deriveAll.FEED_SCHEDULES;
+exports.FEED_STATE_FILE = require_feeds_paths.FEED_STATE_FILE;
+exports.INGEST_KINDS = require_deriveAll.INGEST_KINDS;
+exports.INGEST_STATE_DIR = require_feeds_paths.INGEST_STATE_DIR;
+exports.feedDir = require_feeds_paths.feedDir;
+exports.feedStatePath = require_feeds_paths.feedStatePath;
+exports.feedsRoot = require_feeds_paths.feedsRoot;
+exports.ingestStateDir = require_feeds_paths.ingestStateDir;
+exports.ingestStatePath = require_feeds_paths.ingestStatePath;
+exports.isFeedSchedule = require_ingestTypes.isFeedSchedule;

package/dist/feeds/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ingestTypes.js';
+export * from './paths.js';

package/dist/feeds/index.js

@@ -0,0 +1,4 @@
+import { a as FEED_SCHEDULES, o as INGEST_KINDS } from "../deriveAll-vzIhhKBK.js";
+import { n as DEFAULT_FEED_MAX_ITEMS, r as isFeedSchedule, t as AGENT_INGEST_KIND } from "../ingestTypes-B8DaQOTy.js";
+import { FEEDS_DIR, FEED_STATE_FILE, INGEST_STATE_DIR, feedDir, feedStatePath, feedsRoot, ingestStateDir, ingestStatePath } from "./paths.js";
+export { AGENT_INGEST_KIND, DEFAULT_FEED_MAX_ITEMS, FEEDS_DIR, FEED_SCHEDULES, FEED_STATE_FILE, INGEST_KINDS, INGEST_STATE_DIR, feedDir, feedStatePath, feedsRoot, ingestStateDir, ingestStatePath, isFeedSchedule };

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/paths.js

@@ -0,0 +1,38 @@
+import path from "node:path";
+//#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 path.join(workspaceRoot, FEEDS_DIR);
+}
+/** Absolute path to one feed's directory (`<root>/<slug>/`). */
+function feedDir(slug, workspaceRoot) {
+	return path.join(feedsRoot(workspaceRoot), slug);
+}
+/** Absolute path to one feed's retrieval-state file. */
+function feedStatePath(slug, workspaceRoot) {
+	return path.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 path.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 path.join(ingestStateDir(workspaceRoot), `${slug}.json`);
+}
+//#endregion
+export { FEEDS_DIR, FEED_STATE_FILE, INGEST_STATE_DIR, feedDir, feedStatePath, feedsRoot, ingestStateDir, ingestStatePath };
+
+//# sourceMappingURL=paths.js.map

package/dist/feeds/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","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,KAAK,KAAK,eAAe,SAAS;AAC3C;;AAGA,SAAgB,QAAQ,MAAc,eAA+B;CACnE,OAAO,KAAK,KAAK,UAAU,aAAa,GAAG,IAAI;AACjD;;AAGA,SAAgB,cAAc,MAAc,eAA+B;CACzE,OAAO,KAAK,KAAK,UAAU,aAAa,GAAG,MAAM,eAAe;AAClE;;;AAIA,SAAgB,eAAe,eAA+B;CAC5D,OAAO,KAAK,KAAK,eAAe,gBAAgB;AAClD;;;;;AAMA,SAAgB,gBAAgB,MAAc,eAA+B;CAC3E,OAAO,KAAK,KAAK,eAAe,aAAa,GAAG,GAAG,KAAK,MAAM;AAChE"}

package/dist/feeds/server/agentIngest.d.ts

@@ -0,0 +1,13 @@
+import { LoadedCollection } from '../../collection/server/index.js';
+import { RefreshResult } from './refreshResult.js';
+export type { AgentWorkerResult, AgentWorkerRunner } from './host.js';
+/** Dispatch one agent-ingest refresh: build the seed, launch a worker, and (on a
+ *  successful launch) stamp `lastFetchedAt` with the DISPATCH time — not
+ *  completion. That's what gates the due-loop, so a slow worker can't cause a
+ *  double-dispatch. `opts.hidden` (default true) runs an invisible system worker
+ *  for SCHEDULED refreshes; a MANUAL Refresh passes `hidden:false` for a visible,
+ *  debuggable session. Failure-isolated: never throws; cap-miss / template-miss /
+ *  launch error leave state untouched and report via `errors`. */
+export declare function refreshViaAgent(workspaceRoot: string, collection: LoadedCollection, opts?: {
+    hidden?: boolean;
+}): Promise<RefreshResult>;

package/dist/feeds/server/engine.d.ts

@@ -0,0 +1,12 @@
+import { LoadedCollection } from '../../collection/server/index.js';
+import { RefreshResult } from './refreshResult.js';
+export type { RefreshResult } from './refreshResult.js';
+/** Fetch one feed now, upsert its records, then enforce the maxItems cap.
+ *  Failure-isolated: returns an errors array rather than throwing. */
+export declare function refreshOne(workspaceRoot: string, feed: LoadedCollection, opts?: {
+    hidden?: boolean;
+}): Promise<RefreshResult>;
+/** Refresh every collection whose ingest schedule says it's due — declarative
+ *  feeds AND skill-backed collections with `ingest.kind: "agent"`. Called by the
+ *  hourly system task. Sequential + failure-isolated. */
+export declare function refreshDue(workspaceRoot?: string): Promise<RefreshResult[]>;

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;

package/dist/feeds/server/host.d.ts

@@ -0,0 +1,51 @@
+/** Outcome of launching one hidden/visible agent-ingest worker. `chatId` lets
+ *  the caller register a completion hook so a failed refresh doesn't die
+ *  silently. */
+export type AgentWorkerResult = {
+    ok: true;
+    chatId: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Launches a worker chat. Injected at boot to keep the feeds engine from
+ *  importing a host's routes/session layer. `hidden` chooses an invisible
+ *  system worker (scheduled refresh) vs a visible session the user can watch
+ *  (manual Refresh — debuggable). `onComplete` is a one-shot completion hook
+ *  (only honoured for hidden workers) so the dispatcher learns success/failure.
+ *  Returns `ok:false` on the concurrency-cap miss or a launch error — the caller
+ *  leaves state untouched and retries next tick. */
+export type AgentWorkerRunner = (args: {
+    message: string;
+    roleId: string;
+    hidden: boolean;
+    onComplete?: (outcome: {
+        didError: boolean;
+    }) => void | Promise<void>;
+}) => Promise<AgentWorkerResult>;
+/** Structured logger, `(prefix, msg, data?)` — same shape as `CollectionLogger`. */
+export interface FeedsLogger {
+    error: (prefix: string, message: string, data?: Record<string, unknown>) => void;
+    warn: (prefix: string, message: string, data?: Record<string, unknown>) => void;
+    info: (prefix: string, message: string, data?: Record<string, unknown>) => void;
+    debug: (prefix: string, message: string, data?: Record<string, unknown>) => void;
+}
+export interface FeedsHost {
+    /** Absolute workspace root — the default for `refreshDue()` and state paths. */
+    workspaceRoot: string;
+    /** Host logger. */
+    log: FeedsLogger;
+    /** Host atomic file writer (state files). */
+    writeFileAtomic: (filePath: string, content: string) => Promise<void>;
+    /** Launches the agent-ingest worker (was `setAgentWorkerRunner`). */
+    spawnWorker: AgentWorkerRunner;
+}
+/** Wire the feeds engine to a host. Call once at startup, before any refresh. */
+export declare function configureFeedsHost(host: FeedsHost): void;
+/** The configured host, or throw if `configureFeedsHost` was never called. */
+export declare function requireFeedsHost(): FeedsHost;
+/** Test-only: clear the configured host. */
+export declare function resetFeedsHostForTesting(): void;
+/** Forwarding logger so engine modules can `import { log }` without each
+ *  reaching for `requireFeedsHost().log`. */
+export declare const log: FeedsLogger;