@feasibleone/blong-gogo 1.31.2 → 1.32.0

package/src/cli.ts

@@ -0,0 +1,209 @@
+import minimist from 'minimist';
+import {pathToFileURL} from 'node:url';
+
+import load from './loadServer.ts';
+
+/**
+ * Shared plumbing for a realm CLI — the shell around the `cli` intent.
+ *
+ * A realm CLI is the same realm in another mode. `runCli` loads the suite with
+ * the `cli` intent (no gateway, no RPC server, no watcher; every dispatch is
+ * resolved in-process), resolves the method the arguments name against the
+ * **live** registry, calls it, prints the result and stops. Going through the
+ * runtime rather than calling the handlers directly is what makes the CLI and the
+ * JSON-RPC surface agree — including the registry-backed answers an offline
+ * process could only approximate.
+ *
+ * What it removes is a handful of things that are subtle, identical in every CLI
+ * and wrong in interesting ways when re-derived: which channel the result goes
+ * on, that `handles()` alone cannot tell whether a method exists, the
+ * `load → start → dispatch → stop` order, and the exit-code conventions. Each of
+ * those has been gotten wrong at least once.
+ *
+ * Typical use, as the whole content of a `bin/*.ts`:
+ *
+ * ```ts
+ * import {isCliEntry, runCli} from '@feasibleone/blong-gogo/cli.ts';
+ * import cliSuite from '../cli.ts';
+ *
+ * const options = {
+ *     suite: cliSuite,
+ *     name: 'my-realm',
+ *     usage: USAGE,
+ *     command: ({positionals}) =>
+ *         positionals[0] ? {method: `myRealm.${positionals[0]}.find`} : undefined,
+ * };
+ *
+ * if (isCliEntry(import.meta.url)) await runCli(options);
+ * ```
+ */
+
+export interface Argv {
+    [key: string]: unknown;
+    _: (string | number)[];
+}
+
+export interface ParsedArgs {
+    /** The minimist view: named flags plus the `_` positionals. */
+    argv: Argv;
+    /** `_` coerced to strings, so `source get PATH` reads naturally. */
+    positionals: string[];
+}
+
+export interface CliCommand {
+    /** Fully qualified method, e.g. `kukum.handler.add`. */
+    method: string;
+    /**
+     * Handler params, passed through unchanged. Deliberately `object` rather
+     * than `Record<string, unknown>`: an interface of optional params is not
+     * assignable to an index signature, so every realm would have to cast.
+     */
+    params?: object;
+}
+
+export interface CliOptions {
+    /** The module the `cli` intent loads — normally the realm's `cli.ts`. */
+    suite: Parameters<typeof load>[0];
+    /** Suite and registry name; also the prefix of every error message. */
+    name: string;
+    /** Printed for `--help` and before a usage error. */
+    usage: string;
+    /**
+     * Flags to parse as strings (and so to accept repeatedly); every other flag
+     * is boolean or numeric.
+     */
+    stringFlags?: string[];
+    /** Intents passed to `load`; defaults to `['cli']`. */
+    intents?: string[];
+    /** Derive the method and its params from the arguments. */
+    command(args: ParsedArgs): CliCommand | undefined;
+    /** Rendering for `--output=text`; `undefined` falls back to JSON. */
+    format?(method: string, result: unknown): string | undefined;
+    /** Non-zero exit code for a call that completed (e.g. diagnostics errors). */
+    exitCodeFor?(method: string, result: unknown): number | undefined;
+    /** Appended to the unknown-method error, e.g. where to look next. */
+    hint?: string;
+}
+
+/** Parse a `process.argv.slice(2)`-style argument list. */
+export function parseArgv(args: string[], stringFlags: string[] = []): ParsedArgs {
+    const argv = minimist(args, {string: stringFlags}) as Argv;
+    return {argv, positionals: argv._.map(String)};
+}
+
+/** True when `--help`, `-h` or a leading `help` was asked for. */
+export function wantsHelp({argv, positionals}: ParsedArgs): boolean {
+    return argv.help === true || argv.h === true || positionals[0] === 'help';
+}
+
+/** The subset of the port API dispatch needs (`AdapterBase`). */
+export type DispatchPort = {
+    handles: (method: string) => boolean;
+    findHandler: (method: string) => unknown;
+};
+
+export type DispatchTarget = {
+    port: DispatchPort;
+    fn: (params: unknown, meta: unknown) => Promise<unknown>;
+};
+
+/**
+ * Locate the port that owns a method.
+ *
+ * A method only exists if its layer loaded, and it is the port's own handler
+ * table that answers — the same entry `Remote._findMethod` resolves to when
+ * `canSkipSocket` is set. `handles()` alone is not enough: it matches the
+ * namespace **prefix**, so it reports true for a method that does not exist.
+ * `findHandler` returning a function is the real test, which is what lets an
+ * unknown method be reported as such instead of falling through to an HTTP call
+ * against a process that binds no port.
+ */
+export function resolveMethod(
+    registry: {ports: Map<string, unknown>; getPort: (id: string) => unknown},
+    method: string,
+): DispatchTarget | undefined {
+    for (const id of registry.ports.keys()) {
+        const port = registry.getPort(id) as DispatchPort | undefined;
+        if (typeof port?.findHandler !== 'function') continue;
+        if (!port.handles(method)) continue;
+        const fn = port.findHandler(method);
+        if (typeof fn === 'function') {
+            return {port, fn: fn as DispatchTarget['fn']};
+        }
+    }
+    return undefined;
+}
+
+/**
+ * True when this module is the process entry point, so a `bin/*.ts` can be
+ * imported by a test without executing the command.
+ */
+export function isCliEntry(importMetaUrl: string): boolean {
+    const entry = process.argv[1];
+    return Boolean(entry) && importMetaUrl === pathToFileURL(entry).href;
+}
+
+/**
+ * Run one command and exit with a conventional status.
+ *
+ * Sets `process.exitCode` rather than calling `process.exit()`, so a caller's
+ * own cleanup still runs; `1` means "the command did not do what was asked" for
+ * a usage error, an unknown method, a thrown error or a result the caller's
+ * `exitCodeFor` rejects.
+ */
+export async function runCli(options: CliOptions): Promise<void> {
+    const {suite, name, usage, intents = ['cli']} = options;
+    const args = parseArgv(process.argv.slice(2), options.stringFlags);
+
+    if (wantsHelp(args)) {
+        process.stdout.write(usage);
+        return;
+    }
+    const command = options.command(args);
+    if (!command) {
+        process.stderr.write(usage);
+        process.exitCode = 1;
+        return;
+    }
+
+    // Keep stdout for the RESULT only. The loader logs to stdout, and
+    // `--output=json` has to stay parseable, so anything written while the realm
+    // loads and stops is forwarded to stderr — the loader's messages stay
+    // visible, just not on the result channel. `console.log` writes through the
+    // replacement too, which is why the result goes through the captured
+    // reference instead.
+    const json =
+        args.argv.output === 'json' || (args.argv.output === undefined && !process.stdout.isTTY);
+    const writeResult = process.stdout.write.bind(process.stdout);
+    process.stdout.write = ((chunk: string | Uint8Array) =>
+        process.stderr.write(chunk)) as typeof process.stdout.write;
+
+    try {
+        const registry = await load(suite, name, name, intents);
+        try {
+            // The load step that records handler folders and files still runs
+            // under `cli` (it is what feeds `Registry.describe()`); only the
+            // watcher and the listeners are off.
+            await registry.start({});
+            const resolved = resolveMethod(registry, command.method);
+            if (!resolved) {
+                process.stderr.write(
+                    `${name}: unknown method '${command.method}'.${options.hint ? ` ${options.hint}` : ''}\n`,
+                );
+                process.exitCode = 1;
+                return;
+            }
+            const result = await resolved.fn.call(resolved.port, command.params ?? {}, {
+                method: command.method,
+            });
+            const text = options.format?.(command.method, result);
+            writeResult(`${!json && text ? text : JSON.stringify(result, null, 2)}\n`);
+            process.exitCode = options.exitCodeFor?.(command.method, result) ?? 0;
+        } finally {
+            await registry.stop();
+        }
+    } catch (error) {
+        process.stderr.write(`${name}: ${(error as Error).message}\n`);
+        process.exitCode = 1;
+    }
+}

package/src/cliHelp.ts

@@ -20,9 +20,10 @@ Usage:
 
 Well-known intents:
   dev            Development — verbose logs, hot reload
-  integration    Integration testing — watch + test reruns
+  integration    Integration testing — watch + test reruns (exits when CI is set)
   microservice   Run a realm as a standalone microservice
   prod           Production / UAT
+  cli            Run a command in-process and exit — no HTTP server, no watcher
   db             Database creation / seeding (short-lived)
   debug          Enable /api/sys/* introspection + stack traces
 

package/src/exit.intent.test.ts

@@ -0,0 +1,98 @@
+import {server} from '@feasibleone/blong';
+import {test} from 'tap';
+
+import load from './loadServer.ts';
+
+/**
+ * The process-lifetime decision is declared per intent in `load.ts` and resolved
+ * onto the registry, so a runner can ask the registry instead of pattern-matching
+ * intent names (which is what `runServer` used to do with
+ * `process.env.CI && !intents.includes('playwright')`).
+ *
+ * Only `load` is exercised, never `start`, so nothing binds a port and no
+ * watcher is created — the assertions here are about the flag, and the
+ * "no listener" property is checked by actually running `blong cli`.
+ */
+
+/**
+ * `pkg` is supplied so the loader skips its `createRequire(mod.url)('./package.json')`
+ * lookup, which needs a real on-disk package next to the entry point.
+ */
+const suite = () =>
+    server(
+        () =>
+            ({
+                url: import.meta.url,
+                pkg: {name: 'exit-intent-test', version: '0.0.0'},
+                children: [],
+                config: {default: {}},
+            }) as never,
+    );
+
+/**
+ * `parentConfig` is passed as an object rather than a name on purpose: a string
+ * routes through ConfigRuntime's external config-file lookup, which is irrelevant
+ * here and would make the test depend on the working directory.
+ */
+async function exitFor(intents: string[]): Promise<boolean | undefined> {
+    const registry = await load(
+        suite() as unknown as Parameters<typeof load>[0],
+        'exit-intent-test',
+        {},
+        intents,
+    );
+    return registry.exit;
+}
+
+test('cli and db are short-lived', async t => {
+    t.equal(await exitFor(['cli']), true, 'a CLI does its work and exits');
+    t.equal(await exitFor(['db']), true, 'schema creation / seeding exits');
+});
+
+test('playwright is long-lived regardless of other intents', async t => {
+    t.equal(await exitFor(['playwright']), false, 'the webServer owns the process lifetime');
+    // The precedence that matters: `integration` is short-lived in CI, and adding
+    // `playwright` must override it — this is exactly what the old
+    // `!intents.includes('playwright')` clause did.
+    const previous = process.env.CI;
+    process.env.CI = '1';
+    try {
+        t.equal(await exitFor(['integration']), true, 'integration exits in CI');
+        t.equal(
+            await exitFor(['integration', 'playwright']),
+            false,
+            'a later intent overrides an earlier one',
+        );
+        // Declares nothing, so it resolves to false — the registry always
+        // carries a boolean once loaded, and `undefined` only appears on
+        // implementations that do not set it at all.
+        t.equal(await exitFor(['dev']), false, 'dev declares no lifetime');
+    } finally {
+        if (previous === undefined) delete process.env.CI;
+        else process.env.CI = previous;
+    }
+});
+
+test('integration keeps its CI-only lifetime', async t => {
+    const previous = process.env.CI;
+    delete process.env.CI;
+    try {
+        t.equal(await exitFor(['integration']), false, 'outside CI the process keeps running');
+    } finally {
+        if (previous !== undefined) process.env.CI = previous;
+    }
+});
+
+test('the cli intent turns off everything that would outlive a command', async t => {
+    // Asserted through the flag it implies plus the fact that loading still
+    // succeeds: the individual keys are read by the infra-item filter, not by
+    // anything the registry exposes.
+    const registry = await load(
+        suite() as unknown as Parameters<typeof load>[0],
+        'exit-intent-test',
+        {},
+        ['cli'],
+    );
+    t.equal(registry.exit, true, 'short-lived');
+    t.ok(Array.isArray(registry.describe?.().realms), 'the realm still loaded');
+});

package/src/graceful-shutdown.spawn.test.ts

@@ -17,7 +17,7 @@ import {test} from 'tap';
 
 const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 const blongBin = resolve(repoRoot, 'core', 'blong-gogo', 'bin', 'blong.ts');
-const helloDir = resolve(repoRoot, 'core', 'blong-hello');
+const helloDir = resolve(repoRoot, 'demo', 'blong-hello');
 
 test(
     'blong CLI exits 0 with the shutdown marker after timeout sends SIGTERM',

package/src/load.ts

@@ -19,6 +19,7 @@ import {
 } from '@feasibleone/blong/types';
 
 import {withProgress} from '@feasibleone/blong-lib';
+import {WELL_KNOWN_LAYERS} from '@feasibleone/blong-lib/layers';
 import {Type, type TSchema} from 'typebox';
 import merge from 'ut-function.merge';
 import {methodParts} from './lib.ts';
@@ -30,6 +31,25 @@ const extension = '.ts';
 
 const LAYER_FILE = 'layer' as const;
 
+/**
+ * Whether the process runs on CI.
+ *
+ * `load.ts` is shared by both platforms, and `process` does not exist in the
+ * browser bundle — a bare `process.env.CI` throws a `ReferenceError` while the
+ * browser realm loads (every browser test then fails with "process is not
+ * defined"). The optional chain keeps the server behaviour and degrades to
+ * `false` in the browser, which is correct: the server platform's `exit` drives
+ * the shutdown of both.
+ *
+ * A function rather than a module constant so the value is read when the config
+ * is built, not when the module is first imported.
+ */
+function isCI(): boolean {
+    return Boolean(
+        (globalThis as {process?: {env?: Record<string, string | undefined>}}).process?.env?.['CI'],
+    );
+}
+
 /**
  * An infrastructure item declaration with explicit dependencies.
  * Items are topologically sorted before instantiation so that each item's
@@ -72,30 +92,6 @@ function topoSort(items: InfraItem[]): InfraItem[] {
     return sorted;
 }
 
-/** Well-known layer folder names and their default activation per kind */
-const WELL_KNOWN_LAYERS: Record<string, {server?: object; browser?: object}> = {
-    api: {server: {default: true}, browser: {default: true}},
-    init: {server: {default: true}, browser: {default: true}},
-    meta: {server: {default: true}, browser: {default: true}},
-    error: {server: {integration: true}},
-    sim: {server: {integration: true}},
-    adapter: {server: {integration: true}},
-    orchestrator: {server: {integration: true}},
-    gateway: {server: {integration: true}},
-    backend: {browser: {integration: true}},
-    component: {browser: {integration: true}},
-    action: {browser: {integration: true}},
-    actions: {browser: {integration: true}},
-    test: {browser: {integration: true}},
-    'server/api': {server: {integration: true}},
-    'server/init': {server: {default: true}},
-    'server/test': {server: {integration: true}},
-    'browser/api': {browser: {integration: true}},
-    'browser/init': {browser: {default: true}},
-    'browser/test': {browser: {integration: true}},
-    'browser/orchestrator': {browser: {integration: true}},
-};
-
 /**
  * Discover layer folders in a realm directory that are not already listed as children.
  * Returns a map of folderName -> activation config.
@@ -400,6 +396,12 @@ export default async function loadRealm<T extends TSchema>(
     if (!('pkg' in mod) && platformApi.platform === 'server')
         mod.pkg = platformApi.createRequire?.(mod.url)('./package.json');
     const loadedConfigs = [];
+    /**
+     * The framework's own intent blocks (`default` + the active intents),
+     * resolved once per root load. Kept so their explicit `false` values can be
+     * re-asserted after every source has merged.
+     */
+    let frameworkConfigs: (boolean | object)[] = [];
     let items:
         | IModuleConfig['children']
         | {
@@ -413,85 +415,124 @@ export default async function loadRealm<T extends TSchema>(
             platform: platformApi,
             manifest,
         } as unknown as typeof api;
-        loadedConfigs.push(
-            ...activeConfigs(
-                {
-                    url: '',
-                    config: {
-                        default: {
-                            watch: {
-                                test: [],
-                            },
-                            log: {},
-                            apiSchema: {},
-                            error: {},
-                            registry: {},
-                            port: {},
-                            codec: {},
-                            adapter: {},
-                            orchestrator: {},
-                            remote: {
-                                canSkipSocket: rootKind === 'browser',
-                            },
-                            local: {},
-                            rpcServer: {},
-                            gateway: {},
-                            restFs: {},
-                            systemDebug: {},
-                            apiGateway: {},
+        // Retained so the "an intent's `false` wins" reconciliation can re-assert
+        // these after every source has merged (see below).
+        frameworkConfigs = activeConfigs(
+            {
+                url: '',
+                config: {
+                    default: {
+                        watch: {
+                            test: [],
                         },
-                        dev: {
-                            resolution: true,
-                            rpcServer: {
-                                port: 0,
+                        log: {},
+                        apiSchema: {},
+                        error: {},
+                        registry: {},
+                        port: {},
+                        codec: {},
+                        adapter: {},
+                        orchestrator: {},
+                        remote: {
+                            canSkipSocket: rootKind === 'browser',
+                        },
+                        local: {},
+                        rpcServer: {},
+                        gateway: {},
+                        restFs: {},
+                        systemDebug: {},
+                        mcp: {},
+                        apiGateway: {},
+                    },
+                    dev: {
+                        resolution: true,
+                        rpcServer: {
+                            port: 0,
+                        },
+                        log: {
+                            cacache: {
+                                cachePath: '~/.blong/log-cache',
                             },
-                            log: {
-                                cacache: {
-                                    cachePath: '~/.blong/log-cache',
-                                },
+                        },
+                        gateway: {
+                            port: 0,
+                            static: {},
+                            debug: true,
+                            expectedErrors: true,
+                            // Static development keys, so sessions survive server hot-reloads
+                            /* cSpell:disable */
+                            sign: {
+                                kty: 'EC',
+                                crv: 'P-384',
+                                alg: 'ES384',
+                                use: 'sig',
+                                x: 'VlRkjgqRHJSk9WN8CaAqHn34BUMy9pgKQUAAW9MrOqh0yvCmJW7JTr6LUCbm9zfW',
+                                y: '8eYxbAZrv-HZEc4LSgdEHeSp21zO3D8KrynMcVcNAmZKTf3RMkbkh1B26lePHQNz',
+                                d: 'aj6BkYmpwkKRbmcO1LO6d__HX5bvkqcRjqadlX7plXlGfj1d42XiSUWa4c9xrxwt',
                             },
-                            gateway: {
-                                port: 0,
-                                static: {},
-                                debug: true,
-                                expectedErrors: true,
-                                // Static development keys, so sessions survive server hot-reloads
-                                /* cSpell:disable */
-                                sign: {
-                                    kty: 'EC',
-                                    crv: 'P-384',
-                                    alg: 'ES384',
-                                    use: 'sig',
-                                    x: 'VlRkjgqRHJSk9WN8CaAqHn34BUMy9pgKQUAAW9MrOqh0yvCmJW7JTr6LUCbm9zfW',
-                                    y: '8eYxbAZrv-HZEc4LSgdEHeSp21zO3D8KrynMcVcNAmZKTf3RMkbkh1B26lePHQNz',
-                                    d: 'aj6BkYmpwkKRbmcO1LO6d__HX5bvkqcRjqadlX7plXlGfj1d42XiSUWa4c9xrxwt',
-                                },
-                                encrypt: {
-                                    kty: 'EC',
-                                    crv: 'P-384',
-                                    alg: 'ECDH-ES+A256KW',
-                                    use: 'enc',
-                                    x: '86IBoWsatO3Vky9CRMxmuYcfYoTY1Yr0D1sJGDgLlREMjbL9cIOHcBQnEaW52QJV',
-                                    y: 'fsKOmTuXaIRFXXteh7uU0Z8mncX4VsPhqaz9pMKMm8EktQlF7HBS_fYFdkLwqMMN',
-                                    d: 'rBY50TZzjONw_oYzWPqaR3DdoFwO-F9sWcmkOltrJHYnfbnTojNImX2xN1DhhC5-',
-                                },
-                                /* cSpell:enable */
+                            encrypt: {
+                                kty: 'EC',
+                                crv: 'P-384',
+                                alg: 'ECDH-ES+A256KW',
+                                use: 'enc',
+                                x: '86IBoWsatO3Vky9CRMxmuYcfYoTY1Yr0D1sJGDgLlREMjbL9cIOHcBQnEaW52QJV',
+                                y: 'fsKOmTuXaIRFXXteh7uU0Z8mncX4VsPhqaz9pMKMm8EktQlF7HBS_fYFdkLwqMMN',
+                                d: 'rBY50TZzjONw_oYzWPqaR3DdoFwO-F9sWcmkOltrJHYnfbnTojNImX2xN1DhhC5-',
                             },
-                            systemDebug: {enabled: true},
+                            /* cSpell:enable */
                         },
-                        integration: {
-                            remote: {canSkipSocket: true},
-                            gateway: {
-                                debug: true,
-                                expectedErrors: true,
-                            },
+                        systemDebug: {enabled: true},
+                    },
+                    integration: {
+                        remote: {canSkipSocket: true},
+                        gateway: {
+                            debug: true,
+                            expectedErrors: true,
                         },
+                        // Long-lived normally, but in CI the test run IS the
+                        // work, so the process is expected to end after it.
+                        exit: isCI(),
+                    },
+                    // Playwright drives the platform from its own webServer,
+                    // so it has to outlive the test command. Declared here so
+                    // the runner can ask the config instead of pattern-matching
+                    // the intent names.
+                    playwright: {exit: false},
+                    // Schema creation / seeding finishes, then exits.
+                    db: {exit: true},
+                    /**
+                     * A CLI process does its work in-process and exits: it
+                     * serves nothing, watches nothing, and resolves every
+                     * dispatch locally.
+                     */
+                    cli: {
+                        gateway: false,
+                        rpcServer: false,
+                        apiGateway: false,
+                        restFs: false,
+                        systemDebug: false,
+                        mcp: false,
+                        resolution: false,
+                        // `{enabled: false}`, NOT `false`: the load step that
+                        // records handler folders and files still runs (it is
+                        // what feeds `Registry.describe()`); only chokidar is
+                        // skipped.
+                        watch: {enabled: false, logLevel: 'warn'},
+                        // Dispatch in-process instead of over HTTP.
+                        remote: {canSkipSocket: true},
+                        // A command's stdout carries its result and has to stay
+                        // parseable, so the framework's own logging is quietened
+                        // here rather than by each CLI remembering to do it.
+                        log: {level: 'warn'},
+                        apiSchema: {logLevel: 'warn'},
+                        exit: true,
                     },
                 },
-                configNames,
-                platformApi.configs,
-            ),
+            },
+            configNames,
+            platformApi.configs,
         );
+        loadedConfigs.push(...frameworkConfigs);
         items = topoSort([
             {
                 name: 'log',
@@ -590,6 +631,11 @@ export default async function loadRealm<T extends TSchema>(
                           deps: ['log', 'gateway', 'registry', 'rpcServer'],
                           load: () => import(/* @vite-ignore */ './SystemDebug' + extension),
                       },
+                      {
+                          name: 'mcp',
+                          deps: ['log', 'gateway', 'registry', 'remote', 'apiSchema'],
+                          load: () => import(/* @vite-ignore */ './Mcp' + extension),
+                      },
                       {
                           name: 'registry',
                           deps: [
@@ -662,6 +708,18 @@ export default async function loadRealm<T extends TSchema>(
         Object.assign(manifest, mergedConfig.manifest);
     }
 
+    // An intent that switches a feature OFF is not overridable by a template's
+    // convenience defaults. The standalone-realm wrapper below declares
+    // ephemeral `gateway`/`rpcServer` ports in its `default` block; that block is
+    // pushed *after* the framework's intent blocks and would otherwise silently
+    // re-enable a listener the `cli` intent deliberately disabled.
+    for (const config of frameworkConfigs) {
+        if (!config || typeof config !== 'object') continue;
+        for (const [key, value] of Object.entries(config)) {
+            if (value === false) (mergedConfig as Record<string, unknown>)[key] = false;
+        }
+    }
+
     // Wire ConfigRuntime into Watch so config-file changes trigger in-process
     // reload via ConfigRuntime.reload() instead of restarting the process.
     if (configRuntime) {
@@ -963,5 +1021,10 @@ export default async function loadRealm<T extends TSchema>(
     }
     realm ||= new RealmImpl(mergedConfig, api!, rootKind);
     if (!api?.registry) throw new Error('Registry not found in loaded modules');
+    // Resolved from the active intents (see the `exit` keys in the synthetic
+    // config above). The runner uses it to decide whether this process outlives
+    // its work; absent means "keep running". Set here rather than in the
+    // constructor so the value is read after every config source has merged.
+    api.registry.exit = Boolean(mergedConfig.exit);
     return api.registry;
 }

package/src/loadBrowser.ts

@@ -94,6 +94,9 @@ export default load.bind(null, {
     writeFileSync: () => {
         throw new Error('writeFileSync is not supported in the browser');
     },
+    mkdirSync: () => {
+        throw new Error('mkdirSync is not supported in the browser');
+    },
     statSync: (() => undefined) as unknown as import('node:fs').StatSyncFn,
     timing: timing(hrtime),
     configs: ['browser'],

package/src/loadServer.ts

@@ -1,7 +1,7 @@
 import type {IPlatformApi} from '@feasibleone/blong';
 import {watch} from 'chokidar';
 import type {Dirent} from 'fs';
-import {existsSync, readFileSync, statSync, writeFileSync} from 'fs';
+import {existsSync, mkdirSync, readFileSync, statSync, writeFileSync} from 'fs';
 import {readdir} from 'fs/promises';
 import minimist from 'minimist';
 import {createRequire} from 'node:module';
@@ -67,6 +67,7 @@ export default load.bind(null, {
     relative,
     readFileSync,
     writeFileSync,
+    mkdirSync,
     statSync,
     watch,
     timing: timing(hrtime),