mikser-io 10.3.0 → 10.4.0

package/docs/configuration.md

@@ -360,24 +360,128 @@ export default {
 
 ### `commands`
 
+Runs shell commands at lifecycle hooks. A plugin, so it goes in `plugins` and
+takes its options as factory arguments:
+
 ```js
+import { commands } from 'mikser-io'
+
 export default {
-  commands: {
-    // Run shell commands at any lifecycle hook
-    load: 'echo Loading...',
-    finalized: ['npm run compress', 'npm run deploy'],
-
-    // Commands can also be async functions
-    processed: async (runtime) => {
-      if (runtime.options.mode === 'production') {
-        return 'npm run optimize'
-      }
-    }
-  }
+  plugins: [
+    commands({
+      load: 'echo Loading...',
+      finalized: ['npm run compress', 'npm run deploy'],
+      // Also an async function, resolved when the hook fires
+      processed: async () => process.env.NODE_ENV === 'production' && 'npm run optimize',
+    }),
+  ],
 }
 ```
 
-Available hook names: `load`, `loaded`, `import`, `imported`, `process`, `processed`, `persist`, `persisted`, `beforeRender`, `render`, `afterRender`, `cancel`, `cancelled`, `finalize`, `finalized`.
+Hook names: `load`, `loaded`, `import`, `imported`, `process`, `processed`,
+`persist`, `persisted`, `beforeRender`, `render`, `afterRender`, `cancel`,
+`cancelled`, `finalize`, `finalized`.
+
+#### From the command line
+
+One flag names a hook, so a one-off side effect needs no config edit:
+
+```bash
+mikser --command finalized="node deploy/publish.mjs"
+
+# repeatable
+mikser --command loaded="node probe.mjs" --command finalized="node publish.mjs"
+```
+
+The same shape as `--tool <name>`: one word of CLI namespace for an
+open-ended set, rather than one flag per hook. It runs *in addition to*
+whatever the config declares for that hook, and only for that run. Forwarded
+to a running `--watch` instance it **replaces** the previous request's
+commands rather than adding to them, and the instance's own rebuilds run
+none — one hook is registered at load and reads a value the instance swaps
+per request. The flag exists only when `commands()` is in the config, like
+every plugin option, and an unknown hook name is refused before anything is
+built.
+
+#### Installing on a running instance
+
+`--command` spends itself on one build. A watcher's **own** rebuilds — the
+ones a file save triggers, which is the point of watching — run nothing, so a
+probe fires only when you forward a build by hand. `--command-install` puts it
+on the instance instead:
+
+```bash
+mikser --command-install finalized="node probe.mjs"   # installs, and runs now
+# ...edit a file, the watcher rebuilds  → probe runs
+# ...edit again                         → probe runs
+mikser --command-reset                                # clears all of them
+mikser --command-reset finalized                      # or just one hook
+```
+
+Installed commands are announced on **every** cycle, not once — you may have
+set one an hour ago, and each build's report has to carry the fact that it was
+not a function of the repository alone. Per-request commands are announced
+once per process, because they are in the invocation you just typed.
+
+On a one-shot build there is no instance to install on, so `--command-install`
+runs once and exits with the process exactly like `--command` — reported under
+`command-install-without-instance` rather than left to look persistent.
+
+To see what is attached, read the last build: every installed command is
+announced on **every** cycle under `command-from-cli`, so the log or the
+`--json` report names each one. There is deliberately no `--tool commands` —
+the tool registry is mirrored into MCP over HTTP with an allow-all default,
+and a command string routinely carries a path, a host or a token. Listing
+them there would hand an authenticated web client a map of the build box, and
+tools have no per-tool scope to gate it with.
+
+Two hooks behave differently from the rest, and both say so rather than
+failing quietly:
+
+- **`load` is refused.** Options are declared *during* the load phase and the
+  table is parsed after it, so a `--command load=` could never fire. It is
+  named and refused rather than left out of the list, because "no hook named
+  load" would be untrue and would send you looking for a typo. Declare it in
+  the config instead.
+- **`loaded` does not fire for a forwarded build.** A running instance loaded
+  at startup and a rebuild does not repeat the load phase, so a load-phase
+  hook belongs to the instance rather than to the request. Asking for one
+  warns under `command-hook-not-reached`. Stop the instance, or use a
+  per-cycle hook.
+
+Two hooks behave differently from the rest, and both say so rather than
+failing quietly:
+
+- **`load` is refused.** Options are declared *during* the load phase and the
+  table is parsed after it, so a `--command load=` could never fire. Declare
+  it in the config instead.
+- **`loaded` does not fire for a forwarded build.** A running instance loaded
+  at startup and a rebuild does not repeat the load phase, so a load-phase
+  hook belongs to the instance rather than to the request. Asking for one
+  warns under `command-hook-not-reached`. Stop the instance, or use a
+  per-cycle hook.
+
+Two things to know, and they are the reason this is a flag rather than a
+convenience:
+
+**It is reported, under `command-from-cli`.** A build is otherwise a function
+of the repository — same commit, same bytes, and `--fingerprint` can prove it.
+A command from argv makes it a function of the repo *and* how it was invoked,
+so an agent, a person and CI can all run "the same build" and get different
+output. The warning carries the hook and the command string into `--json`
+`warnings`, so a fingerprint taken from that build stays interpretable instead
+of quietly meaning something else.
+
+**A command that writes into the output folder fails `--audit-output`.** Not a
+limitation to work around — mikser hashes each file as it writes it, so
+rewriting one afterwards is indistinguishable from tampering, and the audit
+reports it as `Mismatched` and exits 2. Post-build minification through a hook
+is therefore the wrong shape; it belongs in a renderer or a postprocessor,
+where the hash is taken over what is actually deployed. The honest use for
+hooks is side effects that do not touch `out/` — publishing, notifying,
+syncing — which is also the case where a flag beats config, because deploy
+steps are environment-specific and do not belong in a repository's build
+config.
 
 ### `shares`
 

package/package.json

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

package/src/cli.js

@@ -46,7 +46,13 @@ const declared = new Map()
 // is being built is always undefined. Read it in a hook: onLoaded and later
 // all run after stage two. documents() read its folder at construction first,
 // and `--documents content` silently did nothing.
-export function cliOption(flags, description, defaultValue) {
+// `parseArg` and `defaultValue` mirror commander's own signature, so a plugin
+// that wants a REPEATABLE option can pass a collector — which is what a flag
+// naming one of several things needs, and what `--command hook=cmd` is. Kept
+// commander-compatible rather than inventing a shape: the third argument is a
+// coercion function when it is callable and a default otherwise, which is
+// exactly how commander reads it.
+export function cliOption(flags, description, parseArg, defaultValue) {
     // No CLI at all — a plugin constructed by a test harness, or embedded
     // programmatically through setup({ ... }) rather than run from a terminal.
     // There is nothing to register the option on and nothing about that is a
@@ -65,11 +71,20 @@ export function cliOption(flags, description, defaultValue) {
             + 'Declare options while the plugin is constructed (the load phase), not afterwards — '
             + 'a later one would never be read and the flag would look ignored.')
     }
-    if (declared.has(flags)) return declared.get(flags)
-    const option = defaultValue === undefined
+    if (declared.has(flags)) return declared.get(flags).option
+    const coerce = typeof parseArg === 'function' ? parseArg : undefined
+    const fallback = coerce ? defaultValue : parseArg
+    const option = coerce
+        ? commander.option(flags, description, coerce, fallback)
+        : fallback === undefined
         ? commander.option(flags, description)
-        : commander.option(flags, description, defaultValue)
-    declared.set(flags, option)
+        : commander.option(flags, description, fallback)
+    // The coercion is remembered, not just applied. pluginOptionsFrom rebuilds
+    // a throwaway parser to read a forwarded client's argv, and a collector
+    // left out there would hand back the last value where the local run got an
+    // array — the forwarded path quietly behaving differently from the local
+    // one, which is the failure the instance surface exists to remove.
+    declared.set(flags, { option, coerce, fallback })
     return option
 }
 
@@ -154,7 +169,11 @@ export function pluginOptionsFrom(argv) {
     let parsed
     try {
         const probe = commander.createCommand()
-        for (const flags of declared.keys()) probe.option(flags, '')
+        for (const [flags, { coerce, fallback }] of declared) {
+            if (coerce) probe.option(flags, '', coerce, fallback)
+            else if (fallback === undefined) probe.option(flags, '')
+            else probe.option(flags, '', fallback)
+        }
         probe.allowUnknownOption(true).allowExcessArguments(true)
         probe.parse(argv, { from: 'user' })
         parsed = probe.opts()

package/src/plugins/commands.js

@@ -1,8 +1,60 @@
 import { execaCommand } from 'execa'
+import { cliOption } from '../cli.js'
 import lineReader from 'line-reader'
 import { promisify } from 'util'
 import _ from 'lodash'
 
+// The hooks a command can hang off.
+//
+// ONE flag naming a hook, not fifteen flags named after hooks. The same shape
+// as `--tool <name>`: a plugin claims one word for an open-ended registry
+// rather than one word per entry. Fifteen would have reserved `--render`,
+// `--process`, `--load`, `--import`, `--persist` and `--cancel` at the top
+// level for one plugin — words core plausibly wants (a `--render <entity>` is
+// not hard to imagine) — and put fifteen near-identical rows in `--help`.
+const HOOKS = new Set([
+    'load', 'loaded', 'import', 'imported', 'process', 'processed',
+    'persist', 'persisted', 'beforeRender', 'render', 'afterRender',
+    'cancel', 'canceled', 'finalize', 'finalized',
+])
+
+// `load` is declarable in config and unreachable from the CLI: options are
+// declared DURING the load phase and the table is not parsed until after it,
+// so runtime.options is still empty when onLoad fires.
+//
+// Named and REFUSED rather than left out of the hook list. Omitting it would
+// answer `--command load=...` with "no hook named load", which is untrue —
+// there is such a hook, it is simply not one the command line can reach, and a
+// wrong reason sends someone looking for a typo. The refusal says what to do
+// instead.
+const CLI_UNREACHABLE = new Map([
+    ['load', 'the option table is parsed after the load phase, so a --command on it could never fire. '
+        + 'Declare it in the config instead: commands({ load: ... }).'],
+])
+
+// Never expected on a successful build, so their absence is not a finding.
+const CONDITIONAL = new Set(['cancel', 'canceled'])
+
+// `hook=command`, split on the FIRST `=` so a command may contain its own.
+function parseHookCommand(value) {
+    const at = value.indexOf('=')
+    if (at < 1) {
+        throw new Error(`--command expects <hook>=<command>, got ${JSON.stringify(value)}. `
+            + `Hooks: ${[...HOOKS].join(', ')}`)
+    }
+    const hook = value.slice(0, at).trim()
+    const command = value.slice(at + 1).trim()
+    if (!HOOKS.has(hook)) {
+        throw new Error(`--command: no hook named ${JSON.stringify(hook)}. `
+            + `Hooks: ${[...HOOKS].join(', ')}`)
+    }
+    if (CLI_UNREACHABLE.has(hook)) {
+        throw new Error(`--command ${hook}=: ${CLI_UNREACHABLE.get(hook)}`)
+    }
+    if (!command) throw new Error(`--command ${hook}=: no command given`)
+    return { hook, command }
+}
+
 export function commands(options = {}) {
     return ({
         runtime,
@@ -26,6 +78,117 @@ export function commands(options = {}) {
         const eachLine = promisify(lineReader.eachLine)
         const running = {}
 
+        // Declared here, in the load phase, and READ in the hook below.
+        // Reading at construction is always undefined — the option table is
+        // not parsed until after this runs.
+        //
+        // Repeatable, so several hooks can be driven in one invocation. The
+        // collector is remembered by cliOption and replayed when an instance
+        // re-parses a forwarded client's argv, so the forwarded path sees the
+        // same array the local one does.
+        const collect = (value, previous = []) => [...previous, parseHookCommand(value)]
+        cliOption('--command <hook=command>',
+            'run a command at a lifecycle hook for THIS run only, e.g. '
+            + '--command finalized="node deploy/publish.mjs". Repeatable. '
+            + `Hooks: ${[...HOOKS].join(', ')}`,
+            collect, [])
+        // Installed on the instance rather than spent on one request.
+        //
+        // --command alone cannot serve the case it was asked for. A watcher's
+        // OWN rebuilds — the ones a file save triggers, which is the whole
+        // point of watching — run nothing, so a probe fires only when a build
+        // is forwarded by hand. Installing puts it on the instance, where
+        // every cycle sees it until it is cleared.
+        cliOption('--command-install <hook=command>',
+            'install a command on the running instance, so its own rebuilds run it too. '
+            + 'Repeatable. Cleared with --command-reset.',
+            collect, [])
+        cliOption('--command-reset [hook]',
+            'clear commands installed with --command-install: all of them, or one hook\'s.')
+
+        // Said once per hook per process, not once per cycle: a watcher would
+        // otherwise repeat it on every rebuild.
+        const announced = new Set()
+
+        // Commands installed on THIS process by a forwarded --command-install.
+        //
+        // Lives in the plugin's closure rather than runtime.options because
+        // options are swapped per request and restored after — which is
+        // exactly right for --command and exactly wrong for something whose
+        // point is to outlive the request that set it.
+        const installed = new Map()
+
+        // Applied at the top of every hook: idempotent, so it does not matter
+        // which hook of the cycle sees the request first, and by the next
+        // cycle the request's options are gone while `installed` remains.
+        function applyInstallRequest() {
+            const reset = runtime.options?.commandReset
+            if (reset !== undefined && reset !== false) {
+                const cleared = reset === true
+                    ? [...installed.keys()]
+                    : installed.has(reset) ? [reset] : []
+                if (reset === true) installed.clear()
+                else installed.delete(reset)
+                if (cleared.length) {
+                    useLogger()?.info('Cleared installed command(s) at %s', cleared.join(', '))
+                }
+            }
+            const requested = runtime.options?.commandInstall
+            if (!Array.isArray(requested) || !requested.length) return
+            // An instance is what there is to install ON. A one-shot exits
+            // with the process, so installing is the same as --command and
+            // saying nothing would let someone believe it persisted.
+            if (!runtime.options?.watch && !runtime.options?.server) {
+                if (!announced.has('no-instance')) {
+                    announced.add('no-instance')
+                    useLogger()?.warn({ code: 'command-install-without-instance' },
+                        'Nothing to install on — this is a one-shot build, not a watcher, so '
+                        + '--command-install ran once and exits with the process, exactly like --command.')
+                }
+            }
+            for (const { hook, command } of requested) {
+                const list = installed.get(hook) ?? []
+                if (!list.includes(command)) installed.set(hook, [...list, command])
+            }
+        }
+
+        // NOT registered as a tool, deliberately.
+        //
+        // Listing what is attached is worth having, and `--tool commands` was
+        // the obvious shape — the registry forwards report-only runs to the
+        // instance, so it would answer from the process that holds the state.
+        // But the registry is mirrored into MCP over HTTP, its endpoint filter
+        // defaults to allow-all, and a command string routinely carries a
+        // path, a host or a token. That turns "list the hooks" into handing an
+        // authenticated web client a map of the build box.
+        //
+        // There is no per-tool scope to lean on: routes declare reachability
+        // (public / token / loopback), tools declare only `mutates`. A
+        // `scope: 'admin'` key here would be decorative — nothing enforces it
+        // — and a decorative guard is worse than none, because it reads like
+        // one.
+        //
+        // Installing is not the exposure: it needs the unix socket, which is
+        // chmod 0600, so anyone who can reach it already runs as this user and
+        // could run the command directly. Reading over HTTP is a different
+        // boundary, which is why this half is the half that had to go.
+        //
+        // What answers the question meanwhile: every installed command is
+        // announced on every cycle under `command-from-cli`, so the last
+        // build's log or its --json report names each one. A standalone
+        // listing wants per-tool scoping in the registry first.
+
+        // Which requested hooks actually fired this cycle.
+        //
+        // `loaded` is the case that matters: it fires for a local build and
+        // NOT for one forwarded to a running instance, because that instance
+        // loaded at startup and a rebuild does not repeat the load phase. So
+        // the same command does different things depending on whether a
+        // watcher happens to be up, and until now it did so in silence.
+        // Checked generically rather than special-casing that one hook, since
+        // the interesting cases are the ones nobody predicted.
+        const fired = new Set()
+
         async function executeCommand(command) {
             const logger = useLogger()
             if (_.endsWith(command, '&')) {
@@ -51,9 +214,74 @@ export function commands(options = {}) {
             if (typeof cmds == 'function') cmds = await cmds()
             if (typeof cmds == 'string') cmds = [cmds]
 
+            // From argv, read HERE rather than merged into `options` at
+            // construction — that is the whole rule for plugin CLI options,
+            // and it is also what makes a forwarded request overwrite instead
+            // of accumulate. The instance applies a client's flags onto
+            // runtime.options for one cycle and restores them after, so this
+            // reads whatever THIS request asked for. Registering a hook per
+            // request would have made two clients' commands add up; there is
+            // one hook, registered once, reading a value that changes.
+            applyInstallRequest()
+
+            const requested = runtime.options?.command
+            const perRequest = (Array.isArray(requested) ? requested : [])
+                .filter(entry => entry?.hook === hook)
+                .map(entry => entry.command)
+            // Installed ones outlive the request that set them, so they run
+            // for the instance's OWN rebuilds too — which is the case
+            // --command alone cannot serve.
+            const fromInstalled = installed.get(hook) ?? []
+            const fromCli = [...perRequest, ...fromInstalled]
+            for (const command of fromCli) {
+                // Under a code, in the report, with the command.
+                //
+                // A build is otherwise a function of the repository — same
+                // commit, same bytes, and --fingerprint can prove it. A
+                // command from argv makes it a function of the repo AND how it
+                // was invoked, so an agent, a person and CI can run "the same
+                // build" and get different output. Warn rather than log:
+                // warnings are a view of logger.warn in the report, so a
+                // fingerprint taken from this build stays interpretable
+                // instead of quietly meaning something else.
+                // A per-request command is announced once per process: it is
+                // in the invocation you just typed. An INSTALLED one is
+                // announced every cycle, because you may have set it an hour
+                // ago and each build's report has to carry the fact that this
+                // build was not a function of the repository alone.
+                const key = `${hook}:${command}`
+                if (fromInstalled.includes(command) || !announced.has(key)) {
+                    announced.add(key)
+                    useLogger()?.warn({ code: 'command-from-cli', hook, command },
+                        'Running a command from the command line at the %s hook: %s. This build is a '
+                        + 'function of how it was invoked as well as of the repository — the same commit '
+                        + 'built without this flag can differ. Commands that write into the output folder '
+                        + 'also fail --audit-output, which hashes each file as it is written.',
+                        hook, command)
+                }
+            }
+            cmds = [...cmds, ...fromCli]
+
             for (let command of cmds) {
                 await executeCommand(command)
             }
+            if (fromCli.length) fired.add(hook)
+        }
+
+        // Anything asked for that never ran, said at the end of the cycle.
+        function reportUnfired() {
+            const requested = runtime.options?.command
+            if (!Array.isArray(requested)) return
+            const missed = [...new Set(requested.map(entry => entry?.hook))]
+                .filter(hook => hook && !fired.has(hook) && !CONDITIONAL.has(hook))
+            fired.clear()
+            if (!missed.length) return
+            useLogger()?.warn({ code: 'command-hook-not-reached', hooks: missed },
+                'Asked to run a command at %s, and that hook did not fire this cycle. A build forwarded '
+                + 'to a running instance reuses one that loaded at startup, so load-phase hooks belong '
+                + 'to the instance rather than to the request. Stop the instance to run the command, or '
+                + 'move it to a per-cycle hook.',
+                missed.join(', '))
         }
 
         onLoad(async () => await executeCommands('load'))
@@ -70,7 +298,11 @@ export function commands(options = {}) {
         onCancel(async () => await executeCommands('cancel'))
         onCancelled(async () => await executeCommands('canceled'))
         onFinalize(async () => await executeCommands('finalize'))
-        onFinalized(async () => await executeCommands('finalized'))
+        onFinalized(async () => {
+            await executeCommands('finalized')
+            // Last, so every other hook has had its chance.
+            reportUnfired()
+        })
 
         return { executeCommand }
     }