@databehave/cli 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [Unreleased]
+
+Upcoming package version: **0.2.0**. This section describes planned release contents, not a published release.
+
+### Runtime requirements
+
+- Require Node.js 24 or 26; support and test majors 24 and 26. Node.js 18, 20 and 22 are unsupported.
+
+### Added
+
+- `databehave` executable for explicit ESM configuration factories.
+- Public `defineConfig` and `run` APIs, signal-driven shutdown, idle cleanup and failure exit codes.
+- CLI ownership extracted from the previous server package; no implicit plugin discovery or installation.
+
+See [migration](../../MIGRATION.md) and [release procedures](../../docs/releasing.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ochairo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @databehave/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Requires Node.js 24 or 26; supported majors are 24 and 26. See the
+[workspace quickstart](../../README.md#start-a-mock-server) and [migration guide](../../MIGRATION.md).
+
+Run an explicit ESM plugin configuration with `databehave ./databehave.mjs`.
+Export a factory so repeated runs create fresh plugin instances:
+
+```js
+import { defineConfig } from '@databehave/cli'
+import { httpPlugin, nodeHttpPlugin, routesPlugin } from '@databehave/server'
+
+export default defineConfig(() => ({
+  plugins: [
+    httpPlugin(),
+    routesPlugin({ 'GET /hello': () => ({ json: { hello: 'world' } }) }),
+    nodeHttpPlugin({ host: '127.0.0.1', port: 8000 }),
+  ],
+}))
+```
+
+Configuration and plugins execute trusted application code. Install packages explicitly through your package
+manager. The CLI does not discover, download or install plugins. Use ordinary JavaScript imports and validate
+plugin options at their owning boundary. JSONC configurations must be migrated; see the repository migration guide.
+
+`run({ config, signal? })` returns `{ host, close }` after startup. Shutdown cancels/drains work and reports cleanup
+errors. The executable handles SIGINT/SIGTERM and exits with 2 for invalid usage or 1 for startup/cleanup failure.
+When no active resources remain, it runs cleanup and exits successfully instead of keeping an idle process alive.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { parseArguments, run } from './index.js';
+const usage = 'Usage: databehave <config.mjs>\n       databehave --help\n';
+const arguments_ = parseArguments(process.argv.slice(2));
+if (arguments_.kind === 'help')
+    process.stdout.write(usage);
+else if (arguments_.kind === 'error') {
+    process.stderr.write(`${arguments_.message}\n${usage}`);
+    process.exitCode = 2;
+}
+else {
+    const lifetime = new AbortController();
+    const stop = () => lifetime.abort();
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    // A composition with no remaining active resources should dispose and exit successfully.
+    process.once('beforeExit', stop);
+    try {
+        const handle = await run({ config: arguments_.config, signal: lifetime.signal });
+        process.stdout.write('[databehave] ready\n');
+        if (!lifetime.signal.aborted) {
+            await new Promise(resolve => lifetime.signal.addEventListener('abort', () => resolve(), { once: true }));
+        }
+        await handle.close();
+    }
+    catch (error) {
+        if (!(lifetime.signal.aborted && error instanceof Error &&
+            (error.cause === 'aborted' || error.message === 'Host closed during startup'))) {
+            console.error('[databehave] failed:', error);
+            process.exitCode = 1;
+        }
+    }
+    finally {
+        process.removeListener('SIGINT', stop);
+        process.removeListener('SIGTERM', stop);
+        process.removeListener('beforeExit', stop);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { type Host, type Plugin } from '@databehave/core';
+/** A fresh composition for one application instance. */
+export interface Configuration {
+    readonly plugins: readonly Plugin[];
+}
+/** ESM configuration factories create independent plugin instances on each invocation. */
+export type ConfigurationFactory = () => Configuration | Promise<Configuration>;
+/** Type-check a configuration factory without evaluating it or acquiring resources. */
+export declare const defineConfig: (factory: ConfigurationFactory) => ConfigurationFactory;
+/** Explicit local configuration module and optional application lifetime cancellation. */
+export interface RunOptions {
+    readonly config: string;
+    readonly signal?: AbortSignal;
+}
+/** Running host and cleanup of the caller's cancellation subscription. */
+export interface RunHandle {
+    readonly host: Host;
+    close(): Promise<void>;
+}
+/** Import only the explicitly selected local ESM module; plugins are trusted application code. */
+export declare const run: (options: RunOptions) => Promise<RunHandle>;
+/** Validated CLI arguments; feature options belong to the selected plugins. */
+export type CliArguments = {
+    readonly kind: 'help';
+} | {
+    readonly kind: 'run';
+    readonly config: string;
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+};
+export declare const parseArguments: (arguments_: readonly string[]) => CliArguments;

package/dist/index.js

@@ -0,0 +1,75 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createHost } from '@databehave/core';
+/** Type-check a configuration factory without evaluating it or acquiring resources. */
+export const defineConfig = (factory) => factory;
+const isConfiguration = (value) => {
+    if (value === null || typeof value !== 'object' || !('plugins' in value))
+        return false;
+    const plugins = value.plugins;
+    return Array.isArray(plugins) && plugins.every((plugin) => plugin !== null && typeof plugin === 'object' &&
+        'id' in plugin && typeof plugin.id === 'string' &&
+        'apiVersion' in plugin && plugin.apiVersion === 1 &&
+        'setup' in plugin && typeof plugin.setup === 'function');
+};
+const aborted = () => new Error('Application startup was cancelled', { cause: 'aborted' });
+/** Import only the explicitly selected local ESM module; plugins are trusted application code. */
+export const run = async (options) => {
+    if (options.signal?.aborted)
+        throw aborted();
+    const path = resolve(options.config);
+    if (!path.endsWith('.mjs') && !path.endsWith('.js')) {
+        throw new Error('Use an ESM .mjs or .js configuration exporting a default configuration factory; see the migration guide');
+    }
+    const module = await import(pathToFileURL(path).href);
+    if (typeof module.default !== 'function') {
+        throw new Error('Configuration must export a default factory returning { plugins: [...] }');
+    }
+    const configuration = await module.default();
+    if (!isConfiguration(configuration))
+        throw new Error('Configuration factory must return valid plugins');
+    if (options.signal?.aborted)
+        throw aborted();
+    const host = createHost(configuration);
+    let closing;
+    const close = () => {
+        if (!closing) {
+            options.signal?.removeEventListener('abort', onAbort);
+            closing = host.close();
+        }
+        return closing;
+    };
+    const onAbort = () => {
+        // Observe rejection immediately; run()/the returned handle still retain and report it.
+        void close().catch(() => { });
+    };
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        await host.start();
+        if (options.signal?.aborted) {
+            await close();
+            throw aborted();
+        }
+        return { host, close };
+    }
+    catch (error) {
+        options.signal?.removeEventListener('abort', onAbort);
+        try {
+            await close();
+        }
+        catch (cleanupError) {
+            if (cleanupError === error)
+                throw error;
+            throw new AggregateError([error, cleanupError], 'Application startup and cleanup failed', { cause: error });
+        }
+        throw error;
+    }
+};
+export const parseArguments = (arguments_) => {
+    if (arguments_.length === 1 && (arguments_[0] === '--help' || arguments_[0] === '-h'))
+        return { kind: 'help' };
+    if (arguments_.length !== 1 || !arguments_[0] || arguments_[0].startsWith('-')) {
+        return { kind: 'error', message: 'Expected one ESM configuration path' };
+    }
+    return { kind: 'run', config: arguments_[0] };
+};

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@databehave/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Explicit plugin composition for Databehave",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ochairo/databehave.git",
+    "directory": "packages/cli"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "databehave": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": "^24.0.0 || ^26.0.0"
+  },
+  "dependencies": {
+    "@databehave/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3",
+    "@types/node": "25.9.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/bin.js",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc -p tsconfig.test.json && node --test dist-test/test/*.test.js",
+    "clean": "rm -rf dist dist-test"
+  }
 }