mikser-io 10.4.0 → 10.5.0

package/app.js

@@ -54,11 +54,11 @@ function locate(argv) {
     // cycle reports drift that is not there.
     const tool = value('--tool')
     const explain = value('--explain')
-    const request = has('--tools') ? { type: 'report', tools: true, json: has('--json') }
-        : tool                    ? { type: 'report', tool, toolArgs: value('--tool-args'), json: has('--json') }
-        : explain                 ? { type: 'report', explain, json: has('--json') }
-        : has('--audit-output')   ? { type: 'report', auditOutput: true, json: has('--json') }
-        : has('--fingerprint')    ? { type: 'report', fingerprint: true, json: has('--json') }
+    const request = has('--tools') ? { type: 'report', tools: true, json: has('--json'), log: value('--log') ?? value('-l') }
+        : tool                    ? { type: 'report', tool, toolArgs: value('--tool-args'), json: has('--json'), log: value('--log') ?? value('-l') }
+        : explain                 ? { type: 'report', explain, json: has('--json'), log: value('--log') ?? value('-l') }
+        : has('--audit-output')   ? { type: 'report', auditOutput: true, json: has('--json'), log: value('--log') ?? value('-l') }
+        : has('--fingerprint')    ? { type: 'report', fingerprint: true, json: has('--json'), log: value('--log') ?? value('-l') }
         : { type: 'build',
             clear: has('--clear'),
             // Not a flag that happens to be set — the client's OUTPUT
@@ -74,7 +74,16 @@ function locate(argv) {
             // rebuilt whatever the gates let through, which on a settled tree
             // is nothing, and a caller asking for a full re-render got a no-op
             // reported as success.
-            force: has('--force', '-f') }
+            force: has('--force', '-f'),
+            // The level travels for the same reason --json does: it is an
+            // OUTPUT CONTRACT, and the process doing the writing is the
+            // instance, which was started without it. A forwarded --log
+            // otherwise changed the level of a process that prints nothing.
+            log: value('--log') ?? value('-l'),
+            // Instance state rather than a contract: these outlive the request
+            // on purpose, which is the case a per-request flag cannot serve.
+            logInstall: value('--log-install'),
+            logReset: has('--log-reset') }
 
     return {
         longRunning,

package/docs/configuration.md

@@ -54,8 +54,9 @@ These options are part of `runtime.options` and apply to the engine itself.
 | `force` | `-f, --force` | boolean | `false` | Rebuild everything; disable incremental dispatch. |
 | `resume` | `-R, --resume` | boolean | `false` | Continue from journal entries left by a previous interrupted run; skip the initial filesystem scan. The journal table survives crashes, so an interrupted cycle can be picked up by re-running with `--resume`. |
 | `verify` | `--audit-output` | boolean | `false` | Verify the output folder against the manifest snapshot — report drift instead of building. |
-| `debug` | `-d, --debug` | boolean | `false` | Enable debug-level logging. |
-| `trace` | `-t, --trace` | boolean | `false` | Enable trace-level logging (very verbose). |
+| `log` | `-l, --log` | string | — | Log level for this run: `trace`, `debug`, `info`, `notice`, `warn`, `error`, `fatal`, `silent`. Replaces the old `--debug` / `--trace` booleans, which could not express "warnings only" and, in `--debug`'s case, did nothing at all — it moved the logger's level while the terminal stream kept the one it was built with. |
+| `logInstall` | `--log-install` | string | — | Set the level on a **running** instance, so its own rebuilds are verbose too — the case a per-request flag cannot serve. Expires after 30 minutes, dies with the process, and is disclosed in the build report under `logLevel`. |
+| `logReset` | `--log-reset` | boolean | `false` | Return a running instance to its configured level. |
 | `threads` | — | number | `4` | Worker thread count for the Piscina pools (`renderWorkers`, `postprocessWorkers`). Both pools are lazy (`minThreads: 0` + `idleTimeout: 30_000`) so INLINE-only workloads spin up zero workers. |
 | `server` | `-s, --server [port]` | number\|boolean | — | When set, the engine creates a shared Express app on `runtime.options.app` and listens on the given port (default `3001`) after all plugins have mounted their routes. Plugins like `api` attach to it instead of starting their own server. The `outputFolder` is also served as a static catch-all route at `/` (plugin routes match first; anything that doesn't match falls through to the rendered output). Requires `express` to be installed. |
 | `junk` | — | array\|false | built-in list | OS and file-manager litter, filtered out of both the scan and the watcher. The dot-prefixed files (`.DS_Store`, `._*`) were already invisible — globby defaults to `dot: false` and the watcher ignores leading dots — but the Windows ones are **not** dotfiles: `Thumbs.db` and `desktop.ini` were measurably scanned *and* watched, and became entities. The list is deliberately conservative (OS/file-manager artifacts and application lock files only, no `*.tmp`, `*.bak` or editor backups), because a filter that silently drops content is worse than the litter it prevents. `false` disables it; an array replaces it. See `isJunkPath` / `JUNK_IGNORE` in `src/utils.js`. Plugins that write metadata next to content add their own patterns with `registerJunk({ ignore, match })` — the engine provides the mechanism and the plugin the knowledge of what its files are called (`mikser-io-drive` registers `*.nephelemeta`). Plugin registrations survive an array override, since narrowing the OS list is not a request to start importing a library's sidecars. |

package/docs/diagnostics.md

@@ -328,7 +328,7 @@ compare against. It never appears alongside `matched` or `dependency`
 either: a consumer switches on `reason` and reads one field, so a stray
 key from another branch would make that switch wrong.
 
-The same detail appears at `--debug` for a watch run, one line per render.
+The same detail appears at `--log debug` for a watch run, one line per render.
 It is deliberately not in the build's normal output — the counts are the
 summary and `--json` is the record — but when you are watching one page
 misbehave, the trigger is the point.
@@ -419,7 +419,9 @@ thing `find out -type f` cannot do.
 | `-f, --force` | ignore all three gates (import checksum, dispatch, manifest) and re-render everything |
 | `-R, --resume` | continue from a previous interrupted run's journal; skips the filesystem scan |
 | `-r, --clear` | clear state before running |
-| `-d, --debug` / `-t, --trace` | raise log level; `trace` includes per-entity catalog writes |
+| `-l, --log <level>` | set the level for this run; `trace` includes per-entity catalog writes |
+| `--log-install <level>` | raise the level on a RUNNING instance without restarting it — restarting drops every connected MCP and drive session, so the tool you need should not require the risky act you are diagnosing. Expires after 30 minutes, dies with the process, and appears in the build report under `logLevel` so a level left on production is findable. |
+| `--log-reset` | put a running instance back to its configured level |
 | `--tools` | list the registered tools, then exit; `--json` for full schemas |
 | `--tool <name>` | run one tool and print its result, then exit. `--tool-args '<json>'` supplies arguments |
 

package/docs/getting-started.md

@@ -114,8 +114,11 @@ mikser [options]
                                    interrupted run; skip the initial filesystem scan
       --audit-output                     Audit output against recorded snapshots; report
                                    drift instead of building
-  -d, --debug                      Show debug log statements
-  -t, --trace                      Show trace log statements
+  -l, --log <level>                Log level for this run: trace, debug, info,
+                                   notice, warn, error, fatal, silent
+  --log-install <level>            Set the level on a RUNNING instance, so its
+                                   own rebuilds are verbose too. Expires.
+  --log-reset                      Return an instance to its configured level
   -e, --runtime-folder <folder>    Runtime/temp folder (default: runtime)
 ```
 

package/docs/lifecycle.md

@@ -91,7 +91,7 @@ onInitialized(async () => {
 
 **What Mikser does here:**
 - Parses CLI arguments and merges into `runtime.options`
-- Sets logger level based on `--debug` / `--trace` flags
+- Sets the logger level from `--log <level>`, moving the terminal stream with it
 - Resolves absolute paths for `workingFolder`, `outputFolder`, `runtimeFolder`
 - Creates the `runtimeFolder` directory
 - Clears `outputFolder` and `runtimeFolder` if `--clear` was set

package/package.json

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

package/src/engine.js

@@ -24,7 +24,10 @@ import map from 'p-map'
 import Queue from 'p-queue'
 import packageInfo from '../package.json' with { type: 'json' }
 import { attachServerCliOptions, setupServer } from './server.js'
-import { createMikserLogger } from './logger.js'
+import {
+    createMikserLogger, setLogLevel, rememberBaseLevel, installLogLevel, resetLogLevel,
+    applyInstalledLogLevel, installedLogLevel, LOG_LEVELS, INSTALLED_LOG_TTL_MS,
+} from './logger.js'
 import { inputHashOf } from './utils.js'
 import { createTrack, mergeTrack } from './track.js'
 import { queryContext } from './database/query-context.js'
@@ -552,8 +555,19 @@ export async function setup(options) {
             .option('--fingerprint', 'hash everything this build wrote — including what it wrote through a '
                 + 'symlink, which `find` does not descend into — and exit. One comparable number per output '
                 + 'tree, plus one per asset preset, for proving an upgrade moved no bytes.', false)
-            .option('-d --debug', 'display debug statements')
-            .option('-t --trace', 'display trace statements')
+            // One level, not two booleans.
+            //
+            // `--debug` and `--trace` could not say "warnings only on this
+            // build" or "trace this one thing", and --debug did not work at
+            // all: it moved the logger's level while the terminal stream kept
+            // the one it was built with, so debug records were accepted and
+            // discarded. Both are gone rather than aliased — a flag that lies
+            // is worse than a flag that is missing.
+            .option('-l --log <level>', `log level for this run: ${LOG_LEVELS.join(', ')}`)
+            .option('--log-install <level>', 'set the log level on a RUNNING instance, so its own '
+                + `rebuilds are verbose too. Expires after ${INSTALLED_LOG_TTL_MS / 60000} minutes and `
+                + 'dies with the process. Levels as above.')
+            .option('--log-reset', 'return a running instance to its configured log level', false)
             .option('-e --runtime-folder <folder>', 'set mikser runtime folder relative to working folder', 'runtime')
         attachServerCliOptions(runtime.engine.commander)
 
@@ -666,16 +680,20 @@ The full version, with what each code means: docs/diagnostics.md`)
         // runtime.options.info gates the progress bar — gauge stays
         // silent in --debug/--trace modes because logs are voluminous
         // there and a bar on top would just be noise.
+        //
+        // Applied through setLogLevel so the terminal STREAM moves with the
+        // logger — the whole reason --debug did nothing.
         runtime.options.info = true
-        if (runtime.options.debug) {
-            runtime.engine.logger.level = 'debug'
-            runtime.options.info = false
-        }
-        if (runtime.options.trace) {
-            runtime.engine.logger.level = 'trace'
-            runtime.options.debug = false
-            runtime.options.info = false
+        const asked = runtime.options.log
+        if (asked) {
+            if (!LOG_LEVELS.includes(asked)) {
+                throw new Error(`--log ${asked}: no such level. Levels: ${LOG_LEVELS.join(', ')}`)
+            }
+            setLogLevel(asked)
+            // A bar on top of debug output is noise, and silent means silent.
+            if (asked === 'trace' || asked === 'debug' || asked === 'silent') runtime.options.info = false
         }
+        rememberBaseLevel(asked && LOG_LEVELS.includes(asked) ? asked : 'info')
 
         // Resolve folders inside onInitialize so journal.js and
         // catalog.js (which initialize in onInitialized) see absolute

package/src/instance.js

@@ -37,6 +37,9 @@ import runtime from './runtime.js'
 import { onLoaded } from './lifecycle.js'
 import { renderErrorCount } from './report.js'
 import { runReportOnly } from './engine.js'
+import {
+    setLogLevel, installLogLevel, resetLogLevel, restingLogLevel,
+} from './logger.js'
 import { emitReport } from './report.js'
 import { pluginOptionsFrom } from './cli.js'
 
@@ -418,6 +421,17 @@ async function withRequestOutput(request, run) {
     // Set for the duration of the request and restored with the rest, so a
     // watcher's own cycle before or after is unaffected.
     request = { ...request, requested: true }
+
+    // The level the CLIENT asked for, for this request only.
+    //
+    // Restored in the finally below like every other part of the contract, so
+    // a watcher's own cycle before or after keeps the level it was running at.
+    // An installed level is different and deliberately not touched here — it
+    // outlives the request, which is its whole point.
+    if (request.logReset) resetLogLevel()
+    if (request.logInstall) installLogLevel(request.logInstall)
+    if (request.log) setLogLevel(request.log)
+
     for (const key of ['json', 'tool', 'tools', 'requested']) {
         prior[key] = runtime.options[key]
         if (request[key]) runtime.options[key] = request[key]
@@ -437,6 +451,11 @@ async function withRequestOutput(request, run) {
         return await run()
     } finally {
         Object.assign(runtime.options, prior)
+        // Back to where the level RESTS, not to what it was a moment ago.
+        // An installed level survives the request; a per-request --log does
+        // not; and a --log-reset in this same request has already moved the
+        // resting point, so restoring "the previous level" would undo it.
+        setLogLevel(restingLogLevel())
     }
 }
 

package/src/logger.js

@@ -30,7 +30,7 @@ import Gauge from 'gauge'
 import { Writable } from 'node:stream'
 import runtime from './runtime.js'
 import { useLogger } from './engine.js'
-import { onLoad } from './lifecycle.js'
+import { onLoad, onFinalized } from './lifecycle.js'
 import { captureWarning, captureFault } from './report.js'
 
 // Custom level — `notice` slots between info and warn. Used by mikser
@@ -355,6 +355,111 @@ export function addLogTransport(entry) {
     return true
 }
 
+// The levels a person can ask for, in pino's order.
+export const LOG_LEVELS = ['trace', 'debug', 'info', 'notice', 'warn', 'error', 'fatal', 'silent']
+
+// What the run was configured with, so a reset has something to return to.
+let baseLevel = 'info'
+// { level, expiresAt } — set by --log-install, survives the request that set it.
+let installedLevel = null
+
+// Move the level, and mean it.
+//
+// `--debug` used to set runtime.engine.logger.level and stop there, which did
+// nothing observable: the pino INSTANCE accepted debug records while the
+// terminal stream still filtered them at the level it was constructed with,
+// so they were accepted and discarded. It only ever worked when a logging
+// transport happened to be configured, because that is the one path that
+// rebuilt the logger. Measured on 10.4.0: identical output with and without
+// the flag, down to the line count.
+//
+// So the stream entry moves too, and the instance is rebuilt over the live
+// stream list the way addLogTransport already does — same swap, so a transport
+// added earlier survives.
+//
+// TRANSPORTS KEEP THEIR OWN LEVEL. They were built with the level they
+// declared, and `--log debug` is a statement about what the operator wants to
+// SEE, not an instruction to flood Better Stack. A transport that wants more
+// says so in its own entry.
+export function setLogLevel(level) {
+    if (!LOG_LEVELS.includes(level)) return false
+    if (currentStreams === null || !runtime.engine) return false
+    // Index 0 is the terminal entry — see createMikserLogger, where the list
+    // is seeded with it before any transport is appended.
+    currentStreams[0] = { ...currentStreams[0], level }
+    currentLevel = level
+    runtime.engine.logger = pino(
+        { level: 'trace', customLevels: CUSTOM_LEVELS },
+        pino.multistream(currentStreams),
+    )
+    return true
+}
+
+// The level a run starts at, remembered so --log-reset has a target.
+export function rememberBaseLevel(level) {
+    if (LOG_LEVELS.includes(level)) baseLevel = level
+}
+
+// Raise the level on a RUNNING instance, until it expires.
+//
+// The case a per-request flag structurally cannot serve: a watcher's own
+// rebuilds. Today the only way to make a misbehaving production instance
+// verbose is to restart it — which drops every connected MCP and drive
+// session, and is the incident path, so the tool you need is available only by
+// performing the risky act you are trying to diagnose.
+//
+// EXPIRES, because the failure mode is a full disk weeks later with nobody
+// remembering who asked. It also dies with the process, so a restart is a
+// second guarantee rather than the only one.
+export function installLogLevel(level, ttlMs = INSTALLED_LOG_TTL_MS) {
+    if (!LOG_LEVELS.includes(level)) return false
+    installedLevel = { level, expiresAt: Date.now() + ttlMs }
+    return setLogLevel(level)
+}
+
+export function resetLogLevel() {
+    installedLevel = null
+    return setLogLevel(baseLevel)
+}
+
+// What is in force, and whether an installed level has run out. Called at the
+// top of a cycle so expiry lands on a build boundary rather than mid-render.
+export function applyInstalledLogLevel() {
+    if (!installedLevel) return null
+    if (Date.now() >= installedLevel.expiresAt) {
+        const expired = installedLevel.level
+        installedLevel = null
+        setLogLevel(baseLevel)
+        return { expired, level: baseLevel }
+    }
+    if (currentLevel !== installedLevel.level) setLogLevel(installedLevel.level)
+    return { level: installedLevel.level, expiresAt: installedLevel.expiresAt }
+}
+
+// Where the level RESTS between requests: an installed one if there is one,
+// otherwise what the run was configured with.
+//
+// The single rule the restore needs. Putting back "the level before this
+// request" instead was wrong for exactly one case and it was the important
+// one: --log-reset captured debug, cleared it, and the restore put debug back,
+// so the reset appeared to do nothing.
+export function restingLogLevel() {
+    return installedLevel?.level ?? baseLevel
+}
+
+// What is in force right now, so a caller can put it back.
+export function currentLogLevel() {
+    return currentLevel ?? baseLevel
+}
+
+export function installedLogLevel() {
+    return installedLevel ? { ...installedLevel } : null
+}
+
+// Thirty minutes: long enough to reproduce something on a live instance,
+// short enough that forgetting costs a log file rather than a disk.
+export const INSTALLED_LOG_TTL_MS = 30 * 60 * 1000
+
 // Replace the bootstrap logger (built by engine.setup() with the
 // terminal-only stream) with one that includes any third-party
 // transports from runtime.config.logging.transports. Runs at onLoad
@@ -422,3 +527,38 @@ export function updateProgressDetails(details) {
         currentBar.value / currentBar.total,
     )
 }
+
+// An installed level, disclosed and expired, once per cycle.
+//
+// Disclosed for the reason an installed command is: it is state left on a live
+// instance that changes what the process does, and the person who finds it
+// weeks later is not the person who set it. A level at debug is quieter to
+// leave behind than a probe and louder in effect — the deployment's out log is
+// already 1.6MB, and a watcher rebuilding on every editor save at debug grows
+// it fast. The failure lands as a full disk with nobody remembering who asked.
+//
+// Expiry is checked here rather than on a timer so it lands on a build
+// boundary instead of mid-render, and the level also dies with the process, so
+// a restart is a second guarantee rather than the only one.
+//
+// onFinalized, matching where the commands plugin announces an installed
+// command — the report is reset at the top of a cycle, and a warning raised
+// anywhere earlier than the last hook did not survive into the document a
+// forwarded --json emits. Measured, not assumed: on onImport and on onFinalize
+// the line reached the instance's log and the report stayed empty.
+onFinalized(() => {
+    const state = applyInstalledLogLevel()
+    if (!state) return
+    const logger = useLogger()
+    if (state.expired) {
+        logger?.info('Log level installed with --log-install has expired; back to %s', state.level)
+        return
+    }
+    const minutes = Math.max(0, Math.round((state.expiresAt - Date.now()) / 60000))
+    logger?.warn(
+        { code: 'log-level-installed', level: state.level, expiresIn: `${minutes}m` },
+        'This instance is running at log level %s, installed with --log-install — it is not the '
+        + 'configured level and it is not this build asking for it. Expires in %dm, or on --log-reset, '
+        + 'or when the process restarts.',
+        state.level, minutes)
+})

package/src/report.js

@@ -10,6 +10,7 @@
 // reworded — which is exactly the kind of assertion that should not break
 // when someone improves the wording.
 import runtime from './runtime.js'
+import { installedLogLevel } from './logger.js'
 import { isReportOnlyRun } from './tools.js'
 
 // A transport that can serve the build report declares itself here, at
@@ -529,6 +530,27 @@ export function buildReport() {
         cycleId: cycle?.id ?? null,
         startedAt: cycle?.startedAt ?? null,
         finishedAt: cycle?.finishedAt ?? null,
+        // A log level installed on this instance with --log-install.
+        //
+        // Read HERE, at emit time, rather than raised as a warning during the
+        // cycle. A warning was the obvious shape — it is how an installed
+        // command is disclosed — and it does not survive into the document a
+        // forwarded --json emits: the line reached the instance's log from
+        // onImport, onFinalize and onFinalized alike, and `warnings` stayed
+        // empty every time. Reading state at emit has no ordering to get
+        // wrong, and this is a FACT ABOUT THE INSTANCE rather than an event in
+        // the cycle, so it reads better as a field than as an entry anyway.
+        //
+        // Null is the normal case, and its absence is what tells a reader the
+        // level is the configured one.
+        logLevel: installedLogLevel()
+            ? {
+                level: installedLogLevel().level,
+                installed: true,
+                expiresInMinutes: Math.max(0,
+                    Math.round((installedLogLevel().expiresAt - Date.now()) / 60000)),
+            }
+            : null,
         // What the run COST, per phase, in milliseconds.
         //
         // `finishedAt - startedAt` is not this. It spans the processing cycle