@gobing-ai/ts-infra 0.3.20 → 0.3.22

package/README.md

@@ -614,6 +614,35 @@ Validation errors include the config file path and section name for diagnostics.
 `@gobing-ai/ts-infra` import stays portable and adapter-light. A future ADR
 may decide whether type-only re-exports are acceptable.
 
+#### CLI convenience bootstrap
+
+For fire-and-forget CLIs (Commander, Yargs, etc.), `@gobing-ai/ts-infra/application-cli`
+wraps `runNodeApplication` with the one thing every CLI does at the end: map the
+command result to a process exit code, and terminate. Same option shape, same
+defaults, same callback contract — no surprises.
+
+```ts
+import { runCliApplication } from '@gobing-ai/ts-infra/application-cli';
+import { Command } from 'commander';
+
+await runCliApplication({
+    async start(app) {
+        const program = new Command().name('mycli');
+        // ...register commands...
+        program.parse();               // Commander sets exit code on error
+        return process.exitCode;       // forward to runCliApplication
+    },
+});
+```
+
+Differences from `runNodeApplication`:
+- `start` returns `number | void` — the number becomes the exit code (void = 0)
+- On success, calls `app.stop('shutdown')` then `process.exit(code)`
+- On error, writes the message to stderr and exits 1 (after graceful teardown)
+
+Use this for CLIs. For long-running services (servers, daemons, workers), use
+`runNodeApplication` directly — it returns a runtime handle you control.
+
 ## Usage
 
 ### Install

package/dist/application-cli.d.ts

@@ -0,0 +1,59 @@
+/**
+ * CLI convenience bootstrap for `@gobing-ai/ts-infra`.
+ *
+ * Wraps {@link runNodeApplication} with the one thing every CLI does at the
+ * end: map the command result to a process exit code, and terminate. Same
+ * option shape, same defaults, same callback contract — no surprises.
+ *
+ * Differences from `runNodeApplication`:
+ * - `start` returns `number | void` instead of `void`. The number becomes the
+ *   process exit code (void = 0). This is the Commander convention.
+ * - After `start` resolves, the runtime is shut down gracefully
+ *   (`app.stop('shutdown')`) and the process terminates via `exitProcess(code)`.
+ * - If `start` throws (or startup fails), the error message is written to
+ *   stderr and the process exits with code 1. `runNodeApplication`'s built-in
+ *   reverse-order cleanup (telemetry, owned DB, user `stop` callback) runs
+ *   before the rethrow, so resources are released.
+ *
+ * Use this for fire-and-forget CLIs (Commander, Yargs, etc.). For long-running
+ * services (servers, daemons, workers), use `runNodeApplication` directly — it
+ * returns a runtime handle you control.
+ *
+ * @example
+ * ```ts
+ * import { runCliApplication } from '@gobing-ai/ts-infra/application-cli';
+ *
+ * await runCliApplication({
+ *     async start(app) {
+ *         app.logger.info('running');
+ *         return doWork(); // returns exit code
+ *     },
+ * });
+ * ```
+ */
+import type { ApplicationRuntime, ApplicationStopReason, EventMap, InfraEvents } from './application/types';
+import { type NodeApplicationOptions } from './application-node';
+/** Options for the CLI convenience {@link runCliApplication}. */
+export interface CliApplicationOptions<TAppConfig = unknown, TEvents extends EventMap = InfraEvents> extends Omit<NodeApplicationOptions<TAppConfig, TEvents>, 'start' | 'stop'> {
+    /**
+     * User callback: CLI logic. Called after all services are ready.
+     * Return a number to set the process exit code; void/undefined means success (0).
+     */
+    readonly start: (app: ApplicationRuntime<TAppConfig, TEvents>) => Promise<number | undefined> | number | undefined;
+    /**
+     * User callback: cleanup before services shut down. Receives the stop
+     * reason: `'shutdown'` on normal completion, `'error'` if `start` threw.
+     */
+    readonly stop?: (app: ApplicationRuntime<TAppConfig, TEvents>, reason: ApplicationStopReason) => Promise<void> | void;
+}
+/**
+ * CLI convenience application bootstrap.
+ *
+ * Delegates to {@link runNodeApplication} for all service lifecycle (logger,
+ * telemetry, events, DB, scheduler, plugins), then maps the `start` result to
+ * a process exit code and terminates. See the module docstring for details.
+ *
+ * @returns Never resolves — terminates the process via `exitProcess` internally.
+ */
+export declare function runCliApplication<TAppConfig = unknown, TEvents extends EventMap = InfraEvents>(options: CliApplicationOptions<TAppConfig, TEvents>): Promise<never>;
+//# sourceMappingURL=application-cli.d.ts.map

package/dist/application-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-cli.d.ts","sourceRoot":"","sources":["../src/application-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC5G,OAAO,EAAE,KAAK,sBAAsB,EAAsB,MAAM,oBAAoB,CAAC;AAErF,iEAAiE;AACjE,MAAM,WAAW,qBAAqB,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,GAAG,WAAW,CAC/F,SAAQ,IAAI,CAAC,sBAAsB,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3E;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS,CAAC;IACnH;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,CACZ,GAAG,EAAE,kBAAkB,CAAC,UAAU,EAAE,OAAO,CAAC,EAC5C,MAAM,EAAE,qBAAqB,KAC5B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,GAAG,WAAW,EAChG,OAAO,EAAE,qBAAqB,CAAC,UAAU,EAAE,OAAO,CAAC,GACpD,OAAO,CAAC,KAAK,CAAC,CAwBhB"}

package/dist/application-cli.js

@@ -0,0 +1,68 @@
+/**
+ * CLI convenience bootstrap for `@gobing-ai/ts-infra`.
+ *
+ * Wraps {@link runNodeApplication} with the one thing every CLI does at the
+ * end: map the command result to a process exit code, and terminate. Same
+ * option shape, same defaults, same callback contract — no surprises.
+ *
+ * Differences from `runNodeApplication`:
+ * - `start` returns `number | void` instead of `void`. The number becomes the
+ *   process exit code (void = 0). This is the Commander convention.
+ * - After `start` resolves, the runtime is shut down gracefully
+ *   (`app.stop('shutdown')`) and the process terminates via `exitProcess(code)`.
+ * - If `start` throws (or startup fails), the error message is written to
+ *   stderr and the process exits with code 1. `runNodeApplication`'s built-in
+ *   reverse-order cleanup (telemetry, owned DB, user `stop` callback) runs
+ *   before the rethrow, so resources are released.
+ *
+ * Use this for fire-and-forget CLIs (Commander, Yargs, etc.). For long-running
+ * services (servers, daemons, workers), use `runNodeApplication` directly — it
+ * returns a runtime handle you control.
+ *
+ * @example
+ * ```ts
+ * import { runCliApplication } from '@gobing-ai/ts-infra/application-cli';
+ *
+ * await runCliApplication({
+ *     async start(app) {
+ *         app.logger.info('running');
+ *         return doWork(); // returns exit code
+ *     },
+ * });
+ * ```
+ */
+import { echoError, exitProcess } from '@gobing-ai/ts-utils';
+import { runNodeApplication } from './application-node.js';
+/**
+ * CLI convenience application bootstrap.
+ *
+ * Delegates to {@link runNodeApplication} for all service lifecycle (logger,
+ * telemetry, events, DB, scheduler, plugins), then maps the `start` result to
+ * a process exit code and terminates. See the module docstring for details.
+ *
+ * @returns Never resolves — terminates the process via `exitProcess` internally.
+ */
+export async function runCliApplication(options) {
+    let exitCode = 0;
+    try {
+        const app = await runNodeApplication({
+            ...options,
+            start: async (runtime) => {
+                const code = await options.start(runtime);
+                if (typeof code === 'number')
+                    exitCode = code;
+            },
+        });
+        // `start` completed — graceful reverse-order shutdown of all services.
+        await app.stop('shutdown');
+    }
+    catch (error) {
+        // Startup failure OR `start` threw. `runNodeApplication`'s catch block
+        // already ran stopAll/unloadAll on whatever started, so resources are
+        // released. We just normalize the exit code and surface the message.
+        exitCode = 1;
+        const msg = error instanceof Error ? error.message : String(error);
+        echoError(`Error: ${msg}`);
+    }
+    return exitProcess(exitCode);
+}

package/dist/event-bus/event-bus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/event-bus/event-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAa,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,KAAK,EAER,oBAAoB,EACpB,kBAAkB,EAElB,QAAQ,EAER,gBAAgB,EACnB,MAAM,SAAS,CAAC;AAQjB;;;GAGG;AACH,qBAAa,QAAQ,CAAC,OAAO,SAAS,QAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyD;IACtF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyD;IACvF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6C;IAC7E,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6C;IAC/E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,kBAAkB,CAAK;gBACnB,IAAI,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,QAAQ,CAAC;QACpB,YAAY,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;QAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;KACnB;IAMD,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAQzF,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAS3F,GAAG,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAmBjE,kBAAkB,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI;IAgBtD,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkF7F,aAAa,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM;IAMjF,UAAU,IAAI,MAAM,EAAE;IAOtB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,aAAa;IAkBrB,OAAO,CAAC,iBAAiB;IAUzB,6EAA6E;IAC7E,OAAO,CAAC,4BAA4B;IAWpC;;;;;;;;;;;;OAYG;IACH,gBAAgB,IAAI,UAAU,CAAC,oBAAoB,CAAC;IAepD,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,oBAAoB;CAU/B"}
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/event-bus/event-bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAa,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,KAAK,EAER,oBAAoB,EACpB,kBAAkB,EAElB,QAAQ,EAER,gBAAgB,EACnB,MAAM,SAAS,CAAC;AAQjB;;;GAGG;AACH,qBAAa,QAAQ,CAAC,OAAO,SAAS,QAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyD;IACtF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyD;IACvF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6C;IAC7E,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6C;IAC/E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,kBAAkB,CAAK;gBACnB,IAAI,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,QAAQ,CAAC;QACpB,YAAY,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;QAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;KACnB;IAMD,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAQzF,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAS3F,GAAG,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAmBjE,kBAAkB,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI;IAgBtD,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAoF7F,aAAa,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM;IAMjF,UAAU,IAAI,MAAM,EAAE;IAOtB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,aAAa;IAkBrB,OAAO,CAAC,iBAAiB;IAUzB,6EAA6E;IAC7E,OAAO,CAAC,4BAA4B;IAWpC;;;;;;;;;;;;OAYG;IACH,gBAAgB,IAAI,UAAU,CAAC,oBAAoB,CAAC;IAepD,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,oBAAoB;CAU/B"}

package/dist/event-bus/event-bus.js

@@ -141,6 +141,8 @@ export class EventBus {
         }
         const durationMs = performance.now() - startMs;
         const detail = args.length === 1 ? args[0] : args.length > 1 ? args : undefined;
+        // Metrics are emitted inline here; traces (span attributes + events) are attached
+        // by attachTelemetryObserver in default-observers.ts — see that file for the trace layer.
         getEventbusEmitsTotal().add(1, { event: eventName });
         if (errors > 0)
             getEventbusErrorsTotal().add(errors, { event: eventName });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-infra",
-    "version": "0.3.20",
+    "version": "0.3.22",
     "description": "@gobing-ai/ts-infra — Infrastructure backbone: event bus, job queue, scheduler, telemetry, API client, and logging.",
     "keywords": [
         "typescript",
@@ -55,6 +55,10 @@
         "./application-node": {
             "types": "./dist/application-node.d.ts",
             "import": "./dist/application-node.js"
+        },
+        "./application-cli": {
+            "types": "./dist/application-cli.d.ts",
+            "import": "./dist/application-cli.js"
         }
     },
     "files": [
@@ -74,11 +78,12 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-infra-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
+        "@gobing-ai/ts-utils": "^0.3.22",
         "@logtape/logtape": "^2.0.0"
     },
     "peerDependencies": {
-        "@gobing-ai/ts-db": "^0.3.20",
-        "@gobing-ai/ts-runtime": "^0.3.20",
+        "@gobing-ai/ts-db": "^0.3.22",
+        "@gobing-ai/ts-runtime": "^0.3.22",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",
         "@opentelemetry/sdk-metrics": "^2.0.0",
@@ -111,8 +116,8 @@
         }
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.3.20",
-        "@gobing-ai/ts-runtime": "^0.3.20",
+        "@gobing-ai/ts-db": "^0.3.22",
+        "@gobing-ai/ts-runtime": "^0.3.22",
         "@types/bun": "1.3.14",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",

package/src/application-cli.ts

@@ -0,0 +1,92 @@
+/**
+ * CLI convenience bootstrap for `@gobing-ai/ts-infra`.
+ *
+ * Wraps {@link runNodeApplication} with the one thing every CLI does at the
+ * end: map the command result to a process exit code, and terminate. Same
+ * option shape, same defaults, same callback contract — no surprises.
+ *
+ * Differences from `runNodeApplication`:
+ * - `start` returns `number | void` instead of `void`. The number becomes the
+ *   process exit code (void = 0). This is the Commander convention.
+ * - After `start` resolves, the runtime is shut down gracefully
+ *   (`app.stop('shutdown')`) and the process terminates via `exitProcess(code)`.
+ * - If `start` throws (or startup fails), the error message is written to
+ *   stderr and the process exits with code 1. `runNodeApplication`'s built-in
+ *   reverse-order cleanup (telemetry, owned DB, user `stop` callback) runs
+ *   before the rethrow, so resources are released.
+ *
+ * Use this for fire-and-forget CLIs (Commander, Yargs, etc.). For long-running
+ * services (servers, daemons, workers), use `runNodeApplication` directly — it
+ * returns a runtime handle you control.
+ *
+ * @example
+ * ```ts
+ * import { runCliApplication } from '@gobing-ai/ts-infra/application-cli';
+ *
+ * await runCliApplication({
+ *     async start(app) {
+ *         app.logger.info('running');
+ *         return doWork(); // returns exit code
+ *     },
+ * });
+ * ```
+ */
+
+import { echoError, exitProcess } from '@gobing-ai/ts-utils';
+import type { ApplicationRuntime, ApplicationStopReason, EventMap, InfraEvents } from './application/types';
+import { type NodeApplicationOptions, runNodeApplication } from './application-node';
+
+/** Options for the CLI convenience {@link runCliApplication}. */
+export interface CliApplicationOptions<TAppConfig = unknown, TEvents extends EventMap = InfraEvents>
+    extends Omit<NodeApplicationOptions<TAppConfig, TEvents>, 'start' | 'stop'> {
+    /**
+     * User callback: CLI logic. Called after all services are ready.
+     * Return a number to set the process exit code; void/undefined means success (0).
+     */
+    readonly start: (app: ApplicationRuntime<TAppConfig, TEvents>) => Promise<number | undefined> | number | undefined;
+    /**
+     * User callback: cleanup before services shut down. Receives the stop
+     * reason: `'shutdown'` on normal completion, `'error'` if `start` threw.
+     */
+    readonly stop?: (
+        app: ApplicationRuntime<TAppConfig, TEvents>,
+        reason: ApplicationStopReason,
+    ) => Promise<void> | void;
+}
+
+/**
+ * CLI convenience application bootstrap.
+ *
+ * Delegates to {@link runNodeApplication} for all service lifecycle (logger,
+ * telemetry, events, DB, scheduler, plugins), then maps the `start` result to
+ * a process exit code and terminates. See the module docstring for details.
+ *
+ * @returns Never resolves — terminates the process via `exitProcess` internally.
+ */
+export async function runCliApplication<TAppConfig = unknown, TEvents extends EventMap = InfraEvents>(
+    options: CliApplicationOptions<TAppConfig, TEvents>,
+): Promise<never> {
+    let exitCode = 0;
+
+    try {
+        const app = await runNodeApplication<TAppConfig, TEvents>({
+            ...options,
+            start: async (runtime) => {
+                const code = await options.start(runtime);
+                if (typeof code === 'number') exitCode = code;
+            },
+        });
+
+        // `start` completed — graceful reverse-order shutdown of all services.
+        await app.stop('shutdown');
+    } catch (error) {
+        // Startup failure OR `start` threw. `runNodeApplication`'s catch block
+        // already ran stopAll/unloadAll on whatever started, so resources are
+        // released. We just normalize the exit code and surface the message.
+        exitCode = 1;
+        const msg = error instanceof Error ? error.message : String(error);
+        echoError(`Error: ${msg}`);
+    }
+
+    return exitProcess(exitCode);
+}

package/src/event-bus/event-bus.ts

@@ -163,6 +163,8 @@ export class EventBus<TEvents extends EventMap> {
         const durationMs = performance.now() - startMs;
         const detail = args.length === 1 ? args[0] : args.length > 1 ? args : undefined;
 
+        // Metrics are emitted inline here; traces (span attributes + events) are attached
+        // by attachTelemetryObserver in default-observers.ts — see that file for the trace layer.
         getEventbusEmitsTotal().add(1, { event: eventName });
         if (errors > 0) getEventbusErrorsTotal().add(errors, { event: eventName });