@mulmoclaude/core 0.2.7 → 0.2.9

package/dist/collection/server/index.cjs

@@ -1,51 +0,0 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_server = require("../../server-Db-x7OXz.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.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.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/io.d.ts

@@ -1,120 +0,0 @@
-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;
-/** 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: 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
- *  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;

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

@@ -1,52 +0,0 @@
-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

@@ -1,55 +0,0 @@
-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/util.d.ts

@@ -1,3 +0,0 @@
-/** 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

@@ -1,19 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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

@@ -1,49 +0,0 @@
-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;