@mulmoclaude/core 0.27.0 → 0.29.0

package/dist/{discovery-BxbJy2VN.cjs → discovery-Bklck7Ck.cjs}

@@ -640,6 +640,18 @@ ${dataJson}
 ${templateText}`;
 }
 //#endregion
+//#region src/collection/server/backendAvailability.ts
+/** Thrown by a store when its engine or session cannot serve the request. */
+var BackendUnavailableError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "BackendUnavailableError";
+	}
+};
+function isBackendUnavailable(err) {
+	return err instanceof BackendUnavailableError;
+}
+//#endregion
 //#region src/collection/core/queryZ.ts
 /** Result-column aliases double as SQL identifiers and JSON keys — keep
 *  them to a conservative identifier charset so neither side needs
@@ -861,13 +873,23 @@ function decodeCsvRecordId(itemId) {
 *  (date-only when the clock is exactly UTC midnight, matching the `date`
 *  field contract), exotic DuckDB values → their string form. Pure +
 *  exported for unit tests. */
+/** `JSON.stringify` restricted to what a CSV cell can survive. Returns the
+*  serialised value, or `String(value)` when serialisation is impossible —
+*  losing the content of one cell is bad, failing the entire query is worse. */
+function safeJsonCell(value) {
+	try {
+		return JSON.stringify(value, (_key, entry) => typeof entry === "bigint" ? entry.toString() : entry) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
 function normalizeCsvValue(value) {
 	if (typeof value === "bigint") return value <= BigInt(Number.MAX_SAFE_INTEGER) && value >= BigInt(-Number.MAX_SAFE_INTEGER) ? Number(value) : value.toString();
 	if (value instanceof Date) {
 		const iso = value.toISOString();
 		return iso.endsWith("T00:00:00.000Z") ? iso.slice(0, 10) : iso;
 	}
-	if (value !== null && typeof value === "object") return String(value);
+	if (value !== null && typeof value === "object") return safeJsonCell(value);
 	return value;
 }
 /** One raw DuckDB row → a CollectionItem, or null when the key cell is
@@ -878,10 +900,11 @@ function normalizeCsvValue(value) {
 function csvRowToItem(row, primaryKey) {
 	const normalized = Object.fromEntries(Object.entries(row).map(([key, value]) => [key, normalizeCsvValue(value)]));
 	const rawKey = normalized[primaryKey];
-	if (rawKey === null || rawKey === void 0 || String(rawKey) === "") return null;
+	const keyText = require_ids.fieldTextOrNull(rawKey);
+	if (keyText === null || keyText === "") return null;
 	return {
 		...normalized,
-		[primaryKey]: encodeCsvRecordId(String(rawKey))
+		[primaryKey]: encodeCsvRecordId(keyText)
 	};
 }
 /** Dedupe by record id, LAST row wins (matches `csvRead`'s last-match
@@ -1039,7 +1062,7 @@ async function duckDbInstance() {
 		return await instancePromise;
 	} catch (err) {
 		instancePromise = null;
-		throw new Error(`DuckDB is unavailable on this host (@duckdb/node-api failed to load: ${String(err)}) — dataSource collections cannot be read`);
+		throw new BackendUnavailableError(`DuckDB is unavailable on this host (@duckdb/node-api failed to load: ${String(err)}) — dataSource collections cannot be read`);
 	}
 }
 async function queryCsv(sql, params) {
@@ -1124,6 +1147,89 @@ async function csvRunQuery(absPath, primaryKey, query, workspaceRoot) {
 	return (await queryCsv(sql, [utf8Path, ...params])).map((row) => Object.fromEntries(Object.entries(row).map(([key, value]) => [key, normalizeCsvValue(value)])));
 }
 //#endregion
+//#region src/collection/server/watchFs.ts
+/** An atomic file replace (editor save, `mv` over the target) surfaces as
+*  2-3 events. Collapse them so one user action reports one change. */
+var REPLACE_DEBOUNCE_MS = 300;
+/** The path to hand `watch()`, with Windows 8.3 short names resolved away.
+*
+*  ReadDirectoryChangesW reports filenames against the LONG path, but a watch
+*  opened on a short path (`C:\Users\RUNNER~1\…` — what `os.tmpdir()` returns
+*  on GitHub's Windows runners) keeps the short form. libuv's
+*  `assert(!_wcsnicmp(filename, dir, dirlen))` in `src/win/fs-event.c` then
+*  aborts the PROCESS on the first event — a native assert, so neither
+*  `watcher.on("error")` nor a try/catch can contain it.
+*
+*  POSIX is deliberately left alone: `realpath` there also collapses symlinks
+*  (`/var` → `/private/var` on macOS), which we neither need nor want to
+*  change. A failure falls back to the original path — worst case we are no
+*  worse off than before. */
+function watchablePath(dir) {
+	if (process.platform !== "win32") return dir;
+	try {
+		return node_fs.realpathSync.native(dir);
+	} catch {
+		return dir;
+	}
+}
+/** Watch `dir`, reporting each accepted filename. `accept` decides what is
+*  noise; a null filename always passes (the platform didn't tell us which
+*  file, so the caller must assume the worst). */
+async function watchDirectory(dir, accept, onHit) {
+	try {
+		await (0, node_fs_promises.mkdir)(dir, { recursive: true });
+		const watcher = (0, node_fs.watch)(watchablePath(dir), { persistent: false }, (_eventType, rawFilename) => {
+			const filename = rawFilename === null ? null : String(rawFilename);
+			if (filename !== null && !accept(filename)) return;
+			onHit(filename);
+		});
+		watcher.on("error", (err) => {
+			log.warn("collections", "fs watch error", {
+				dir,
+				error: String(err)
+			});
+		});
+		return { close: () => watcher.close() };
+	} catch (err) {
+		log.warn("collections", "fs watch start failed", {
+			dir,
+			error: String(err)
+		});
+		return null;
+	}
+}
+/** Watch the single file `absPath` by watching its PARENT directory, so an
+*  atomic replace can't strand the watch on a dead inode. `alsoAccept`
+*  widens the filter beyond the exact basename (sqlite's `-wal`/`-journal`
+*  sidecars). Reports are debounced: one replace, one call. */
+async function watchSingleFile(absPath, alsoAccept, onChange) {
+	const dir = node_path.default.dirname(absPath);
+	const base = node_path.default.basename(absPath);
+	let timer = null;
+	const fire = () => {
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(() => {
+			timer = null;
+			onChange();
+		}, REPLACE_DEBOUNCE_MS);
+		timer.unref?.();
+	};
+	const handle = await watchDirectory(dir, (filename) => filename === base || alsoAccept(base, filename), fire);
+	if (!handle) return null;
+	return { close: () => {
+		if (timer) clearTimeout(timer);
+		timer = null;
+		handle.close();
+	} };
+}
+/** An `FsWatchHandle` as a bare unsubscribe — `null` straight through, so an
+*  unarmed watch stays distinguishable from an armed one. Lives here rather
+*  than beside the store contract so both `store.ts` and the backends it
+*  registers can reach it without importing each other. */
+function closerFor(handle) {
+	return handle === null ? null : () => handle.close();
+}
+//#endregion
 //#region src/collection/server/storePage.ts
 /** Project `fields` (+ the primary key, always) out of each record. Thin
 *  server-typed alias over the shared isomorphic `projectRecordFields`
@@ -1151,7 +1257,7 @@ var sqliteModule = null;
 function loadSqlite() {
 	sqliteModule ??= import("node:sqlite").then((mod) => mod, (err) => {
 		sqliteModule = null;
-		throw new Error(`sqlite storage needs the node:sqlite module (Node.js >= 22.5) — this runtime cannot load it: ${String(err)}`);
+		throw new BackendUnavailableError(`sqlite storage needs the node:sqlite module (Node.js >= 22.5) — this runtime cannot load it: ${String(err)}`);
 	});
 	return sqliteModule;
 }
@@ -1388,7 +1494,8 @@ function sqliteStoreFor(collection, opts) {
 		delete: (itemId) => sqliteDelete(file, itemId, {
 			workspaceRoot: root(),
 			slug
-		})
+		}),
+		watch: async (onChange) => closerFor(await watchSingleFile(file, (base, name) => name.startsWith(base), () => onChange({ kind: "collection" })))
 	};
 }
 //#endregion
@@ -1398,8 +1505,8 @@ function sqliteStoreFor(collection, opts) {
 *  is filesystem-dependent; paging needs determinism. */
 function sortByRecordId(items, primaryKey) {
 	return [...items].sort((left, right) => {
-		const leftId = String(left[primaryKey] ?? "");
-		const rightId = String(right[primaryKey] ?? "");
+		const leftId = require_ids.fieldText(left[primaryKey]);
+		const rightId = require_ids.fieldText(right[primaryKey]);
 		if (leftId < rightId) return -1;
 		return leftId > rightId ? 1 : 0;
 	});
@@ -1435,7 +1542,8 @@ function csvStoreFor(collection, opts) {
 		list: () => listAll().then((result) => result.items),
 		page: (pageOpts = {}) => listAll().then((result) => pageFromFullRead(result.items, pageOpts, key, result.truncated)),
 		read: (itemId) => file === void 0 ? Promise.resolve(null) : csvRead(file, key, itemId, opts.workspaceRoot),
-		query: (query) => file === void 0 ? Promise.resolve([]) : csvRunQuery(file, key, query, opts.workspaceRoot)
+		query: (query) => file === void 0 ? Promise.resolve([]) : csvRunQuery(file, key, query, opts.workspaceRoot),
+		...file === void 0 ? {} : { watch: async (onChange) => closerFor(await watchSingleFile(file, () => false, () => onChange({ kind: "collection" }))) }
 	};
 }
 /** The classic file store over `<dataDir>/<itemId>.json` records. */
@@ -1458,7 +1566,11 @@ function fileStoreFor(collection, opts) {
 			...ioOpts,
 			refuseOverwrite: writeOpts.refuseOverwrite
 		}),
-		delete: (itemId) => deleteItem(collection.dataDir, itemId, ioOpts)
+		delete: (itemId) => deleteItem(collection.dataDir, itemId, ioOpts),
+		watch: async (onChange) => closerFor(await watchDirectory(collection.dataDir, (name) => name.endsWith(".json") && !name.startsWith("."), (filename) => onChange(filename === null ? { kind: "collection" } : {
+			kind: "item",
+			itemId: filename.slice(0, -5)
+		})))
 	};
 }
 var storeFactories = /* @__PURE__ */ new Map([
@@ -2034,7 +2146,8 @@ function fieldDrivenFromFieldCarried(schema) {
 	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));
+		const key = require_ids.fieldTextOrNull(raw);
+		return key !== null && Object.prototype.hasOwnProperty.call(driven.map, key);
 	}
 	return (carry ?? []).includes(driven.fromField);
 }
@@ -2509,6 +2622,12 @@ function toDetail(collection) {
 	};
 }
 //#endregion
+Object.defineProperty(exports, "BackendUnavailableError", {
+	enumerable: true,
+	get: function() {
+		return BackendUnavailableError;
+	}
+});
 Object.defineProperty(exports, "CollectionQueryZ", {
 	enumerable: true,
 	get: function() {
@@ -2659,6 +2778,12 @@ Object.defineProperty(exports, "getWorkspaceRoot", {
 		return getWorkspaceRoot;
 	}
 });
+Object.defineProperty(exports, "isBackendUnavailable", {
+	enumerable: true,
+	get: function() {
+		return isBackendUnavailable;
+	}
+});
 Object.defineProperty(exports, "isContainedInRoot", {
 	enumerable: true,
 	get: function() {
@@ -2852,4 +2977,4 @@ Object.defineProperty(exports, "writeItem", {
 	}
 });
 
-//# sourceMappingURL=discovery-BxbJy2VN.cjs.map
+//# sourceMappingURL=discovery-Bklck7Ck.cjs.map