@mulmoclaude/core 0.2.9 → 0.2.11

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

@@ -0,0 +1,77 @@
+/** Logger shape the engine logs through — matches the host `Logger`
+ *  (prefix, message, optional structured data). */
+export interface CollectionLogger {
+    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 CollectionHost {
+    /** Absolute path to the host workspace root (e.g. `~/mulmoclaude`). The
+     *  default root for every path/containment check that isn't given an
+     *  explicit override. */
+    workspaceRoot: string;
+    /** Host logger; the engine logs under the `"collections"` prefix. */
+    log: CollectionLogger;
+    /** Host workspace layout — supplied as the host's own path helpers so the
+     *  package owns no layout literals and works against a test/alt root. */
+    paths: {
+        /** Absolute user-scope skills dir (host-specific, e.g. `~/.claude/skills`). */
+        userSkillsDir: string;
+        /** Absolute project-scope skills dir for a workspace (`<root>/.claude/skills`). */
+        projectSkillsDir: (workspaceRoot: string) => string;
+        /** Absolute feeds-registry root for a workspace (`<root>/data/feeds`). */
+        feedsRoot: (workspaceRoot: string) => string;
+        /** Absolute project-skills *staging* dir for a workspace (`<root>/data/skills`). */
+        skillsStagingDir: (workspaceRoot: string) => string;
+        /** Workspace-relative archive dir (a removed collection's files move here). */
+        archiveDir: string;
+    };
+    /** True for a preset-skill slug (host-owned naming convention). */
+    isPresetSlug: (slug: string) => boolean;
+}
+/** A collection's records changed on disk. Carries the `slug` so the host can
+ *  publish on a per-collection channel; `ids` lists the affected record ids
+ *  when known (a consumer may ignore them and refetch the whole collection),
+ *  and `op` is advisory. Deliberately carries NO record bodies — this is a
+ *  "refetch" ping, not a data feed, so it stays cheap and leaks nothing when a
+ *  host relays it into an opaque-origin custom-view iframe. */
+export interface CollectionChangePayload {
+    slug: string;
+    ids?: string[];
+    op?: "upsert" | "delete";
+}
+type CollectionChangePublisher = (payload: CollectionChangePayload) => void;
+/** Wire the engine to a host. Call once at server startup, before any
+ *  collection storage operation. Re-binding to a *different* host throws —
+ *  silently redirecting later filesystem operations to another workspace
+ *  would be a bug, not a feature. Re-calling with the same host is a no-op. */
+export declare function configureCollectionHost(host: CollectionHost): void;
+/** Wire a publisher that broadcasts record-change events; the host bridges it
+ *  to its pubsub. Kept SEPARATE from `configureCollectionHost` because the
+ *  host's pubsub instance isn't ready at host-binding time (the binding is set
+ *  at the top of server startup, the pubsub later). Optional: left unset, every
+ *  write is silent — the default for tests and for a host that doesn't want
+ *  live view updates. Pass `null` to detach (test teardown). */
+export declare function setCollectionChangePublisher(publish: CollectionChangePublisher | null): void;
+/** Broadcast a record-change event if a publisher is wired (no-op otherwise).
+ *  Called from the write path (`writeItem`/`deleteItem`). The wired publisher is
+ *  expected to be fire-and-forget (it wraps its own pubsub call in try/catch),
+ *  so this stays a thin pass-through and never throws into the write. */
+export declare function publishCollectionChange(payload: CollectionChangePayload): void;
+/** The configured workspace root. Throws if the host never configured one. */
+export declare function getWorkspaceRoot(): string;
+export declare function userSkillsDir(): string;
+export declare function projectSkillsDir(workspaceRoot: string): string;
+export declare function feedsRoot(workspaceRoot: string): string;
+export declare function skillsStagingDir(workspaceRoot: string): string;
+export declare function archiveDir(): string;
+export declare function isPresetSlug(slug: string): boolean;
+/** Logger proxy so engine modules can `import { log }` and use it exactly like
+ *  the host logger — each call forwards to the live host binding. Logging is
+ *  non-critical, so calls before the host configures a binding (e.g. unit tests
+ *  that exercise pure logic) are dropped rather than throwing — unlike
+ *  `getWorkspaceRoot()`, which fails loudly because the engine cannot operate
+ *  without a workspace root. */
+export declare const log: CollectionLogger;
+export {};

package/dist/collection/server/index.cjs

@@ -0,0 +1,53 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_server = require("../../server-DAyIQ5rT.cjs");
+const require_collection_paths = require("../paths.cjs");
+exports.COMPUTED_TYPES = require_server.COMPUTED_TYPES;
+exports.CollectionSchemaZ = require_server.CollectionSchemaZ;
+exports.SCHEMA_FILE = require_server.SCHEMA_FILE;
+exports.acceptParsedSchema = require_server.acceptParsedSchema;
+exports.advanceTriggerDate = require_server.advanceTriggerDate;
+exports.buildActionSeedPrompt = require_server.buildActionSeedPrompt;
+exports.buildCollectionActionSeedPrompt = require_server.buildCollectionActionSeedPrompt;
+exports.computeSuccessor = require_server.computeSuccessor;
+exports.configureCollectionHost = require_server.configureCollectionHost;
+exports.daysInMonth = require_server.daysInMonth;
+exports.deleteCollection = require_server.deleteCollection;
+exports.deleteCollectionRefusalMessage = require_server.deleteCollectionRefusalMessage;
+exports.deleteCustomView = require_server.deleteCustomView;
+exports.deleteItem = require_server.deleteItem;
+exports.discoverCollections = require_server.discoverCollections;
+exports.enrichItems = require_server.enrichItems;
+exports.formatCivil = require_server.formatCivil;
+exports.generateItemId = require_server.generateItemId;
+exports.getWorkspaceRoot = require_server.getWorkspaceRoot;
+exports.isContainedInRoot = require_server.isContainedInRoot;
+exports.isContainedInWorkspace = require_server.isContainedInWorkspace;
+exports.isSafeActionTemplatePath = require_collection_paths.isSafeActionTemplatePath;
+exports.isSafeCustomViewI18nPath = require_collection_paths.isSafeCustomViewI18nPath;
+exports.isSafeCustomViewPath = require_collection_paths.isSafeCustomViewPath;
+exports.isSafeTemplatePath = require_collection_paths.isSafeTemplatePath;
+exports.isTriggerDue = require_server.isTriggerDue;
+exports.itemFilePath = require_server.itemFilePath;
+exports.listItems = require_server.listItems;
+exports.loadCollection = require_server.loadCollection;
+exports.log = require_server.log;
+exports.maybeSpawnSuccessor = require_server.maybeSpawnSuccessor;
+exports.parseCivil = require_server.parseCivil;
+exports.publishCollectionChange = require_server.publishCollectionChange;
+exports.readCustomViewHtml = require_server.readCustomViewHtml;
+exports.readCustomViewI18n = require_server.readCustomViewI18n;
+exports.readItem = require_server.readItem;
+exports.readSkillTemplate = require_server.readSkillTemplate;
+exports.resolveCreateItemId = require_server.resolveCreateItemId;
+exports.resolveDataDir = require_server.resolveDataDir;
+exports.resolveEvery = require_server.resolveEvery;
+exports.resolveTemplatePath = require_server.resolveTemplatePath;
+exports.safeRecordId = require_server.safeRecordId;
+exports.safeSlugName = require_server.safeSlugName;
+exports.setCollectionChangePublisher = require_server.setCollectionChangePublisher;
+exports.successorId = require_server.successorId;
+exports.toDetail = require_server.toDetail;
+exports.toSummary = require_server.toSummary;
+exports.validateCollectionRecords = require_server.validateCollectionRecords;
+exports.validateRecordObject = require_server.validateRecordObject;
+exports.writeItem = require_server.writeItem;

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-q4WPXtbU.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 };
+import { A as readItem, B as safeRecordId, C as buildActionSeedPrompt, D as listItems, E as generateItemId, F as isContainedInRoot, G as publishCollectionChange, H as configureCollectionHost, I as isContainedInWorkspace, K as setCollectionChangePublisher, L as itemFilePath, M as resolveCreateItemId, N as writeItem, O as readCustomViewHtml, P as SCHEMA_FILE, R as resolveDataDir, S as validateRecordObject, T as deleteItem, U as getWorkspaceRoot, V as safeSlugName, W as log, _ 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 readSkillTemplate, k as readCustomViewI18n, 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 resolveTemplatePath } from "../../server-D2QZuMS2.js";
+import { isSafeActionTemplatePath, isSafeCustomViewI18nPath, 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, isSafeCustomViewI18nPath, isSafeCustomViewPath, isSafeTemplatePath, isTriggerDue, itemFilePath, listItems, loadCollection, log, maybeSpawnSuccessor, parseCivil, publishCollectionChange, readCustomViewHtml, readCustomViewI18n, readItem, readSkillTemplate, resolveCreateItemId, resolveDataDir, resolveEvery, resolveTemplatePath, safeRecordId, safeSlugName, setCollectionChangePublisher, successorId, toDetail, toSummary, validateCollectionRecords, validateRecordObject, writeItem };

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

@@ -0,0 +1,147 @@
+import { CollectionItem, CollectionSchema } from '../core/schema';
+import { LoadedCollection } from './discoveredCollection';
+export interface IoOptions {
+    /** Override the workspace root for containment checks. Default:
+     *  the live `workspacePath`. Tests point this at a `mkdtempSync`
+     *  tree so the realpath-based escape detection can be exercised
+     *  without touching `~/mulmoclaude/`. Same pattern as
+     *  `server/workspace/skills/catalog.ts#CatalogOptions`. */
+    workspaceRoot?: string;
+    /** Collection slug this write/delete belongs to. When provided, a
+     *  successful write/delete publishes a record-change event (see
+     *  `publishCollectionChange`) so live views refetch. `writeItem` has no
+     *  slug of its own (it's keyed by `dataDir`), so callers thread it through;
+     *  omitting it just means no event is published (internal / test writes). */
+    slug?: string;
+}
+/** Read every record under `dataDir`. Returns [] if the dir doesn't
+ *  exist yet (legitimate first-use state). Malformed JSON files and
+ *  symlinked records are skipped (the latter is a file-disclosure
+ *  defense — see `isRegularFile`). Re-validates the realpath
+ *  containment to defend against a symlinked data dir appearing
+ *  between discovery and use. */
+export declare function listItems(dataDir: string, opts?: IoOptions): Promise<CollectionItem[]>;
+/** Read one record by id. Returns null when the file is missing,
+ *  when the resolved path escapes the workspace via a symlink, or
+ *  when the record file itself is a symlink (file-disclosure
+ *  defense — see `isRegularFile`). */
+export declare function readItem(dataDir: string, itemId: string, opts?: IoOptions): Promise<CollectionItem | null>;
+export interface WriteItemOptions extends IoOptions {
+    /** When true (POST/create), refuse to overwrite an existing file
+     *  and return `kind: "conflict"`. Update flow (PUT) leaves it false. */
+    refuseOverwrite?: boolean;
+}
+export type WriteItemResult = {
+    kind: "ok";
+    itemId: string;
+    item: CollectionItem;
+} | {
+    kind: "invalid-id";
+    itemId: string;
+} | {
+    kind: "conflict";
+    itemId: string;
+} | {
+    kind: "path-escape";
+    itemId: string;
+};
+/** Write a record. Ensures the directory exists, validates the id,
+ *  re-checks symlink containment after mkdir, and writes atomically.
+ *
+ *  Create path (`refuseOverwrite: true`) uses an O_EXCL `wx` open
+ *  rather than `stat` + `writeFileAtomic` to close a check-then-write
+ *  race: two concurrent POSTs would otherwise both pass the existence
+ *  check and one would silently overwrite the other. The trade-off
+ *  is that the create path is not crash-atomic (a partial file could
+ *  remain if the process dies mid-write); acceptable here because
+ *  records are small JSON blobs and the next read either parses or
+ *  is skipped via the "malformed JSON" branch in `listItems`.
+ *
+ *  Update path (`refuseOverwrite: false`) uses `writeFileAtomic` so
+ *  PUT remains crash-atomic. No race there — the URL pins the id. */
+export declare function writeItem(dataDir: string, itemId: string, item: CollectionItem, opts?: WriteItemOptions): Promise<WriteItemResult>;
+export type DeleteItemResult = {
+    kind: "ok";
+    itemId: string;
+} | {
+    kind: "invalid-id";
+    itemId: string;
+} | {
+    kind: "not-found";
+    itemId: string;
+} | {
+    kind: "path-escape";
+    itemId: string;
+};
+export declare function deleteItem(dataDir: string, itemId: string, opts?: IoOptions): Promise<DeleteItemResult>;
+/** Generate a short random hex id. Used by POST when the form doesn't
+ *  carry a primary-key value (UI shortcut — Claude normally derives a
+ *  semantic id from the record's name). */
+export declare function generateItemId(): string;
+/** The shape `readSourceAwareFile` (and its public callers
+ *  `readCustomViewHtml` / `readCustomViewI18n`) need from a loaded collection:
+ *  the slug for the safe-name check, the source to pick the base set, and the
+ *  discovered skill dir for the imported-layout fallback. Kept as a named
+ *  alias so the three signatures stay in lockstep (and so sonarjs stops
+ *  flagging the inline `Pick` union as duplication). */
+type SourceAwareReadTarget = Pick<LoadedCollection, "slug" | "source" | "skillDir">;
+/** Read a collection's custom-view HTML, path-safely. `viewFile` is a
+ *  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 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: SourceAwareReadTarget, viewFile: string, opts?: IoOptions): Promise<string | null>;
+export interface CustomViewI18nResult {
+    /** The locale the returned `dict` is keyed to — equals the requested locale
+     *  when available, else the `"en"` fallback, else `""` when neither block is
+     *  present (empty `dict`). The host echoes this back to the iframe so
+     *  `__MC_VIEW.locale` reflects what the view actually got. */
+    locale: string;
+    /** Flat key → string map for the picked locale. Empty when the file is
+     *  absent, malformed, or has no usable locale block. Non-string values in a
+     *  locale block are dropped — `__MC_VIEW.dict` is contract-flat. */
+    dict: Record<string, string>;
+}
+/** Read a custom view's translation dictionary and return only the strings
+ *  for the requested locale (or the `"en"` fallback, or empty). Same
+ *  source-aware fallback as `readCustomViewHtml` so imported and authored
+ *  project collections both work. The on-disk file is `{ <locale>: { <key>:
+ *  <string> } }`; the host never streams other locales' strings to the view.
+ *  Malformed JSON / unknown shape yields an empty dict — an i18n-less view
+ *  keeps working unchanged (`__MC_VIEW.t(key)` falls back to the key). */
+export declare function readCustomViewI18n(collection: SourceAwareReadTarget, i18nFile: string, locale: string, opts?: IoOptions): Promise<CustomViewI18nResult>;
+/** The item id a CREATE should use for `schema`, or null when the
+ *  caller should generate one. A singleton collection pins every
+ *  create to its fixed `schema.singleton` id, so the "at most one
+ *  record" contract is enforced server-side (a second create targets
+ *  the same file and hits `writeItem`'s refuseOverwrite conflict) —
+ *  not only in the UI. Otherwise the record's own primaryKey value
+ *  wins, falling back to a generated id (null = "generate"). */
+export declare function resolveCreateItemId(schema: CollectionSchema, record: CollectionItem): string | null;
+/** Read an action's template file from `skillDir`, path-safely. Returns
+ *  the file contents, or null when the path escapes the skill dir, the
+ *  resolved target isn't a regular file, or the read fails. */
+export declare function readSkillTemplate(skillDir: string, templateRelPath: string): Promise<string | null>;
+/** Build the seed prompt for a `kind: "chat"` action: a security-
+ *  boundary instruction + the record as a sanitized JSON data block +
+ *  the template text verbatim. Pure + exported for tests. Domain-free —
+ *  the template (skill-owned) carries every specific instruction; the
+ *  host only injects the record's own data. */
+export declare function buildActionSeedPrompt(record: CollectionItem, templateText: string): string;
+/** Build the seed prompt for a collection-level `kind: "chat"` action: a
+ *  security-boundary instruction + a compact progress summary of every
+ *  record (see `progressSummary`) + the template verbatim. Pure +
+ *  exported for tests. Domain-free — the template carries the specifics. */
+export declare function buildCollectionActionSeedPrompt(items: CollectionItem[], schema: CollectionSchema, templateText: string): string;
+export {};

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

@@ -0,0 +1,52 @@
+export declare const SCHEMA_FILE = "schema.json";
+/** Sanitise a user-supplied slug into a safe directory-name leaf.
+ *  Returns null for anything that fails the slug whitelist OR isn't a
+ *  basename (i.e. survives `path.basename` round-trip unchanged).
+ *  The basename round-trip is the pattern CodeQL recognises as a
+ *  `js/path-injection` sanitiser. */
+export declare function safeSlugName(slug: string): string | null;
+/** Sanitise a user-supplied record id into a safe filename stem. Like
+ *  `safeSlugName` but tolerates interior dots (so natural keys work),
+ *  while still rejecting any `..` substring, path separators, and
+ *  leading/trailing dots. The `path.basename` round-trip is the same
+ *  `js/path-injection` sanitiser CodeQL recognises on `safeSlugName`. */
+export declare function safeRecordId(recordId: string): string | null;
+/** True iff the realpath'd closest existing ancestor of `absPath`
+ *  resolves under `rootPath`'s realpath. Pure helper, takes both
+ *  paths explicitly so tests can drive it against a `mkdtempSync`
+ *  root without touching the user's workspace. Defends against the
+ *  data dir or any ancestor being a symlink to a directory outside
+ *  the workspace — lexical-only checks (`path.resolve` + prefix
+ *  match) would miss this case, which is the class of bug the rest
+ *  of this codebase uses realpath-based containment to avoid (see
+ *  `server/utils/files/safe.ts#resolveWithinRoot`). */
+export declare function isContainedInRoot(absPath: string, rootPath: string): boolean;
+/** Workspace-bound convenience over `isContainedInRoot`. Production
+ *  callers use this; the tests exercise the pure helper. */
+export declare function isContainedInWorkspace(absPath: string): boolean;
+/** Resolve a schema-declared dataPath against `rootPath` (default:
+ *  the live workspace), refusing anything that escapes — absolute
+ *  paths, `..`-segments, empty string, or symlinks pointing outside
+ *  the root. Returns the absolute path on success, null on refusal.
+ *  Does NOT require the directory to exist; the caller may create it
+ *  on first write. The realpath containment check covers the symlink
+ *  case at discovery time; io operations re-check before each write
+ *  to defend against symlinks introduced between discovery and use.
+ *
+ *  `rootPath` exists as an optional override so a test (or a tool
+ *  driving discovery against a `mkdtempSync` tree) gets a dataDir
+ *  rooted at the same place it asked to scan, not the real workspace.
+ *  Without this, `discoverApps({ workspaceRoot: tmpdir })` would
+ *  discover skills in tmpdir but resolve every app's dataDir against
+ *  `~/mulmoclaude/`, breaking isolation. */
+export declare function resolveDataDir(dataPath: string, rootPath?: string): string | null;
+/** Compose the absolute path to a single record file. Both arguments
+ *  must have been passed through `safeSlugName` / `resolveDataDir`
+ *  before reaching here so the join can't escape. */
+export declare function itemFilePath(dataDir: string, itemId: string): string;
+/** Resolve an action's skill-relative `template` path against
+ *  `skillDir`, refusing escapes — absolute paths, `..`-segments, or a
+ *  symlink pointing outside the skill dir. Mirrors `resolveDataDir`;
+ *  the realpath containment is the hard guarantee. Returns the
+ *  absolute path on success, null on refusal. */
+export declare function resolveTemplatePath(skillDir: string, templateRelPath: string): string | null;

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

@@ -0,0 +1,55 @@
+import { IoOptions } from './io';
+import { CollectionEvery, CollectionItem, CollectionSchema, CollectionSpawnEvery } from '../core/schema';
+/** A timezone-free calendar date. `m` is 1-12. */
+export interface CivilDate {
+    y: number;
+    m: number;
+    d: number;
+}
+/** Days in `month` (1-12) of `year`, leap-year-aware. `new Date(y, m, 0)`
+ *  is day 0 of the *next* month = the last day of `month`; `.getDate()`
+ *  reads the civil day regardless of timezone. */
+export declare function daysInMonth(year: number, month: number): number;
+/** Parse a `YYYY-MM-DD` string into a CivilDate, or null when the value
+ *  isn't a well-formed in-range calendar date. */
+export declare function parseCivil(raw: unknown): CivilDate | null;
+/** `YYYY-MM-DD` for storage in a `date` field. */
+export declare function formatCivil(date: CivilDate): string;
+/** Advance a civil date by one `every` step. Month/year units preserve
+ *  the rule's day-of-month anchor, clamped to the target month's length
+ *  (no drift); day/week units do civil day arithmetic. */
+export declare function advanceTriggerDate(source: CivilDate, every: CollectionEvery): CivilDate;
+/** True iff `now`'s civil date (local timezone) has reached the fire date
+ *  for `triggerRaw` — i.e. the trigger date minus `leadDays` (so a 10-day
+ *  lead fires 10 days early). Returns null when `triggerRaw` isn't a
+ *  parseable date — callers treat that as "don't fire" and warn. */
+export declare function isTriggerDue(triggerRaw: unknown, now: Date, leadDays?: number): boolean | null;
+/** Deterministic successor id: `<stem>-<YYYYMMDD>`, where `<stem>` is the
+ *  source id with a trailing `-YYYYMMDD` stripped if present. So a chain
+ *  shares one stem and each instance is dated:
+ *    `rent`           → `rent-20260610`
+ *    `rent-20260610`  → `rent-20260710`
+ *  Slug-safe (alphanumeric + hyphen) and a pure function of the inputs,
+ *  which is what makes create-if-absent idempotent. */
+export declare function successorId(sourceId: string, next: CivilDate): string;
+/** Resolve the literal `every` that applies to `sourceItem`. Literal-arm
+ *  `spawn.every` passes through unchanged. Field-driven `spawn.every` reads
+ *  `sourceItem[fromField]` and looks it up in `map`; an empty field or a
+ *  value with no map entry yields null (caller skips + logs — see plan §5).
+ *  Discovery rejects a map that doesn't cover the enum's values, so null
+ *  here means a record that predates a map/enum edit. */
+export declare function resolveEvery(every: CollectionSpawnEvery, sourceItem: CollectionItem): CollectionEvery | null;
+export interface ComputedSuccessor {
+    id: string;
+    record: CollectionItem;
+}
+/** Build the successor record purely from (schema, source record, source
+ *  id). Returns null when the schema has no spawn/triggerField or the
+ *  source's trigger date is unparseable. */
+export declare function computeSuccessor(schema: CollectionSchema, sourceItem: CollectionItem, sourceId: string): ComputedSuccessor | null;
+/** Idempotently create the successor for `sourceItem` when it matches the
+ *  spawn predicate. No-op when the schema declares no spawn, the
+ *  predicate doesn't match, the trigger date is unparseable, or the
+ *  successor already exists (create-if-absent). Never overwrites an
+ *  existing successor — protects any edits the user made to it. */
+export declare function maybeSpawnSuccessor(slug: string, schema: CollectionSchema, dataDir: string, sourceItem: CollectionItem, sourceId: string, ioOpts?: IoOptions): Promise<void>;

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

@@ -23,3 +23,12 @@ export declare function isSafeActionTemplatePath(value: string): boolean;
  * realpath containment is the hard guarantee.
  */
 export declare function isSafeCustomViewPath(value: string): boolean;
+/**
+ * A custom-view `i18n` value: the JSON dictionary file authors ship next to
+ * their `views/<id>.html`. Constrained to `views/<name>.i18n.json` so the
+ * field can only point at a translation file co-located with the view it
+ * translates — the same `views/` containment the HTML reader uses. The
+ * `.i18n.json` suffix (vs plain `.json`) makes the file's purpose grep-able
+ * for both authors and tooling.
+ */
+export declare function isSafeCustomViewI18nPath(value: string): boolean;

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

@@ -0,0 +1,3 @@
+/** Human-readable message from an unknown thrown value. */
+export declare function errorMessage(err: unknown): string;
+export declare const ONE_DAY_MS: number;

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

@@ -0,0 +1,19 @@
+import { LoadedCollection } from './discoveredCollection';
+import { CollectionItem, CollectionSchema } from '../core/schema';
+export interface RecordIssue {
+    /** Record filename, e.g. `lesson-003.json`. */
+    file: string;
+    /** Human-readable problem, written to be actionable by the LLM. */
+    problem: string;
+}
+export declare const COMPUTED_TYPES: ReadonlySet<string>;
+export declare function validateCollectionRecords(collection: LoadedCollection, opts?: {
+    workspaceRoot?: string;
+}): Promise<RecordIssue[]>;
+/** First schema problem on an in-memory record (primaryKey↔id mismatch,
+ *  missing required, bad enum value), or null when it's fine. One issue
+ *  per record keeps the report short and the fix obvious. Pure +
+ *  exported so write paths (manageCollection putItems) can gate on the
+ *  SAME rules the post-hoc file scan reports — `itemId` is the id the
+ *  record is (or would be) stored under. */
+export declare function validateRecordObject(record: CollectionItem, itemId: string, schema: CollectionSchema): string | null;

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

@@ -0,0 +1,20 @@
+import { IoOptions } from './io';
+import { LoadedCollection } from './discoveredCollection';
+export type DeleteViewResult = {
+    kind: "ok";
+    viewId: string;
+} | {
+    kind: "not-found";
+    viewId: string;
+} | {
+    kind: "user-scope";
+} | {
+    kind: "preset";
+} | {
+    kind: "unsafe-path";
+    viewId: string;
+};
+/** Delete one custom view from `collection`: unlink its HTML file and drop it
+ *  from every schema.json copy. User-scope and preset (mc-*) collections are
+ *  refused (read-only / re-seeded on boot), consistent with `deleteCollection`. */
+export declare function deleteCustomView(collection: LoadedCollection, viewId: string, opts?: IoOptions): Promise<DeleteViewResult>;

package/dist/collection-watchers/config.d.ts

@@ -0,0 +1,49 @@
+import { NotifierSeverity } from '../notifier';
+/** Two-level urgency a pending record can carry, derived from the
+ *  schema's `notifyWhen` spec. The host maps this onto its own severity
+ *  scale via `priorityToSeverity`. */
+export type CompletionPriority = "normal" | "high";
+export interface CollectionWatcherLogger {
+    info: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+}
+/** The host-specific notification surface the reconciler binds to. The
+ *  reconciler owns the internal `legacyId` key (it encodes slug+itemId
+ *  and round-trips it through `pluginData`); the adapter only wraps /
+ *  unwraps it into whatever shape the host's bell expects. */
+export interface CollectionNotificationAdapter {
+    /** Plugin namespace these bell entries publish under (MulmoClaude: "todo"). */
+    pluginPkg: string;
+    /** Map a record's completion priority onto the host's bell severity. */
+    priorityToSeverity: (priority: CompletionPriority) => NotifierSeverity;
+    /** Build the in-app deep-link the bell row routes to on click. */
+    buildNavigateTarget: (slug: string, itemId: string) => string;
+    /** Wrap the reconciler's internal key + priority into the host's
+     *  `pluginData` shape. Stored verbatim on the entry; recovered via
+     *  `readEntry`. */
+    buildPluginData: (input: {
+        legacyId: string;
+        slug: string;
+        itemId: string;
+        priority: CompletionPriority;
+        navigateTarget: string;
+    }) => unknown;
+    /** Recognise a bell entry produced by this reconciler and recover its
+     *  internal key + stored priority. Returns null for entries that didn't
+     *  originate here, so `listAll()` scans skip foreign entries. */
+    readEntry: (pluginData: unknown) => {
+        legacyId: string;
+        priority: CompletionPriority;
+    } | null;
+}
+/** Wire the host adapter + logger. Call once at startup, before
+ *  `startCollectionWatchers` or any direct reconcile call. */
+export declare function configureCollectionWatchers(config: {
+    adapter: CollectionNotificationAdapter;
+    log?: CollectionWatcherLogger;
+}): void;
+export declare function requireAdapter(): CollectionNotificationAdapter;
+export declare function log(): CollectionWatcherLogger;
+/** Test-only: clear the host wiring. */
+export declare function resetCollectionWatchersConfig(): void;
+export declare function errMsg(err: unknown): string;