mikser-io 9.73.0 → 9.75.0

package/app.js

@@ -49,8 +49,6 @@ function locate(argv) {
         longRunning,
         workingFolder: value('--working-folder', '-i') ?? '.',
         config: value('--config', '-c') ?? 'mikser.config.js',
-        // Commander's negated form: `attach` is true unless --no-attach said so.
-        attach: has('--no-attach') ? false : true,
         request,
     }
 }
@@ -62,18 +60,17 @@ async function main() {
     // A second server or watcher is the hazard this whole surface exists to
     // remove, and it is the one shape that cannot be answered by forwarding.
     // So it stops, rather than silently doing something else.
-    if (where.attach !== false && where.longRunning) {
+    if (where.longRunning) {
         if (await isInstanceLive(workingFolder)) {
             process.stderr.write(
                 'mikser: another mikser is already running in this folder, and a server or watcher cannot be '
                 + 'forwarded to it — it would have to open a port on your behalf.\n'
-                + 'Stop that one, or pass --no-attach to run a second engine here (two engines share the '
-                + 'catalogue and the output tree, with no lock between them).\n')
+                + 'Stop that one first.\n')
             process.exit(1)
         }
     }
 
-    if (where.attach !== false && !where.longRunning) {
+    if (!where.longRunning) {
         const code = await forward({
             workingFolder,
             config: path.resolve(where.workingFolder, where.config),

package/docs/diagnostics.md

@@ -760,8 +760,9 @@ Three things it refuses or reports rather than guessing:
   to *become* the instance, which is not something a running one can do for
   you — it would have to open a port in your process. They exit 1 and say so,
   rather than building and leaving nothing on the port.
-- **A folder held by someone else.** `--no-attach` runs a private engine
-  anyway — for checking that a cold start works — and says the folder is held.
+There is no opt-out. A flag for running a second engine on a held folder
+only ever enabled the accident this surface prevents, and stopping the
+instance serves every case it was reached for.
 
 `--tool`, `--tools`, `--verify` and `--explain` forward as well, and for a
 different reason than builds do. They only read, so running one locally never

package/package.json

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

package/src/engine.js

@@ -386,7 +386,6 @@ export async function setup(options) {
         runtime.engine.commander?.version(packageInfo.version)
             .option('-i --working-folder <folder>', 'set mikser working folder', './')
             .option('-c --config <file>', 'set mikser mikser.config.js location', './mikser.config.js')
-            .option('--no-attach', 'start a private engine instead of forwarding to the one already running here')
             .option('-m --mode <mode>', 'set mikser runtime mode', 'development')
             .option('-r --clear', 'clear current state before execution', false)
             .option('-o --output-folder <folder>', 'set mikser output folder relative to working folder', 'out')

package/src/instance.js

@@ -19,10 +19,12 @@
 // new to learn and no watermark to reason about — which matters, because a
 // design that needs discipline from the caller is the one that gets violated.
 //
-// `--no-attach` opts out, for when a fresh process IS the point: checking that
-// a cold start works, that startup ordering hides nothing. Named for what it
-// switches off rather than for a property of the process — the default is to
-// attach, and the flag should say which behaviour is being declined.
+// There is no opt-out. A flag for "run a second engine here anyway" only ever
+// enabled the accident this file exists to prevent — two engines sharing one
+// catalogue and one output tree with no lock between them — and no caller had
+// a reason to want it that a stopped instance would not serve better. An
+// option whose only use is the wrong one is not an escape hatch, it is a trap
+// with a name.
 
 import net from 'node:net'
 import { createHash } from 'node:crypto'
@@ -280,7 +282,7 @@ function refuseConfig(socket, request, wrongConfig) {
         type: 'refused',
         reason: `this instance is running ${wrongConfig}, and you asked for ${path.resolve(request.config)}.`,
         detail: 'Answering would use the wrong config — the accident this refusal exists to prevent. '
-            + 'Stop that instance, or pass --no-attach to run your own.',
+            + 'Stop that instance and run this again.',
     })
 }
 
@@ -341,7 +343,6 @@ async function serveBuild(socket, request, logger) {
 export function serveInstance() {
     onLoaded(async () => {
         if (!runtime.options.watch && !runtime.options.server) return
-        if (runtime.options.attach === false) return
         const logger = runtime.engine?.logger
         const endpoint = socketPath(runtime.options.workingFolder)
 
@@ -402,53 +403,7 @@ export function serveInstance() {
 
 // Say so when a private engine is starting in a folder someone else holds.
 //
-// The local counterpart of the rule already written down for deployments —
-// "never run a one-shot mikser command against the deployment" — which existed
-// because there was no alternative. There is one now, so this covers what is
-// left: --no-attach, and the report-only runs that stay local by design.
-//
-// A warning rather than a refusal. --no-attach is how you deliberately check
-// that a cold start works, and refusing it would take away the escape hatch
-// this design depends on having.
-export async function warnIfHeld({ workingFolder, attached }) {
-    const endpoint = socketPath(workingFolder)
-    if (process.platform !== 'win32' && !existsSync(endpoint)) return false
-
-    const live = await new Promise((resolve) => {
-        const probe = net.connect(endpoint)
-        const done = (answer) => { try { probe.destroy() } catch { /* already gone */ } resolve(answer) }
-        probe.on('connect', () => done(true))
-        probe.on('error', () => done(false))
-        setTimeout(() => done(false), 250).unref?.()
-    })
-    if (!live) return false
-
-    const logger = runtime.engine?.logger
-    const message = attached === false
-        ? 'Another mikser is already running in this folder, and --no-attach means this one will not talk to '
-          + 'it. Two engines share the catalogue and the output tree with no lock between them; a --clear from '
-          + 'either is what produces a cold rebuild that renders nothing.'
-        : 'Another mikser is already running in this folder. This command reads and does not write, so it is '
-          + 'safe — but it may see a catalogue mid-cycle.'
-    logger?.warn?.({ code: 'instance-already-running' }, message)
-    return true
-}
-
 // Registered at setup so both halves are wired from one call.
 export function instanceControl() {
     serveInstance()
-    onLoaded(async () => {
-        // Only --no-attach reaches this now. Everything else either forwarded
-        // (a build, a report) or refused before setup ran (a second server or
-        // watcher), so a process that is still here and not attaching is one
-        // that deliberately opted out — and that is exactly the case worth
-        // saying something about, long-running or not. The earlier gate
-        // skipped watch and server, which excluded `--no-attach --server`:
-        // the very command that puts two engines on one folder.
-        if (runtime.options.attach !== false) return
-        await warnIfHeld({
-            workingFolder: runtime.options.workingFolder,
-            attached: false,
-        })
-    })
 }

package/src/manifest.js

@@ -1289,7 +1289,36 @@ onFinalize(async () => {
     // That made "resolve the collision by deleting the stub" delete the
     // homepage, which is the opposite of what the operator asked for and the
     // exact operation the new collision reporting invites.
+    // Destinations THIS cycle's surviving renders just wrote.
+    //
+    // Their snapshot rows are not inserted until 3c below, so the
+    // by-destination query cannot see them — the same blind spot 2a already
+    // compensates for in the other direction ("recorded snapshots only
+    // describe PRIOR cycles").
+    //
+    // Without this, renaming a source's extension unlinks the output the new
+    // entity just wrote. `index.md` → `index.yml` keeps the entity NAME and
+    // the destination but changes the id, so one cycle carries a DELETE for
+    // the old id and a RENDER for the new one. The render writes the page,
+    // the delete stages the same destination, nothing surviving claims it
+    // yet, and the file goes — with `Rendered: 1`, a green build and no
+    // warning. A second build does not fix it (nothing changed), nor does
+    // touch (the input hash is the same); only a real content edit re-renders
+    // it. Only --verify ever said so, and renaming an extension is the most
+    // common action there is during a migration.
+    const claimedByThisCycle = new Set()
+    for (const { entity } of renderedEntries) {
+        if (deleted.has(entity.id) || (entity.parent && deleted.has(entity.parent))) continue
+        if (entity.destination) claimedByThisCycle.add(entity.destination)
+    }
+
     for (const { destination, reason } of filesToUnlink) {
+        // Written this cycle by an entity that is staying. Keep it, and say
+        // nothing: the snapshot recorded at 3c is this render's own, so there
+        // is no staleness to report — unlike the surviving-snapshot case
+        // below, where the bytes belong to the entity that went away.
+        if (claimedByThisCycle.has(destination)) continue
+
         // "Still claimed" means by something that SURVIVES this pass. The
         // ids going away here are not just the deleted entities: pagination
         // children staged above are removed too, and counting a child's own

package/src/server.js

@@ -220,13 +220,42 @@ export function setupServer() {
                    .sendFile(faviconFile)
             })
 
-            await new Promise(resolve => {
-                const httpServer = runtime.options.app.listen(runtime.options.port, () => {
+            // Why this needs an error handler AND an address() check, rather
+            // than trusting the callback:
+            //
+            // `app.listen(port, cb)` invokes cb even when the bind FAILED —
+            // observed with a squatter on the port, cb running with
+            // `address() === null` and EADDRINUSE arriving on the error event
+            // afterwards. With no error handler, the process logged
+            // "Server listening: http://localhost:3779", printed a LAN
+            // address, completed the build green, and answered nothing: every
+            // request went to whoever actually held the port, which on a dev
+            // machine is another project's site. The operator opens the
+            // address, sees somebody else's pages, and the log insists they
+            // are their own.
+            //
+            // A server that cannot bind is not a server. --server asks to
+            // BECOME the instance, which is exactly the request that cannot be
+            // satisfied by carrying on — the same reasoning that makes a second
+            // server exit 1 rather than forward.
+            await new Promise((resolve, reject) => {
+                const httpServer = runtime.options.app.listen(runtime.options.port, function onListening() {
                     // Public URL wins for operator-clickable log lines —
                     // a reverse-proxy/tunnel/ngrok setup binds locally but
                     // is reached externally at runtime.options.url. Fall
                     // back to the bind URL when no public origin is set.
-                    const externalUrl = runtime.options.url ?? `http://localhost:${runtime.options.port}`
+                    // The bind is the authority on which port answers, not
+                    // the port that was asked for. A null address means the
+                    // listen failed and the error handler below owns it — say
+                    // nothing here, or the log claims a port it does not have.
+                    // `this`, not the const above: EventEmitter calls a
+                    // listener with the emitter, and a synchronous listen
+                    // reaches here while `httpServer` is still in its
+                    // temporal dead zone.
+                    const bound = this?.address?.()
+                    if (!bound) return
+
+                    const externalUrl = runtime.options.url ?? `http://localhost:${bound.port}`
                     logger.info('Server listening: %s', externalUrl)
 
                     // The addresses that are NOT localhost.
@@ -246,13 +275,25 @@ export function setupServer() {
                         const lan = localAddresses()
                         if (lan.length) {
                             logger.info('Also on: %s', lan
-                                .map(address => `http://${address}:${runtime.options.port}`)
+                                .map(address => `http://${address}:${bound.port}`)
                                 .join('  '))
                         }
                     }
                     resolve()
                 })
 
+                httpServer.on('error', (err) => {
+                    if (err.code === 'EADDRINUSE') {
+                        reject(new Error(
+                            `port ${runtime.options.port} is already in use — something else is listening there, `
+                            + `and requests to it will reach that instead of this build. `
+                            + `Stop it, or pass --server <other port>.`))
+                        return
+                    }
+                    reject(new Error(
+                        `could not listen on port ${runtime.options.port} — ${err.code ?? err.message}`))
+                })
+
                 // Node caps a single request at 5 minutes (requestTimeout,
                 // default 300_000ms), which is not a timeout in the usual
                 // sense here — it is an upload size limit expressed in