@zmdb/app 1.0.0-beta.1

package/README.md

@@ -0,0 +1,27 @@
+# @zmdb/app
+
+The protocol-neutral application kernel for zmdb. It owns Stage-3 metadata, dependency injection, modules, lifecycle, transport-neutral messaging, command applications, events, CQRS, state machines,
+health contracts, and dependency-free observability ports.
+
+For the cohesive server product, install `zmdb` and use `zmdb/app` for application concerns. The [server journey](https://ambasta.github.io/zmdb/docs/web-overview.html) combines HTTP and selected jobs
+under this lifecycle.
+
+## Advanced: install the kernel alone
+
+```bash
+yarn add @zmdb/app@1.0.0-beta.1
+```
+
+The package is ESM-only and requires Node.js 26 or later.
+
+## Entry points
+
+`@zmdb/app`, `@zmdb/app/commands`, `@zmdb/app/cqrs`, `@zmdb/app/data`, `@zmdb/app/di`, `@zmdb/app/events`, `@zmdb/app/health`, `@zmdb/app/lifecycle`, `@zmdb/app/messaging`, `@zmdb/app/modules`,
+`@zmdb/app/observability`, and `@zmdb/app/state`.
+
+HTTP adapters live in `@zmdb/web`. Queues and scheduling live in `@zmdb/jobs`; concrete broker integrations remain separately installed and implement the public `@zmdb/app/messaging` strategy
+contract.
+
+## License
+
+GNU General Public License v3.0 or later (GPL-3.0-or-later).

package/dist/application.d.ts

@@ -0,0 +1,45 @@
+import type { Container } from './di/index.js';
+import { type CompiledModule, type LazyModuleHandle, type ModuleClass } from './modules/index.js';
+import { type CompiledController } from './modules/runtime.js';
+import type { Observability } from './observability/types.js';
+/** Private cross-package bridge used by HTTP/testing adapters without widening Application. */
+export interface ApplicationBridge {
+    readonly compiled: CompiledModule;
+    readonly controllers: readonly CompiledController[];
+}
+export interface ApplicationExtensionContext {
+    readonly container: Container;
+    readonly controllers: readonly object[];
+    readonly commands: readonly object[];
+    readonly observability: Observability;
+}
+export interface ApplicationExtension {
+    readonly name: string;
+    start(context: ApplicationExtensionContext): void | Promise<void>;
+    stop(options: {
+        readonly graceMs: number;
+    }): void | Promise<void>;
+}
+export interface ApplicationOptions {
+    readonly extensions?: readonly ApplicationExtension[];
+    readonly observability?: Observability;
+    readonly graceMs?: number;
+}
+export interface Application extends AsyncDisposable {
+    readonly container: Container;
+    readonly lazy: readonly LazyModuleHandle[];
+    init(): Promise<void>;
+}
+/**
+ * Compile one protocol-neutral application and own its complete lifecycle.
+ *
+ * The two symbol-keyed bridge properties are non-enumerable implementation
+ * details. They let the HTTP and testing adapters consume the same compiled
+ * identities without adding public Application fields or compiling twice.
+ */
+export declare function createApplication(rootModule: ModuleClass, options?: ApplicationOptions): Application;
+/** Package-private controller declarations for extensions with eager-only rules. */
+export declare function applicationExtensionControllersOf(context: ApplicationExtensionContext): readonly CompiledController[];
+/** Package-private access for command applications. */
+export declare function applicationBridgeOf(application: Application): ApplicationBridge;
+//# sourceMappingURL=application.d.ts.map

package/dist/application.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../src/application.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAiB,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjH,OAAO,EAAa,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAY9D,+FAA+F;AAC/F,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACrD;AAcD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,OAAO,EAAE,2BAA2B,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,IAAI,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC3C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,WAAW,EAAE,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAsHxG;AAED,oFAAoF;AACpF,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,2BAA2B,GAAG,SAAS,kBAAkB,EAAE,CAMrH;AAED,uDAAuD;AACvD,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,iBAAiB,CAO/E"}

package/dist/application.js

@@ -0,0 +1,186 @@
+import { runInit, runShutdown } from './lifecycle.js';
+import { compileModule } from './modules/index.js';
+import { lifecycleInstances } from './modules/lifecycle-instances.js';
+import { runtimeOf } from './modules/runtime.js';
+const APPLICATION_BRIDGE = Symbol.for('@zmdb/app.application-bridge');
+const APPLICATION_EXTENSION_BRIDGE = Symbol('@zmdb/app.application-extension-bridge');
+const COMPILED_APPLICATION = Symbol.for('@zmdb/app.compiled-application');
+const DEFAULT_GRACE_MS = 5_000;
+const EMPTY_OBSERVABILITY = Object.freeze({});
+/**
+ * Compile one protocol-neutral application and own its complete lifecycle.
+ *
+ * The two symbol-keyed bridge properties are non-enumerable implementation
+ * details. They let the HTTP and testing adapters consume the same compiled
+ * identities without adding public Application fields or compiling twice.
+ */
+export function createApplication(rootModule, options = {}) {
+    const graceMs = applicationGrace(options.graceMs ?? DEFAULT_GRACE_MS);
+    const extensions = validatedExtensions(options.extensions ?? []);
+    const compiled = compiledApplication(options) ?? compileModule(rootModule);
+    const runtime = runtimeOf(compiled);
+    const instances = lifecycleInstances(compiled.container);
+    const observability = options.observability ?? EMPTY_OBSERVABILITY;
+    const controllerBindings = Object.freeze([
+        ...(runtime?.controllers ?? compiled.controllers.map(controller => ({ kind: 'eager', controller }))),
+    ]);
+    let context;
+    if (extensions.length > 0) {
+        const extensionContext = {
+            container: compiled.container,
+            controllers: Object.freeze([...compiled.controllers]),
+            commands: Object.freeze([...compiled.commands]),
+            observability,
+        };
+        Object.defineProperty(extensionContext, APPLICATION_EXTENSION_BRIDGE, {
+            value: Object.freeze({ controllers: controllerBindings }),
+        });
+        context = Object.freeze(extensionContext);
+    }
+    const entered = [];
+    let state = 'created';
+    let initPromise;
+    let disposePromise;
+    const stopEntered = async () => {
+        const errors = [];
+        const deadline = Date.now() + graceMs;
+        for (let index = entered.length - 1; index >= 0; index -= 1) {
+            const extension = entered[index];
+            if (extension === undefined)
+                continue;
+            try {
+                await extension.stop({ graceMs: Math.max(0, deadline - Date.now()) });
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        entered.length = 0;
+        return errors;
+    };
+    const shutdownInstances = async () => {
+        try {
+            await runShutdown(instances);
+            return [];
+        }
+        catch (error) {
+            return errorsOf(error);
+        }
+    };
+    const start = async () => {
+        state = 'starting';
+        try {
+            await runInit(instances);
+            if (context !== undefined) {
+                for (const extension of extensions) {
+                    entered.push(extension);
+                    await extension.start(context);
+                }
+            }
+            state = 'running';
+        }
+        catch (startupError) {
+            runtime?.beginShutdown();
+            await runtime?.waitForLoads();
+            const cleanupErrors = [...(await stopEntered()), ...(await shutdownInstances())];
+            state = 'failed-cleaned';
+            if (cleanupErrors.length === 0)
+                throw startupError;
+            throw new AggregateError([startupError, ...cleanupErrors], '@zmdb/app: application startup cleanup failed', {
+                cause: startupError,
+            });
+        }
+    };
+    const dispose = async () => {
+        runtime?.beginShutdown();
+        if (initPromise !== undefined) {
+            try {
+                await initPromise;
+            }
+            catch {
+                // Failed initialization performed its own complete cleanup transaction.
+                return;
+            }
+        }
+        if (state === 'failed-cleaned' || state === 'stopped')
+            return;
+        state = 'stopping';
+        await runtime?.waitForLoads();
+        const errors = [...(await stopEntered()), ...(await shutdownInstances())];
+        state = 'stopped';
+        throwObserved(errors, '@zmdb/app: application shutdown failed');
+    };
+    const application = {
+        container: compiled.container,
+        lazy: compiled.lazy,
+        init: () => {
+            if (disposePromise !== undefined) {
+                return Promise.reject(new Error('@zmdb/app: application is shutting down'));
+            }
+            initPromise ??= start();
+            return initPromise;
+        },
+        [Symbol.asyncDispose]: () => {
+            disposePromise ??= dispose();
+            return disposePromise;
+        },
+    };
+    Object.defineProperty(application, APPLICATION_BRIDGE, {
+        value: Object.freeze({
+            compiled,
+            controllers: controllerBindings,
+        }),
+    });
+    return application;
+}
+/** Package-private controller declarations for extensions with eager-only rules. */
+export function applicationExtensionControllersOf(context) {
+    const carrier = context;
+    return (carrier[APPLICATION_EXTENSION_BRIDGE]?.controllers ??
+        Object.freeze(context.controllers.map(controller => ({ kind: 'eager', controller }))));
+}
+/** Package-private access for command applications. */
+export function applicationBridgeOf(application) {
+    const carrier = application;
+    const bridge = carrier[APPLICATION_BRIDGE];
+    if (bridge === undefined) {
+        throw new Error('@zmdb/app: application omitted its compiled graph');
+    }
+    return bridge;
+}
+function compiledApplication(options) {
+    const carrier = options;
+    return carrier[COMPILED_APPLICATION];
+}
+function applicationGrace(value) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new RangeError('@zmdb/app: graceMs must be a positive integer');
+    }
+    return value;
+}
+function validatedExtensions(values) {
+    const names = new Set();
+    const extensions = [...values];
+    for (const extension of extensions) {
+        if (extension.name.length === 0) {
+            throw new RangeError('@zmdb/app: an extension name cannot be empty');
+        }
+        if (names.has(extension.name)) {
+            throw new Error(`@zmdb/app: duplicate extension name "${extension.name}"`);
+        }
+        names.add(extension.name);
+    }
+    return Object.freeze(extensions);
+}
+function errorsOf(error) {
+    return error instanceof AggregateError ? [...error.errors] : [error];
+}
+function throwObserved(errors, message) {
+    if (errors.length === 0)
+        return;
+    const first = errors[0];
+    if (errors.length === 1 && first !== undefined)
+        throw first;
+    throw new AggregateError(errors, message);
+}
+//# sourceMappingURL=application.js.map

package/dist/application.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application.js","sourceRoot":"","sources":["../src/application.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAgE,MAAM,oBAAoB,CAAC;AACjH,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,SAAS,EAA2B,MAAM,sBAAsB,CAAC;AAG1E,MAAM,kBAAkB,GAAG,MAAM,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;AACtE,MAAM,4BAA4B,GAAG,MAAM,CAAC,wCAAwC,CAAC,CAAC;AACtF,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;AAC1E,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAC/B,MAAM,mBAAmB,GAAkB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAiD7D;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAuB,EAAE,OAAO,GAAuB,EAAE;IACzF,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC;IACtE,MAAM,UAAU,GAAG,mBAAmB,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;IACjE,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,IAAI,aAAa,CAAC,UAAU,CAAC,CAAC;IAC3E,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,kBAAkB,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACzD,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,mBAAmB,CAAC;IACnE,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC;QACvC,GAAG,CAAC,OAAO,EAAE,WAAW,IAAI,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAgB,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;KAC9G,CAAC,CAAC;IACH,IAAI,OAAgD,CAAC;IACrD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,gBAAgB,GAAgC;YACpD,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;YACrD,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC/C,aAAa;SACd,CAAC;QACF,MAAM,CAAC,cAAc,CAAC,gBAAgB,EAAE,4BAA4B,EAAE;YACpE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;SAC1D,CAAC,CAAC;QACH,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,IAAI,KAAK,GAAmF,SAAS,CAAC;IACtG,IAAI,WAAsC,CAAC;IAC3C,IAAI,cAAyC,CAAC;IAE9C,MAAM,WAAW,GAAG,KAAK,IAAwB,EAAE;QACjD,MAAM,MAAM,GAAc,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;QACtC,KAAK,IAAI,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YAC5D,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YACjC,IAAI,SAAS,KAAK,SAAS;gBAAE,SAAS;YACtC,IAAI,CAAC;gBACH,MAAM,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACxE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;QACD,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QACnB,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IAEF,MAAM,iBAAiB,GAAG,KAAK,IAAwB,EAAE;QACvD,IAAI,CAAC;YACH,MAAM,WAAW,CAAC,SAAS,CAAC,CAAC;YAC7B,OAAO,EAAE,CAAC;QACZ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,KAAK,IAAmB,EAAE;QACtC,KAAK,GAAG,UAAU,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;YACzB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;oBACnC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;oBACxB,MAAM,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBACjC,CAAC;YACH,CAAC;YACD,KAAK,GAAG,SAAS,CAAC;QACpB,CAAC;QAAC,OAAO,YAAY,EAAE,CAAC;YACtB,OAAO,EAAE,aAAa,EAAE,CAAC;YACzB,MAAM,OAAO,EAAE,YAAY,EAAE,CAAC;YAC9B,MAAM,aAAa,GAAG,CAAC,GAAG,CAAC,MAAM,WAAW,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,iBAAiB,EAAE,CAAC,CAAC,CAAC;YACjF,KAAK,GAAG,gBAAgB,CAAC;YACzB,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,YAAY,CAAC;YACnD,MAAM,IAAI,cAAc,CAAC,CAAC,YAAY,EAAE,GAAG,aAAa,CAAC,EAAE,+CAA+C,EAAE;gBAC1G,KAAK,EAAE,YAAY;aACpB,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,KAAK,IAAmB,EAAE;QACxC,OAAO,EAAE,aAAa,EAAE,CAAC;QACzB,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACH,MAAM,WAAW,CAAC;YACpB,CAAC;YAAC,MAAM,CAAC;gBACP,wEAAwE;gBACxE,OAAO;YACT,CAAC;QACH,CAAC;QACD,IAAI,KAAK,KAAK,gBAAgB,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO;QAE9D,KAAK,GAAG,UAAU,CAAC;QACnB,MAAM,OAAO,EAAE,YAAY,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,MAAM,WAAW,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,iBAAiB,EAAE,CAAC,CAAC,CAAC;QAC1E,KAAK,GAAG,SAAS,CAAC;QAClB,aAAa,CAAC,MAAM,EAAE,wCAAwC,CAAC,CAAC;IAClE,CAAC,CAAC;IAEF,MAAM,WAAW,GAAgB;QAC/B,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,IAAI,EAAE,GAAG,EAAE;YACT,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;gBACjC,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC,CAAC;YAC9E,CAAC;YACD,WAAW,KAAK,KAAK,EAAE,CAAC;YACxB,OAAO,WAAW,CAAC;QACrB,CAAC;QACD,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,GAAG,EAAE;YAC1B,cAAc,KAAK,OAAO,EAAE,CAAC;YAC7B,OAAO,cAAc,CAAC;QACxB,CAAC;KACF,CAAC;IAEF,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,kBAAkB,EAAE;QACrD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;YACnB,QAAQ;YACR,WAAW,EAAE,kBAAkB;SAChC,CAAC;KACH,CAAC,CAAC;IACH,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,iCAAiC,CAAC,OAAoC;IACpF,MAAM,OAAO,GAAuC,OAAO,CAAC;IAC5D,OAAO,CACL,OAAO,CAAC,4BAA4B,CAAC,EAAE,WAAW;QAClD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAgB,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,CAC/F,CAAC;AACJ,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,mBAAmB,CAAC,WAAwB;IAC1D,MAAM,OAAO,GAAuB,WAAW,CAAC;IAChD,MAAM,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC3C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,mBAAmB,CAAC,OAA2B;IACtD,MAAM,OAAO,GAAoD,OAAO,CAAC;IACzE,OAAO,OAAO,CAAC,oBAAoB,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa;IACrC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,UAAU,CAAC,+CAA+C,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAuC;IAClE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,UAAU,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;IAC/B,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,UAAU,CAAC,8CAA8C,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,wCAAwC,SAAS,CAAC,IAAI,GAAG,CAAC,CAAC;QAC7E,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,YAAY,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,aAAa,CAAC,MAA0B,EAAE,OAAe;IAChE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAChC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,KAAK,CAAC;IAC5D,MAAM,IAAI,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC"}

package/dist/commands/index.d.ts

@@ -0,0 +1,31 @@
+import { type JsonSchemaObject } from '@zmdb/schema/ir';
+import type { Container } from '../di/index.js';
+import type { ModuleClass } from '../modules/index.js';
+import '../polyfill.js';
+/** Declaration recorded by `@Command`. */
+export interface CommandDef<A> {
+    readonly name: string;
+    readonly description: string;
+    readonly args?: JsonSchemaObject;
+    readonly validate?: (raw: unknown) => A;
+    readonly positionals?: readonly string[];
+}
+/** A zero-argument command class; dependencies arrive through `@Inject` fields. */
+export type CommandClass<A> = abstract new () => {
+    run(args: A): unknown;
+};
+/** A module graph driven from argv rather than an HTTP request. */
+export interface CommandApp extends AsyncDisposable {
+    readonly container: Container;
+    run(argv?: readonly string[]): Promise<number>;
+    init(): Promise<void>;
+}
+/** Stage-3 class decorator: record one command declaration in `context.metadata`. */
+export declare function Command<A>(def: CommandDef<A>): <T extends CommandClass<A>>(target: T, context: ClassDecoratorContext<T>) => void;
+/**
+ * Compile a root module through `createApplication`, then dispatch its declared
+ * commands. The returned app never calls `process.exit`; callers own
+ * `process.exitCode`.
+ */
+export declare function createCommandApp(rootModule: ModuleClass): CommandApp;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAIxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,gBAAgB,CAAC;AAExB,0CAA0C;AAC1C,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,mFAAmF;AACnF,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,QAAQ,WAAW;IAAE,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAA;CAAE,CAAC;AAE3E,mEAAmE;AACnE,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,GAAG,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAyCD,qFAAqF;AACrF,wBAAgB,OAAO,CAAC,CAAC,EACvB,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GACjB,CAAC,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,CAInF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,WAAW,GAAG,UAAU,CAUpE"}

package/dist/commands/index.js

@@ -0,0 +1,338 @@
+// @zmdb/app — command applications (epic #497, spec ./SPEC.md).
+// Commands use the same module compilation, container and lifecycle as
+// createApplication, with argv validation at the terminal boundary and no
+// runtime reflection or HTTP router.
+import {} from '@zmdb/schema/ir';
+import { coerce } from '@zmdb/validator/advanced';
+import { applicationBridgeOf, createApplication } from '../application.js';
+import '../polyfill.js';
+const COMMAND = Symbol('zmdb.app.command');
+function commandView(metadata) {
+    return metadata;
+}
+/** Stage-3 class decorator: record one command declaration in `context.metadata`. */
+export function Command(def) {
+    return function (_target, context) {
+        commandView(context.metadata)[COMMAND] = def;
+    };
+}
+/**
+ * Compile a root module through `createApplication`, then dispatch its declared
+ * commands. The returned app never calls `process.exit`; callers own
+ * `process.exitCode`.
+ */
+export function createCommandApp(rootModule) {
+    const application = createApplication(rootModule);
+    const commands = registerCommands(applicationBridgeOf(application).compiled.commands);
+    return {
+        container: application.container,
+        init: application.init,
+        run: (argv = process.argv.slice(2)) => runCommand(commands, argv),
+        [Symbol.asyncDispose]: application[Symbol.asyncDispose],
+    };
+}
+function registerCommands(instances) {
+    const commands = [];
+    const names = new Set();
+    for (const instance of instances) {
+        const definition = commandDefinitionOf(instance);
+        if (definition === undefined) {
+            throw new Error(`@zmdb/app: ${instance.constructor.name} is listed in commands but has no @Command declaration`);
+        }
+        if (!isRunnableCommand(instance)) {
+            throw new Error(`@zmdb/app: command "${definition.name}" has no run(args) method`);
+        }
+        if (definition.name.length === 0) {
+            throw new Error('@zmdb/app: a command name cannot be empty');
+        }
+        if (names.has(definition.name)) {
+            throw new Error(`@zmdb/app: duplicate command name "${definition.name}"`);
+        }
+        names.add(definition.name);
+        commands.push(prepareCommand(instance, definition));
+    }
+    return commands;
+}
+function commandDefinitionOf(instance) {
+    const carrier = instance.constructor;
+    const metadata = carrier[Symbol.metadata];
+    if (metadata === undefined || metadata === null) {
+        return undefined;
+    }
+    return commandView(metadata)[COMMAND];
+}
+function isRunnableCommand(instance) {
+    return 'run' in instance && typeof instance.run === 'function';
+}
+function prepareCommand(instance, definition) {
+    const positionals = [...(definition.positionals ?? [])];
+    const properties = definition.args === undefined
+        ? []
+        : Object.entries(definition.args.properties)
+            .map(([name, schema]) => argumentProperty(definition.name, name, schema))
+            .toSorted((left, right) => left.option.localeCompare(right.option));
+    const propertyByName = new Map(properties.map(property => [property.name, property]));
+    const seenPositionals = new Set();
+    for (const positional of positionals) {
+        if (seenPositionals.has(positional)) {
+            throw new Error(`@zmdb/app: command "${definition.name}" repeats positional "${positional}"`);
+        }
+        seenPositionals.add(positional);
+        if (definition.args !== undefined && !propertyByName.has(positional)) {
+            throw new Error(`@zmdb/app: command "${definition.name}" names positional "${positional}" but its args type has no such property`);
+        }
+    }
+    const optionNames = new Set();
+    for (const property of properties) {
+        if (optionNames.has(property.option)) {
+            throw new Error(`@zmdb/app: command "${definition.name}" maps more than one property to --${property.option}`);
+        }
+        optionNames.add(property.option);
+    }
+    return { definition, instance, properties, propertyByName, positionals };
+}
+function argumentProperty(command, name, schema) {
+    const types = schemaTypes(schema);
+    if (types.includes('object')) {
+        throw nestedArgument(command, name);
+    }
+    if (types.includes('array')) {
+        const items = schemaKeyword(schema, 'items');
+        const itemTypes = schemaTypes(items);
+        if (itemTypes.length === 0 || itemTypes.includes('object') || itemTypes.includes('array')) {
+            throw nestedArgument(command, name);
+        }
+        const itemType = scalarType(itemTypes);
+        return {
+            name,
+            option: kebabCase(name),
+            parseType: itemType === 'boolean' ? 'boolean' : 'string',
+            multiple: true,
+            numeric: itemType === 'number' || itemType === 'integer',
+        };
+    }
+    if (schemaKeyword(schema, 'properties') !== undefined || schemaKeyword(schema, '$ref') !== undefined) {
+        throw nestedArgument(command, name);
+    }
+    const type = scalarType(types);
+    return {
+        name,
+        option: kebabCase(name),
+        parseType: type === 'boolean' ? 'boolean' : 'string',
+        multiple: false,
+        numeric: type === 'number' || type === 'integer',
+    };
+}
+function nestedArgument(command, property) {
+    return new Error(`@zmdb/app: command "${command}" argument "${property}" has a nested shape; argv must be flat`);
+}
+function schemaTypes(schema) {
+    const type = schemaKeyword(schema, 'type');
+    if (typeof type === 'string') {
+        return [type];
+    }
+    if (Array.isArray(type)) {
+        return type.filter(value => typeof value === 'string' && value !== 'null');
+    }
+    return [];
+}
+function schemaKeyword(schema, keyword) {
+    return typeof schema === 'object' && schema !== null ? Reflect.get(schema, keyword) : undefined;
+}
+function scalarType(types) {
+    return types.find(type => type !== 'null');
+}
+function kebabCase(name) {
+    return name.replaceAll(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+async function runCommand(commands, argv) {
+    const selected = selectCommand(commands, argv);
+    if (selected.kind === 'list') {
+        process.stdout.write(commandList(commands));
+        return 0;
+    }
+    if (selected.kind === 'unknown') {
+        process.stderr.write(`unknown command "${selected.name}"\n\n${commandList(commands)}`);
+        return 2;
+    }
+    if (selected.help) {
+        process.stdout.write(commandHelp(selected.command));
+        return 0;
+    }
+    let args;
+    try {
+        args = commandArguments(selected.command, selected.argv);
+    }
+    catch (error) {
+        process.stderr.write(`${lowerFirst(errorMessage(error))}\n\n${commandHelp(selected.command)}`);
+        return 2;
+    }
+    try {
+        const result = await selected.command.instance.run(args);
+        return exitCode(result);
+    }
+    catch (error) {
+        process.stderr.write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+}
+function selectCommand(commands, argv) {
+    if (commands.length === 1) {
+        const command = commands[0];
+        if (command === undefined) {
+            return { kind: 'list' };
+        }
+        const named = argv[0] === command.definition.name;
+        const commandArgv = named ? argv.slice(1) : argv;
+        return {
+            kind: 'command',
+            command,
+            argv: commandArgv,
+            help: requestsHelp(commandArgv),
+        };
+    }
+    const name = argv[0];
+    if (name === undefined || name === '--help') {
+        return { kind: 'list' };
+    }
+    const command = commands.find(candidate => candidate.definition.name === name);
+    if (command === undefined) {
+        return { kind: 'unknown', name };
+    }
+    const commandArgv = argv.slice(1);
+    return {
+        kind: 'command',
+        command,
+        argv: commandArgv,
+        help: requestsHelp(commandArgv),
+    };
+}
+function requestsHelp(argv) {
+    const terminator = argv.indexOf('--');
+    const beforeTerminator = terminator === -1 ? argv : argv.slice(0, terminator);
+    return beforeTerminator.includes('--help');
+}
+function parseCommandArgs(config) {
+    return process.getBuiltinModule('node:util').parseArgs(config);
+}
+function commandArguments(command, argv) {
+    if (command.definition.args === undefined) {
+        const parsed = parseCommandArgs({
+            args: argv,
+            allowNegative: true,
+            allowPositionals: true,
+            strict: false,
+            tokens: true,
+        });
+        const parts = positionalParts(parsed.tokens);
+        const raw = {
+            values: parsed.values,
+            positionals: parts.positionals,
+            passthrough: parts.passthrough,
+        };
+        return command.definition.validate === undefined ? raw : command.definition.validate(raw);
+    }
+    const positionalNames = new Set(command.positionals);
+    const options = {};
+    for (const property of command.properties) {
+        if (!positionalNames.has(property.name)) {
+            options[property.option] = {
+                type: property.parseType,
+                ...(property.multiple ? { multiple: true } : {}),
+            };
+        }
+    }
+    const parsed = parseCommandArgs({
+        args: argv,
+        allowNegative: command.properties.some(property => property.parseType === 'boolean'),
+        allowPositionals: true,
+        options,
+        strict: true,
+        tokens: true,
+    });
+    const parts = positionalParts(parsed.tokens);
+    if (parts.positionals.length > command.positionals.length) {
+        const unexpected = parts.positionals[command.positionals.length] ?? '';
+        throw new Error(`unexpected positional argument "${unexpected}"`);
+    }
+    const raw = {};
+    for (const property of command.properties) {
+        if (positionalNames.has(property.name)) {
+            continue;
+        }
+        const value = parsed.values[property.option];
+        if (value !== undefined) {
+            raw[property.name] = coerceArgument(property, value);
+        }
+    }
+    for (const [index, name] of command.positionals.entries()) {
+        const value = parts.positionals[index];
+        if (value === undefined) {
+            continue;
+        }
+        const property = command.propertyByName.get(name);
+        raw[name] = property === undefined ? value : coerceArgument(property, value);
+    }
+    return command.definition.validate === undefined ? raw : command.definition.validate(raw);
+}
+function positionalParts(tokens) {
+    const positionals = [];
+    const passthrough = [];
+    let afterTerminator = false;
+    for (const token of tokens) {
+        if (token.kind === 'option-terminator') {
+            afterTerminator = true;
+        }
+        else if (token.kind === 'positional' && token.value !== undefined) {
+            (afterTerminator ? passthrough : positionals).push(token.value);
+        }
+    }
+    return { positionals, passthrough };
+}
+function coerceArgument(property, value) {
+    if (property.multiple) {
+        const values = Array.isArray(value) ? value : [value];
+        return property.numeric ? values.map(item => coerce.number(item)) : values;
+    }
+    return property.numeric ? coerce.number(value) : value;
+}
+function commandList(commands) {
+    const rows = commands.length === 0
+        ? ['  (no commands registered)']
+        : commands
+            .toSorted((left, right) => left.definition.name.localeCompare(right.definition.name))
+            .map(command => `  ${command.definition.name}  ${command.definition.description}`);
+    return `Usage: <command> [options]\n\nCommands:\n${rows.join('\n')}\n`;
+}
+function commandHelp(command) {
+    const required = new Set(command.definition.args?.required ?? []);
+    const positionalNames = new Set(command.positionals);
+    const positionalUsage = command.positionals.map(name => (required.has(name) ? `<${name}>` : `[${name}]`)).join(' ');
+    const usage = `Usage: ${command.definition.name}${positionalUsage.length === 0 ? '' : ` ${positionalUsage}`}`;
+    const options = command.properties
+        .filter(property => !positionalNames.has(property.name))
+        .map(property => {
+        const value = property.parseType === 'boolean' ? '' : ` <value>${property.multiple ? '...' : ''}`;
+        const marker = required.has(property.name) ? ' (required)' : '';
+        return `  --${property.option}${value}${marker}`;
+    });
+    options.push('  --help');
+    return `${usage}\n\n${command.definition.description}\n\nOptions:\n${options.join('\n')}\n`;
+}
+function exitCode(value) {
+    if (typeof value === 'boolean') {
+        return value ? 0 : 1;
+    }
+    if (typeof value === 'number') {
+        const integer = Math.floor(value);
+        return Number.isNaN(integer) ? 1 : Math.max(0, Math.min(255, integer));
+    }
+    return 0;
+}
+function errorMessage(error) {
+    return error instanceof Error && error.message.length > 0 ? error.message : String(error);
+}
+function lowerFirst(value) {
+    return value.length === 0 ? value : `${value[0]?.toLowerCase()}${value.slice(1)}`;
+}
+//# sourceMappingURL=index.js.map