@mulmoclaude/collection-plugin 0.5.1 → 0.5.3

package/dist/server.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("./chunk-CKQMccvm.cjs");
-const require_schema = require("./schema-LrmrgW12.cjs");
+const require_schema = require("./schema-5P5ZJPrY.cjs");
 const require_deriveAll = require("./deriveAll-BJ0Lvm1Q.cjs");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path, 1);
@@ -72,6 +72,20 @@ function safeSlugName(slug) {
 	if (basename !== slug) return null;
 	return basename;
 }
+var SAFE_RECORD_ID_PATTERN = /^[a-zA-Z0-9](?:[a-zA-Z0-9_.-]*[a-zA-Z0-9])?$/;
+/** 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`. */
+function safeRecordId(recordId) {
+	if (typeof recordId !== "string") return null;
+	if (!SAFE_RECORD_ID_PATTERN.test(recordId)) return null;
+	if (recordId.includes("..")) return null;
+	const basename = node_path.default.basename(recordId);
+	if (basename !== recordId) return null;
+	return basename;
+}
 /** Realpath the closest existing ancestor of `absPath` and return it.
 *  Returns null if no ancestor exists or if the realpath call fails
 *  for a non-ENOENT reason (permissions, etc.). Used by
@@ -305,7 +319,7 @@ async function listItems(dataDir, opts = {}) {
 *  when the record file itself is a symlink (file-disclosure
 *  defense — see `isRegularFile`). */
 async function readItem(dataDir, itemId, opts = {}) {
-	const safeId = safeSlugName(itemId);
+	const safeId = safeRecordId(itemId);
 	if (safeId === null) return null;
 	if (!isContainedInRoot(dataDir, opts.workspaceRoot ?? getWorkspaceRoot())) return null;
 	const filePath = itemFilePath(dataDir, safeId);
@@ -335,7 +349,7 @@ async function readItem(dataDir, itemId, opts = {}) {
 *  Update path (`refuseOverwrite: false`) uses `writeFileAtomic` so
 *  PUT remains crash-atomic. No race there — the URL pins the id. */
 async function writeItem(dataDir, itemId, item, opts = {}) {
-	const safeId = safeSlugName(itemId);
+	const safeId = safeRecordId(itemId);
 	if (safeId === null) return {
 		kind: "invalid-id",
 		itemId
@@ -394,7 +408,7 @@ async function writeItem(dataDir, itemId, item, opts = {}) {
 	};
 }
 async function deleteItem(dataDir, itemId, opts = {}) {
-	const safeId = safeSlugName(itemId);
+	const safeId = safeRecordId(itemId);
 	if (safeId === null) return {
 		kind: "invalid-id",
 		itemId
@@ -766,7 +780,7 @@ var CustomViewSchema = zod.z.object({
 	file: zod.z.string().trim().min(1).refine(isSafeCustomViewPath, "must be a safe path under `views/` ending in `.html` (e.g. `views/year.html`; no `..`, no leading `/`, no backslash)"),
 	capabilities: zod.z.array(zod.z.enum(["read", "write"])).optional()
 });
-var EverySchema = zod.z.object({
+var EveryLiteralSchema = zod.z.object({
 	unit: zod.z.enum([
 		"day",
 		"week",
@@ -775,7 +789,12 @@ var EverySchema = zod.z.object({
 	]),
 	interval: zod.z.number().int().min(1),
 	dayOfMonth: zod.z.union([zod.z.number().int().min(1).max(31), zod.z.literal("last")]).optional()
-});
+}).strict();
+var EveryFieldDrivenSchema = zod.z.object({
+	fromField: zod.z.string().trim().min(1),
+	map: zod.z.record(zod.z.string(), EveryLiteralSchema)
+}).strict();
+var EverySchema = zod.z.union([EveryLiteralSchema, EveryFieldDrivenSchema]);
 var SpawnSchema = zod.z.object({
 	when: WhenSchema.optional(),
 	every: EverySchema,
@@ -817,6 +836,36 @@ function spawnSuccessorStartsInert(schema) {
 	if (spawn.set && Object.prototype.hasOwnProperty.call(spawn.set, field)) return !values.includes(String(spawn.set[field]));
 	return !(spawn.carry ?? []).includes(field);
 }
+function fieldDrivenSpawnEvery(schema) {
+	const every = schema.spawn?.every;
+	if (!every || !require_schema.isFieldDrivenEvery(every)) return null;
+	return every;
+}
+function fieldDrivenFromFieldIsEnum(schema) {
+	const driven = fieldDrivenSpawnEvery(schema);
+	if (!driven) return true;
+	return schema.fields[driven.fromField]?.type === "enum";
+}
+function fieldDrivenMapCoversValues(schema) {
+	const driven = fieldDrivenSpawnEvery(schema);
+	if (!driven) return true;
+	const target = schema.fields[driven.fromField];
+	if (!target || target.type !== "enum" || target.values === void 0) return true;
+	const values = new Set(target.values);
+	const keys = Object.keys(driven.map);
+	return keys.length === values.size && keys.every((key) => values.has(key));
+}
+function fieldDrivenFromFieldCarried(schema) {
+	const driven = fieldDrivenSpawnEvery(schema);
+	if (!driven) return true;
+	const { carry, set } = schema.spawn ?? {};
+	if (set && Object.prototype.hasOwnProperty.call(set, driven.fromField)) {
+		const raw = set[driven.fromField];
+		if (raw === void 0 || raw === null || raw === "") return false;
+		return Object.prototype.hasOwnProperty.call(driven.map, String(raw));
+	}
+	return (carry ?? []).includes(driven.fromField);
+}
 var IngestSchemaZ = zod.z.object({
 	kind: zod.z.enum(require_schema.INGEST_KINDS),
 	url: zod.z.string().url(),
@@ -848,8 +897,8 @@ var CollectionSchemaZ = zod.z.object({
 	views: zod.z.array(CustomViewSchema).optional(),
 	notifyWhen: WhenSchema.optional(),
 	ingest: IngestSchemaZ.optional()
-}).refine((schema) => schema.singleton === void 0 || safeSlugName(schema.singleton) !== null, {
-	message: "schema `singleton` must be a valid item id (alphanumeric / hyphen / underscore, no path separators)",
+}).refine((schema) => schema.singleton === void 0 || safeRecordId(schema.singleton) !== null, {
+	message: "schema `singleton` must be a valid item id (alphanumeric / hyphen / underscore / interior dot, no `..` or path separators)",
 	path: ["singleton"]
 }).refine((schema) => schema.actions === void 0 || new Set(schema.actions.map((action) => action.id)).size === schema.actions.length, {
 	message: "schema `actions` must have unique `id`s",
@@ -893,6 +942,15 @@ var CollectionSchemaZ = zod.z.object({
 }).refine((schema) => spawnSuccessorStartsInert(schema), {
 	message: "`spawn` must leave the successor in a non-matching state (e.g. `set` the status to a pending value); seeding the predicate field to a matching value via `set`/`carry` would respawn forever",
 	path: ["spawn"]
+}).refine((schema) => fieldDrivenFromFieldIsEnum(schema), {
+	message: "`spawn.every.fromField` must name a top-level `enum` field declared in `fields`",
+	path: ["spawn"]
+}).refine((schema) => fieldDrivenMapCoversValues(schema), {
+	message: "`spawn.every.map` keys must exactly cover the `values` of the `enum` named by `fromField` (no missing or extra keys)",
+	path: ["spawn"]
+}).refine((schema) => fieldDrivenFromFieldCarried(schema), {
+	message: "`spawn.every.fromField` must appear in `spawn.carry`, or be written by `spawn.set` to a value present in `spawn.every.map`, so the successor keeps a resolvable recurrence interval",
+	path: ["spawn"]
 }).refine((schema) => schema.calendarField === void 0 || isDateLike(schema.fields[schema.calendarField]?.type), {
 	message: "schema `calendarField` must name a top-level `date` or `datetime` field declared in `fields`",
 	path: ["calendarField"]
@@ -940,6 +998,45 @@ function applyFeedSchemaDefaults(parsed, slug) {
 		dataPath: `data/feeds/${slug}`
 	};
 }
+/** The acceptance gates discovery applies AFTER `CollectionSchemaZ` parses,
+*  before a schema becomes a live collection:
+*
+*  - the `primaryKey` must be a declared field flagged `primary: true` —
+*    without the flag CollectionView renders the field editable, and a
+*    rename is silently pinned back to the URL itemId on save, so the user's
+*    edit is dropped with no error;
+*  - a `feed` schema must declare an `ingest` block (else it's a dead,
+*    non-refreshable card);
+*  - `dataPath` must resolve INSIDE the workspace.
+*
+*  Exported so `manageCollection`'s `putSchema` can run the SAME gates before
+*  it reports success — a schema that passes `CollectionSchemaZ` but fails one
+*  of these would otherwise write cleanly yet be skipped on the next discovery,
+*  hiding the collection (the exact failure that tool exists to prevent). */
+function acceptParsedSchema(schema, opts) {
+	const primaryField = schema.fields[schema.primaryKey];
+	if (!primaryField) return {
+		ok: false,
+		reason: `primaryKey '${schema.primaryKey}' is not one of the declared fields`
+	};
+	if (primaryField.primary !== true) return {
+		ok: false,
+		reason: `the primaryKey field '${schema.primaryKey}' must be flagged \`primary: true\``
+	};
+	if (opts.source === "feed" && !schema.ingest) return {
+		ok: false,
+		reason: "a feed schema must declare an `ingest` block"
+	};
+	const dataDir = resolveDataDir(schema.dataPath, opts.workspaceRoot);
+	if (dataDir === null) return {
+		ok: false,
+		reason: `dataPath '${schema.dataPath}' escapes the workspace`
+	};
+	return {
+		ok: true,
+		dataDir
+	};
+}
 async function loadOneCollection(skillsRoot, slug, source, workspaceRoot) {
 	const safeName = safeSlugName(slug);
 	if (safeName === null) return null;
@@ -976,31 +1073,14 @@ async function loadOneCollection(skillsRoot, slug, source, workspaceRoot) {
 		return null;
 	}
 	const schema = parsed.data;
-	const primaryField = schema.fields[schema.primaryKey];
-	if (!primaryField) {
-		log.warn("collections", "schema.json primaryKey not found in fields, skipping", {
-			slug: safeName,
-			primaryKey: schema.primaryKey
-		});
-		return null;
-	}
-	if (primaryField.primary !== true) {
-		log.warn("collections", "schema.json primaryKey field is not flagged primary: true, skipping", {
-			slug: safeName,
-			primaryKey: schema.primaryKey
-		});
-		return null;
-	}
-	if (source === "feed" && !schema.ingest) {
-		log.warn("collections", "feed schema.json has no `ingest` block, skipping", { slug: safeName });
-		return null;
-	}
-	const dataDir = resolveDataDir(schema.dataPath, workspaceRoot);
-	if (dataDir === null) {
-		log.warn("collections", "schema.json dataPath escapes workspace, skipping", {
+	const acceptance = acceptParsedSchema(schema, {
+		source,
+		workspaceRoot
+	});
+	if (!acceptance.ok) {
+		log.warn("collections", "schema.json rejected after validation, skipping", {
 			slug: safeName,
-			dataPath: schema.dataPath,
-			workspaceRoot
+			reason: acceptance.reason
 		});
 		return null;
 	}
@@ -1008,7 +1088,7 @@ async function loadOneCollection(skillsRoot, slug, source, workspaceRoot) {
 		slug: safeName,
 		source,
 		schema,
-		dataDir,
+		dataDir: acceptance.dataDir,
 		skillDir: node_path.default.join(skillsRoot, safeName)
 	};
 }
@@ -1277,6 +1357,18 @@ function matchesWhen(when, schema, item) {
 	const raw = item[completionField];
 	return raw !== void 0 && raw !== null && completionDoneValues.includes(String(raw));
 }
+/** 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. */
+function resolveEvery(every, sourceItem) {
+	if (!require_schema.isFieldDrivenEvery(every)) return every;
+	const raw = sourceItem[every.fromField];
+	if (raw === void 0 || raw === null || raw === "") return null;
+	return every.map[String(raw)] ?? null;
+}
 /** 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. */
@@ -1285,7 +1377,9 @@ function computeSuccessor(schema, sourceItem, sourceId) {
 	if (!spawn || !triggerField) return null;
 	const srcDate = parseCivil(sourceItem[triggerField]);
 	if (srcDate === null) return null;
-	const next = advanceTriggerDate(srcDate, spawn.every);
+	const every = resolveEvery(spawn.every, sourceItem);
+	if (every === null) return null;
+	const next = advanceTriggerDate(srcDate, every);
 	const nextId = successorId(sourceId, next);
 	const record = {};
 	for (const field of spawn.carry ?? []) if (Object.prototype.hasOwnProperty.call(sourceItem, field)) record[field] = sourceItem[field];
@@ -1297,6 +1391,27 @@ function computeSuccessor(schema, sourceItem, sourceId) {
 		record
 	};
 }
+/** Warn precisely about which of `computeSuccessor`'s two null causes fired
+*  (plan §5): an unparseable source trigger date (the original cause), or a
+*  field-driven `every` whose record value has no `map` entry (a record that
+*  predates a map/enum edit — discovery rejects this statically otherwise). */
+function logSpawnSkip(slug, triggerField, every, sourceItem, sourceId) {
+	if (parseCivil(sourceItem[triggerField]) === null) {
+		log.warn("collections", "spawn skipped: source trigger date unparseable", {
+			slug,
+			sourceId,
+			triggerField
+		});
+		return;
+	}
+	const fromField = require_schema.isFieldDrivenEvery(every) ? every.fromField : void 0;
+	log.warn("collections", "spawn skipped: no `every` mapping for frequency value", {
+		slug,
+		sourceId,
+		fromField,
+		value: fromField === void 0 ? void 0 : sourceItem[fromField]
+	});
+}
 /** 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
@@ -1308,11 +1423,7 @@ async function maybeSpawnSuccessor(slug, schema, dataDir, sourceItem, sourceId,
 	if (!matchesWhen(spawn.when, schema, sourceItem)) return;
 	const computed = computeSuccessor(schema, sourceItem, sourceId);
 	if (computed === null) {
-		log.warn("collections", "spawn skipped: source trigger date unparseable", {
-			slug,
-			sourceId,
-			triggerField: schema.triggerField
-		});
+		logSpawnSkip(slug, schema.triggerField, spawn.every, sourceItem, sourceId);
 		return;
 	}
 	if (matchesWhen(spawn.when, schema, computed.record)) {
@@ -1577,6 +1688,7 @@ async function deleteCustomView(collection, viewId, opts = {}) {
 exports.COMPUTED_TYPES = COMPUTED_TYPES;
 exports.CollectionSchemaZ = CollectionSchemaZ;
 exports.SCHEMA_FILE = SCHEMA_FILE;
+exports.acceptParsedSchema = acceptParsedSchema;
 exports.advanceTriggerDate = advanceTriggerDate;
 exports.buildActionSeedPrompt = buildActionSeedPrompt;
 exports.buildCollectionActionSeedPrompt = buildCollectionActionSeedPrompt;
@@ -1609,7 +1721,9 @@ exports.readItem = readItem;
 exports.readSkillTemplate = readSkillTemplate;
 exports.resolveCreateItemId = resolveCreateItemId;
 exports.resolveDataDir = resolveDataDir;
+exports.resolveEvery = resolveEvery;
 exports.resolveTemplatePath = resolveTemplatePath;
+exports.safeRecordId = safeRecordId;
 exports.safeSlugName = safeSlugName;
 exports.successorId = successorId;
 exports.toDetail = toDetail;