mikser-io 11.12.1 → 11.14.0

package/README.md

@@ -245,7 +245,7 @@ npm install mikser-io
 ```bash
 npx mikser              # one-shot build
 npx mikser --watch      # incremental dev loop
-npx mikser --server     # build + serve on a free port (or --server 3001 to name one)
+npx mikser --server     # build + serve on the port it used last (or --server 3001 to name one)
 ```
 
 For a working starter — config with a real plugin set, sample `documents/`, expected output — see [Getting Started](./docs/getting-started.md). Or skip straight to "add mikser to this app" via the [Claude Code plugin](#built-for-ai-assisted-development) above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "11.12.1",
+  "version": "11.14.0",
   "files": [
     "app.js",
     "index.js",

package/src/manager.js

@@ -21,12 +21,52 @@ const tasks = []
 // Not done inside runtime.process(): the first cycle's `gated` count is
 // recorded during import, which runs BEFORE process(), so resetting there
 // would wipe it out of a one-shot build's report.
+// File events that arrived while a cycle was running, waiting for it to end.
+//
+// Keyed by nothing and deduplicated by nothing: a file touched three times
+// mid-cycle is three entries, and the source gate collapses them — it compares
+// checksums and skips what has not moved. Deduplicating here would mean
+// deciding that a CREATE and a DELETE for one path cancel out, which they do
+// not.
+const pending = []
+
+// Replay them, now that the cycle is over.
+//
+// Each delivery journals and schedules on its own, exactly as it would have
+// if it had arrived a moment later — which, as far as the engine is now
+// concerned, it did.
+async function flushPending() {
+    if (!pending.length || runtime.processing) return
+    const waiting = pending.splice(0, pending.length)
+    for (const { hook, name, relativePath, fullPath } of waiting) {
+        try {
+            await hook(name, { relativePath })
+        } catch (err) {
+            reportWatchFailure(err, fullPath)
+        }
+    }
+}
+
+// Every cycle ends here, whichever started it — the watcher, `start()`, or a
+// forwarded rebuild — so this is the one place that catches them all.
+//
+// `cycled` and not `onFinalized`: a finalize hook runs INSIDE the cycle, with
+// `runtime.processing` still true, so the flush would defer the events it was
+// called to deliver and the queue would sit there until something unrelated
+// moved. Measured — the first version of this fix did exactly that and
+// imported nothing.
+runtime.hooks.cycled.push(flushPending)
+
 function scheduleProcess() {
     clearTimeout(runtime.engine.processTimeout)
     runtime.engine.processTimeout = setTimeout(async () => {
         await warnConfigStale()
         resetReport()
-        runtime.process()
+        await runtime.process()
+        // A cancelled cycle runs no finalize hooks, so the flush above never
+        // fires for it and anything that arrived mid-cycle would wait for a
+        // later one that may never come.
+        await flushPending()
     }, 1000)
 }
 
@@ -223,6 +263,33 @@ export function watch(name, folder, options = {}) {
     // not the process.
     const deliver = async (hook, fullPath) => {
         const relativePath = fullPath.replace(`${folder}/`, '')
+        // A file that changes WHILE a cycle is running belongs to the next
+        // one, so it waits.
+        //
+        // Delivered immediately, the sync journals the entity behind a cycle
+        // that has already passed its source gate and its dispatch. Later
+        // phases still walk the journal and the catalog is updated, so the
+        // change is half-applied — and then onFinalized clears the journal,
+        // so the next cycle starts with nothing to do and the entity never
+        // renders. No error anywhere; the build is green twice.
+        //
+        // Reported from production, and it is the shape a plugin reaches for
+        // on purpose: one that re-derives pages by touching its sources from
+        // `onProcess`. 47 PDFs touched, every mtime updated, two cycles
+        // completed, not one file re-imported. Worse than a missed rebuild,
+        // because the plugin had already recorded the work as handled — so
+        // nothing retried, and 46 pages served four-day-old prices with
+        // nothing in the log to say so.
+        //
+        // Deferring is the honest reading of what a cycle is: it processes
+        // the state as of its start. The alternative — keeping those journal
+        // entries for the next cycle — does not work, because the engine's
+        // own later walks legitimately consume them first; measured before
+        // choosing this.
+        if (runtime.processing) {
+            pending.push({ hook, name, relativePath, fullPath })
+            return
+        }
         try {
             await hook(name, { relativePath })
         } catch (err) {

package/src/runtime.js

@@ -60,6 +60,11 @@ const runtime = {
         finalized: [],
         sync: [],
         completed: [],
+        // Fires once a cycle is fully over and `processing` is false — see
+        // process(). The watcher uses it to replay file events it held back
+        // while the cycle ran; anything that must act BETWEEN cycles rather
+        // than inside one belongs here.
+        cycled: [],
     },
 
     // What each phase COST, not only what it did.
@@ -190,6 +195,11 @@ const runtime = {
             await this.cancel()
         }
         await this.mutex.use(async () => {
+            // True for the whole cycle, including the gaps between phases —
+            // `phase` goes null between them, so it cannot answer "is a cycle
+            // running". The watcher reads this to decide whether a file event
+            // belongs to this cycle or the next one; see src/manager.js.
+            this.processing = true
             try {
                 this.abortController = new AbortController()
                 const { signal } = this.abortController
@@ -205,8 +215,16 @@ const runtime = {
                 this.phase = 'cancelled'
                 for (let hook of this.hooks.cancelled) await hook()
                 this.phase = null
+            } finally {
+                this.processing = false
             }
         })
+
+        // After the mutex, so `processing` is already false and a hook that
+        // starts work of its own is not told a cycle is still running. Inside
+        // the cycle — at onFinalized, say — it would be, which is exactly the
+        // mistake this placement exists to avoid.
+        for (const hook of this.hooks.cycled) await hook()
     },
 
     async render(signal) {

package/src/server.js

@@ -24,6 +24,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { networkInterfaces } from 'node:os'
 import { createServer } from 'node:net'
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
 
 import runtime from './runtime.js'
 import { useLogger } from './engine/index.js'
@@ -84,23 +85,80 @@ export function requestedPort(server) {
     return Number.isInteger(asked) && asked >= 0 ? asked : DEFAULT_PORT
 }
 
+// Where the LAST USED port is remembered, per working folder.
+//
+// A bare `--server` picks a free port, which solved two people colliding on
+// 3001 and introduced a smaller annoyance: the number changed on every
+// restart, so a bookmark, a tab, a terminal scrollback and anything else
+// holding the old one went stale several times an afternoon.
+//
+// Last USED, not last auto-chosen: `--server 3002` once and a bare `--server`
+// after it keeps 3002. Naming a port is the strongest statement available
+// about which one is wanted, and forgetting it the moment the flag is dropped
+// would make the memory useless exactly where it is most deliberate.
+//
+// The runtime folder is the right lifetime. It is per working folder, so two
+// projects still get different ports and two users still do not collide; it
+// survives a restart, which is the whole point; and `--clear` removes the
+// cache database rather than this, so asking for a cold rebuild does not also
+// move the server. Deleting the folder forgets it, which is the correct
+// answer to "give me a different port".
+const PORT_FILE = 'server-port'
+
+const portFile = () => path.join(runtime.options.runtimeFolder ?? '.', PORT_FILE)
+
+async function rememberedPort() {
+    try {
+        const port = Number((await readFile(portFile(), 'utf8')).trim())
+        // A file someone edited by hand, or a half-written one. Anything that
+        // is not a usable port is treated as no preference rather than as an
+        // error — the fallback is exactly what this feature replaced.
+        return Number.isInteger(port) && port > 0 && port < 65536 ? port : null
+    } catch {
+        return null
+    }
+}
+
+async function rememberPort(port) {
+    try {
+        await mkdir(path.dirname(portFile()), { recursive: true })
+        await writeFile(portFile(), `${port}\n`)
+    } catch (err) {
+        // Not worth failing a build over. The cost is the port moving again
+        // next time, which is where this started.
+        useLogger()?.debug?.('Could not remember the server port: %s', err.message)
+    }
+}
+
 // A port nothing is listening on, according to the OS.
 //
-// Binds to 0, reads what it was given, and lets it go. There is a gap between
-// releasing it and the real listen below, so this is a strong preference
-// rather than a reservation — if something takes the port in between, the
-// EADDRINUSE handler further down says so plainly instead of pretending.
-// Narrow enough not to matter on the machine this exists for; not narrow
-// enough to claim it cannot happen.
-export async function freePort() {
-    return new Promise((resolve, reject) => {
+// Binds to `preferred` when one is given and takes it if it is free —
+// which is how a restart keeps the port it had. Falls back to binding 0,
+// which is the OS choosing.
+//
+// Either way it lets the port go again. There is a gap between releasing it
+// and the real listen below, so this is a strong preference rather than a
+// reservation — if something takes the port in between, the EADDRINUSE
+// handler further down says so plainly instead of pretending. Narrow enough
+// not to matter on the machine this exists for; not narrow enough to claim it
+// cannot happen.
+export async function freePort(preferred = 0) {
+    const bind = (port) => new Promise((resolve) => {
         const probe = createServer()
-        probe.once('error', reject)
-        probe.listen(0, () => {
-            const { port } = probe.address()
-            probe.close(() => resolve(port))
+        probe.once('error', () => resolve(null))
+        probe.listen(port, () => {
+            const { port: got } = probe.address()
+            probe.close(() => resolve(got))
         })
     })
+
+    if (preferred) {
+        const kept = await bind(preferred)
+        if (kept) return kept
+    }
+    const found = await bind(0)
+    if (found) return found
+    throw new Error('Could not find a free port to listen on')
 }
 
 // Wire the server lifecycle hooks. Called by engine.js's setup() AFTER
@@ -143,11 +201,29 @@ export function setupServer() {
             // So it becomes a real number as early as it can, and everything
             // downstream sees exactly what it would have seen from
             // `--server <that number>`.
-            const found = await freePort()
+            const kept = await rememberedPort()
+            const found = await freePort(kept)
             runtime.options.server = found
             runtime.options.port = found
-            logger.info('Server port: %d (nothing named one, so this is a free port)', found)
+            // Written BEFORE it is announced. Anything reading the log and
+            // acting on the port — a wrapper script, a test harness, a person
+            // with a fast Ctrl-C — can otherwise beat the write and leave the
+            // port unremembered, which looks exactly like the feature not
+            // working.
+            await rememberPort(found)
+            logger.info(found === kept
+                ? 'Server port: %d (the same one as last time)'
+                : kept
+                    ? 'Server port: %d (last time it was %d, which is taken)'
+                    : 'Server port: %d (nothing named one, so this is a free port)', found, kept)
+        }
+        // A NAMED port is remembered too — that is what "last used" means,
+        // and it is the case where the number was chosen on purpose. The auto
+        // branch above has already written its own.
+        if (requestedPort(runtime.options.server) !== 0) {
+            await rememberPort(runtime.options.port)
         }
+
         logger.debug('Server starting on port %d', runtime.options.port)
 
         // Trust-proxy: when mikser is behind a reverse proxy (nginx,