mikser-io 9.61.0 → 9.62.0

package/CLAUDE.md

@@ -195,6 +195,11 @@ brevity.
   over ids, not the matched paths, so a file appearing later still
   invalidates. Paths resolve against `options.workingFolder` — the
   render-time `runtime` is a per-render projection with no options on it.
+  The "this file has no entity" warning reads `options.sourceFolders` —
+  the set useSource records as it registers each collection — NOT a list
+  of folder names written in the plugin. A hardcoded list misses every
+  collection a project registers through `sources()`, which produced 63
+  false warnings per build on a real site.
 - `render.js` / `postprocess.js` — Piscina worker entry points AND the
   default-export functions the INLINE/SERIAL dispatcher calls directly.
   Each receives entity + options + config + state; the WORKER path also
@@ -228,7 +233,14 @@ brevity.
   - `{ name, options, postprocess, output?, setup?, teardown? }` →
     postprocessor descriptor; stored in `runtime.postprocessors`.
   Strings produce a v9 migration error pointing at the new shape.
-- `manager.js` — file watching (chokidar) and cron scheduling.
+- `manager.js` — file watching (chokidar) and cron scheduling. `watch()`
+  turns file events into SYNC events — it is how a source folder becomes
+  entities, so pointing it at the output folder feeds output back in as
+  input. `watchFolder(folder, handler, options)` is the primitive without
+  that meaning, for a plugin that only needs to know bytes changed; it
+  carries the shared junk filter and `followSymlinks: true`, which is
+  load-bearing because the files plugin serves by symlinking into the
+  output folder.
 - `source.js` — `useSource` codifies the folder-of-files pattern.
 - `tools.js` — tool registry. `registerTool(name, {description,
   inputSchema}, handler)` / `toolNames()` / `toolSchema()` / `invokeTool()`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.61.0",
+  "version": "9.62.0",
   "description": "A mixer for content: entities in, configurable render pipelines, outputs of any kind. Static sites are the canonical recipe, not the definition — the same engine renders PDFs, emails and whatever a renderer plugin produces. Files are the source of truth, every lifecycle phase is observable, and the build graph is queryable by an agent.",
   "main": "index.js",
   "exports": {

package/src/database/index.js

@@ -331,9 +331,9 @@ export function createSqliteDatabase({
                 configChanged ? 'config' : 'schema version')
         } else if (configChanged && !(recorded && recorded !== version)) {
             logger?.warn(
-                'Config changed since the last run. Wiping the cache and rebuilding from sources ' +
-                '(files are the source of truth — no source data is affected). Note this tracks the ' +
-                'bytes of %s only: a change in a module it imports is not seen.',
+                'Config changed since the last run. Wiping the cache and rebuilding from sources '
+                + '(files are the source of truth — no source data is affected). The stamp covers %s and '
+                + 'every local module it imports; `--json` reports exactly which files under `config.files`.',
                 runtime.options.config,
             )
         }

package/src/manager.js

@@ -90,6 +90,33 @@ export async function deletedHook(name, context) {
 // `ignored` and a function is the one form that has stayed stable.
 const ignoreJunk = (filePath) => /[/\\]\./.test(filePath) || junkFilter()(filePath)
 
+// Watch a folder, with mikser's own settings and none of its lifecycle.
+//
+// `watch()` below turns file events into SYNC events — it is how a source
+// folder becomes entities, and pointing it at anything else feeds output back
+// in as input. A plugin that only wants to know when bytes changed needs the
+// watching without the meaning, and was otherwise reaching for chokidar
+// directly: a second copy of a dependency the engine already has, and a second
+// junk filter that would drift from this one.
+//
+// followSymlinks matters more than it looks. The files plugin serves a file by
+// symlinking it from the source folder into the output folder, so a watcher on
+// the output folder that did not follow links would see the link created once
+// and never hear about the file again — every stylesheet edit silently
+// invisible to anything watching what is served.
+export function watchFolder(folder, handler, options = {}) {
+    return chokidar
+        .watch(folder, {
+            interval: 1000,
+            binaryInterval: 3000,
+            ignored: ignoreJunk,
+            ignoreInitial: true,
+            followSymlinks: true,
+            ...options,
+        })
+        .on('all', (event, fullPath) => handler(event, fullPath))
+}
+
 export function watch(name, folder, options = { interval: 1000, binaryInterval: 3000, ignored: ignoreJunk, ignoreInitial: true }) {
     if (runtime.options.watch !== true) return
 

package/src/plugins/render/file.js

@@ -67,16 +67,27 @@ function entityIdFor(workingFolder, resolved) {
 // nothing to track" read identically from a template. Said once per path.
 const warnedOutside = new Set()
 function warnIfUntrackable(options, resolved, logger) {
-    const folders = ['documentsFolder', 'filesFolder', 'assetsFolder', 'resourcesFolder', 'dataFolder']
-        .map(key => options?.[key]).filter(Boolean)
-    if (!folders.length) return  // nothing configured to compare against
+    // Every folder whose files become entities, as recorded by useSource when
+    // it registered them — NOT a list written here.
+    //
+    // The first version of this hardcoded five content folders, and a project
+    // registering its own collections through sources() has more than five. On
+    // lmed that meant 63 warnings per build, one for every stylesheet and
+    // script, all of them tracked correctly and every one of them saying the
+    // opposite. Which is worse than not warning: 63 spurious lines a build
+    // teaches you to filter the channel, and the filtered-out line is the real
+    // one.
+    const folders = Object.values(options?.sourceFolders ?? {})
+    // Nothing registered yet means nothing can be concluded. Silence is the
+    // only honest answer — the previous shape guessed instead.
+    if (!folders.length) return
     if (folders.some(folder => !path.relative(folder, resolved).startsWith('..'))) return
     if (warnedOutside.has(resolved)) return
     warnedOutside.add(resolved)
     logger?.warn?.({ code: 'untracked-file-read' },
-        'A template read %s, which is outside every content folder — so it has no entity, nothing watches it, '
-        + 'and changing it will NOT rebuild the pages that read it. Move it under a content folder if that '
-        + 'matters, or pass { track: false } to say the staleness is intended.', resolved)
+        'A template read %s, which is outside every folder mikser takes entities from — so it has no entity, '
+        + 'nothing watches it, and changing it will NOT rebuild the pages that read it. Register the folder '
+        + 'with sources() if that matters, or pass { track: false } to say the staleness is intended.', resolved)
 }
 
 export function load({ runtime, options, track, logger }) {

package/src/source.js

@@ -328,6 +328,18 @@ export function useSource(core, options) {
             ? folder
             : path.join(runtime.options.workingFolder, folder)
         runtime.options[`${collection}Folder`] = absFolder
+        // The authoritative set of folders whose files become entities.
+        //
+        // `<collection>Folder` above is the per-collection accessor and reads
+        // like one; this is the LIST, which is a different question and the
+        // one anything asking "could a file here be tracked?" needs. Deriving
+        // it by scanning options for a `*Folder` suffix would sweep up
+        // workingFolder, runtimeFolder and outputFolder, and hand-listing the
+        // content ones misses every collection a project registers itself —
+        // which is exactly how the file helpers came to warn 63 times a build
+        // about files they were tracking correctly.
+        runtime.options.sourceFolders ??= {}
+        runtime.options.sourceFolders[collection] = absFolder
         logger.debug('%s folder: %s', cap, absFolder)
 
         await mkdir(absFolder, { recursive: true })