@db3.ai/app 0.1.0-beta.1

package/src/cli/README.md

@@ -0,0 +1,164 @@
+# Command line
+
+`@db3.ai/app/cli` owns the shared `db3` executable, command help, positional
+argument validation, output and application shutdown. Each service owns its
+commands and calls the same programmatic operations used by application code.
+Applications register the services they use in `server/cli.config.ts`.
+
+## In a generated app
+
+From the app root:
+
+```sh
+npx db3 --help
+npx db3 repl
+npx db3 db:migrate
+npx db3 db:check
+npx db3 queue:make-job GenerateReportJob
+npm run db:make:migration -- add_note_field
+```
+
+The starter also provides `npm run repl` and `npm run db3 -- <command>`.
+`npx` resolves the installed package executable; `node db3 repl` would require
+an app-owned file called `db3`, which generated apps do not need.
+
+## Explore the app
+
+`npx db3 repl` starts a terminal session using the same `createApp` factory as
+the other commands. It starts no HTTP listener. JavaScript expressions support
+top-level `await` and variables persist between inputs:
+
+```js
+app().directory
+await Note.query().limit(5).all()
+await app().db.migrations.status()
+```
+
+The REPL loads the exported `models` array from `server/database/models.ts`
+(`.mjs` and `.js` are also accepted). Named constructors are available directly,
+such as `Note`, and through `models.Note`. Apps without this registry still have
+`app()` and an empty `models` object. Duplicate and reserved model names fail
+with an explanation. The app factory and registry share one TypeScript module
+scope, preserving constructor identity and ActiveRecord's app context.
+
+Use `.help` for Node REPL commands, `.clear` to reset variables and restore app
+bindings, and `.exit` or Ctrl+D to quit. The CLI awaits `App.close()` afterwards,
+including when model loading or terminal input fails. This is a terminal JavaScript
+REPL. It uses the app's configured services and database, so commands have the
+same effects as server code.
+
+Development tools can reuse `runRepl({ values, input, output })` from
+`@db3.ai/app/cli`; the caller owns app startup and shutdown. `runDb3()` accepts
+`input` and `output` streams for its interactive command in addition to the
+existing line-output adapters.
+
+The migration-generation npm script type-checks the app before invoking
+`db3 db:make-migration`. The direct command uses runtime model validation;
+it does not run the application's TypeScript checker. Review generated source
+before applying it. `db:check` returns a nonzero exit status for drift, pending
+migrations or missing migration files. Unsafe generation remains blocked by
+the database service, and source generation is refused in production.
+
+## Register service commands
+
+The starter keeps this configuration under `server/cli.config.ts`:
+
+```ts
+import type { CliConfig } from '@db3.ai/app/cli';
+import { databaseCommands } from '@db3.ai/app/db/commands';
+import { createApplication } from './app';
+import { readConfig } from './config';
+
+export default {
+	/** Creates the app without starting an HTTP listener. */
+	createApp: () => createApplication(readConfig()),
+	commands: databaseCommands,
+} satisfies CliConfig;
+```
+
+The loader also accepts `server/cli.config.mjs` or `.js`, checking `.ts` first.
+Run from the app root. Registration modules should declare factories and
+commands without opening connections or starting listeners at import time.
+Help and usage errors do not call `createApp`. Actions registered with
+`defineCommand()` run after the app is created, so they can use `app()` and
+ActiveRecord normally. The runner awaits
+`App.close()` after success or failure. App subclasses must close any additional
+resources they own.
+
+`repl` is registered by the framework and requires an app factory.
+`queue:make-job` is registered by the framework and works without an app configuration.
+Other service commands are explicitly registered. Duplicate command names fail
+instead of silently overriding another service. The interactive REPL keeps its
+invocation open until session exit. Long-running workers and their signal/drain
+policies remain owned by their existing worker entry points.
+
+## Service, command and action
+
+Commands use `service:action` names, with one action function per file and a
+small registration index inside the service:
+
+```text
+db/commands/
+	migrate.ts
+	check.ts
+	makeMigration.ts
+	index.ts
+```
+
+For example, the `migrate.ts` action calls `app().db.migrations.migrate()` and
+returns its normal result. It does not print output or decide process exit
+codes. `DatabaseOptions.migrations` supplies the app's model registry and policy.
+Migration files and the schema snapshot use the framework's fixed
+`server/database/` paths relative to `app().directory`; no separate migration
+configuration file is needed.
+
+The service index imports its actions and registers them through `defineCommand()`:
+
+```ts
+import { defineCommand } from '@db3.ai/app/cli';
+import makeMigration from './makeMigration';
+
+export const databaseCommands = [defineCommand({
+	name: 'db:make-migration',
+	description: 'Generate a migration from model changes.',
+	parameters: [{ name: 'name' }],
+	/** Passes named CLI parameters to the ordinary action function. */
+	handle: parameters => makeMigration({ name: parameters.name }),
+	exitCode: result => result.blocked ? 1 : 0,
+})];
+```
+
+Positional values map to declared parameter names; required parameters precede
+optional ones. Unknown flags and extra values fail before app startup. The
+adapter formats results for the terminal and maps domain results to exit codes.
+Use `needsApp: false` for operations such as source generation that do not need
+an application. `formatResult` can provide a concise terminal message.
+
+Export the action functions and command index through a supported service
+subpath. An app registers the index in its `commands` array. This explicit index
+makes it clear which files are callable commands. Database actions are exported
+from `@db3.ai/app/db/commands`, and Queue actions from `@db3.ai/app/queue/commands`.
+
+A future UI's authenticated server handler can call the same action, such as
+`migrate()`, within its existing app context and receive a normal result. Command
+registration does not expose an HTTP endpoint or grant permission to execute it.
+Validation and business rules remain in the underlying service operation.
+
+For embedded terminal execution, `new Cli(config, options).run(args)` returns
+an exit status and accepts output adapters. The lower-level `CliCommand` contract
+also supports custom adapters that manage their own parameter mapping.
+Run one app-backed command at a time within a process, matching the framework's
+process-global active application. An already running app should call the
+underlying service operation directly rather than create a second app via CLI.
+
+## Verification
+
+```sh
+npm run test:service --workspace @db3.ai/app -- cli
+```
+
+Runner tests cover help, validation, duplicate registration, lazy startup,
+failure cleanup and the real executable's TypeScript configuration loading.
+Database command tests live under the DB service and use disposable MariaDB
+databases. Release verification installs the packed framework into a generated
+app, then generates, applies and checks actual migrations through `db3`.

package/src/cli/commands/repl.ts

@@ -0,0 +1,29 @@
+import { runRepl } from '../runRepl';
+import type { CliCommand, CliOptions } from '../contracts';
+
+/**
+ * Registers the application REPL using the same module scope as app bootstrap.
+ *
+ * @param loadModels - Loads the conventional app model registry only when invoked.
+ * @param options - Terminal stream adapters for interactive or embedded callers.
+ * @returns Built-in command whose app lifecycle remains owned by the CLI runner.
+ */
+export function createReplCommand(loadModels: () => Promise<Record<string, unknown>>, options: CliOptions): CliCommand {
+	return {
+		name: 'repl', description: 'Explore the application and its models in an interactive terminal.',
+		/** Boots the app without an HTTP listener and keeps it alive until REPL exit. */
+		async run(context) {
+			const application = await context.app();
+			const models = await loadModels();
+			context.write('DB3 REPL. Use app(), models and model names. Type .exit or press Ctrl+D to quit.');
+			await runRepl({
+				input: options.input, output: options.output,
+				values: {
+					...models, models,
+					/** Returns the invocation's live application service hub. */
+					app: () => application,
+				},
+			});
+		},
+	};
+}

package/src/cli/contracts/CliCommand.ts

@@ -0,0 +1,33 @@
+import type { App } from '../../server';
+
+/** One positional value accepted by a command, in declaration order. */
+export interface CliArgument {
+	/** Name displayed in command usage. */
+	name: string;
+	/** Whether omission is a usage error. Required arguments precede optional ones. */
+	required?: boolean;
+}
+
+/** Invocation state supplied by the runner to a service-owned command. */
+export interface CliCommandContext {
+	/** Validated positional values, excluding the command name. */
+	args: readonly string[];
+	/** Absolute application root used for app-owned source generation. */
+	directory: string;
+	/** Lazily creates one application, which the runner closes after execution. */
+	app(): Promise<App>;
+	/** Writes one user-facing output message. */
+	write(message: string): void;
+}
+
+/** A service or application command, backed by its existing programmatic operation. */
+export interface CliCommand {
+	/** Unique command name, for example db:migrate or queue:make-job. */
+	name: string;
+	/** Short explanation shown by db3 --help. */
+	description: string;
+	/** Positional argument declarations used for validation and help. */
+	arguments?: readonly CliArgument[];
+	/** Executes the operation; return a nonzero status for a reported failure. */
+	run(context: CliCommandContext): number | void | Promise<number | void>;
+}

package/src/cli/contracts/CliConfig.ts

@@ -0,0 +1,10 @@
+import type { App } from '../../server';
+import type { CliCommand } from './CliCommand';
+
+/** App-owned command registration exported by server/cli.config.ts. */
+export interface CliConfig {
+	/** Creates the app only when a command requests it; do not start an HTTP listener. */
+	createApp?: () => App | Promise<App>;
+	/** Commands exposed by configured services or by the application itself. */
+	commands: readonly CliCommand[];
+}

package/src/cli/contracts/CliOptions.ts

@@ -0,0 +1,13 @@
+/** Process adapters shared by direct CLI execution and embedded command runners. */
+export interface CliOptions {
+	/** Application root. Defaults to the current working directory. */
+	directory?: string;
+	/** Interactive input used by `db3 repl`. Defaults to process.stdin. */
+	input?: NodeJS.ReadableStream;
+	/** Interactive output used by `db3 repl`. Defaults to process.stdout. */
+	output?: NodeJS.WritableStream;
+	/** Standard output adapter. Defaults to console.log. */
+	write?: (message: string) => void;
+	/** Error output adapter. Defaults to console.error. */
+	writeError?: (message: string) => void;
+}

package/src/cli/contracts/CommandDefinition.ts

@@ -0,0 +1,19 @@
+import type { CliArgument, CliCommandContext } from './CliCommand';
+
+/** A named action adapted for terminal invocation without coupling the action to output or exit codes. */
+export interface CommandDefinition<TResult> {
+	/** Service:action command name, for example db:make-migration. */
+	name: string;
+	/** Short help description. */
+	description: string;
+	/** Positional arguments mapped by name before invoking the handler. */
+	parameters?: readonly CliArgument[];
+	/** Defaults to true; false is for source generators that need no running application. */
+	needsApp?: boolean;
+	/** Calls the service action with named arguments; validation remains in that action. */
+	handle(parameters: Readonly<Record<string, string | undefined>>, context: CliCommandContext): TResult | Promise<TResult>;
+	/** Maps a domain result to a terminal exit code. Defaults to success. */
+	exitCode?: (result: TResult) => number;
+	/** Optional terminal presentation; direct action callers still receive the original result. */
+	formatResult?: (result: TResult) => string;
+}

package/src/cli/contracts/ReplOptions.ts

@@ -0,0 +1,11 @@
+/** Terminal REPL context and streams, reusable by application development tools. */
+export interface ReplOptions {
+	/** Named values available to expressions; installed again after `.clear`. */
+	values: Readonly<Record<string, unknown>>;
+	/** Prompt shown before each expression. Defaults to `db3> `. */
+	prompt?: string;
+	/** Input stream. Defaults to the current process's standard input. */
+	input?: NodeJS.ReadableStream;
+	/** Output stream. Defaults to the current process's standard output. */
+	output?: NodeJS.WritableStream;
+}

package/src/cli/contracts/index.ts

@@ -0,0 +1,5 @@
+export type * from './CliCommand';
+export type * from './CliConfig';
+export type * from './CliOptions';
+export type * from './CommandDefinition';
+export type * from './ReplOptions';

package/src/cli/defineCommand.ts

@@ -0,0 +1,25 @@
+import type * as cli from './contracts';
+
+/**
+ * Registers an app-context action with named argument mapping and terminal result formatting.
+ *
+ * Export action functions separately so UI and programmatic callers receive normal
+ * results without terminal output. The runner owns the application lifecycle.
+ * @param definition - Service action, parameters and optional result-to-exit-code mapping.
+ * @returns Command suitable for app or service registration.
+ */
+export function defineCommand<TResult>(definition: cli.CommandDefinition<TResult>): cli.CliCommand {
+	return {
+		name: definition.name,
+		description: definition.description,
+		arguments: definition.parameters,
+		/** Establishes app context, maps parameters and adapts the action result for the terminal. */
+		async run(context) {
+			if (definition.needsApp !== false) await context.app();
+			const parameters = Object.fromEntries((definition.parameters ?? []).map((parameter, index) => [parameter.name, context.args[index]]));
+			const result = await definition.handle(parameters, context);
+			if (result !== undefined) context.write(definition.formatResult ? definition.formatResult(result) : typeof result === 'string' ? result : JSON.stringify(result, null, 2));
+			return definition.exitCode?.(result) ?? 0;
+		},
+	};
+}

package/src/cli/index.ts

@@ -0,0 +1,5 @@
+export * from './contracts';
+export * from './Cli';
+export * from './runDb3';
+export * from './defineCommand';
+export * from './runRepl';

package/src/cli/runDb3.ts

@@ -0,0 +1,63 @@
+import { access } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { register, type ScopedImport } from 'tsx/esm/api';
+import { Cli } from './Cli';
+import { createReplCommand } from './commands/repl';
+import type * as cli from './contracts';
+
+/**
+ * Loads app registration and runs the framework CLI from source or an installed package.
+ *
+ * TypeScript config loading supports the same extensionless imports as the starter.
+ * No HTTP listener is started. Help and queue:make-job do not create the app.
+ * @param argv - Arguments after db3.
+ * @param options - Application root and optional output adapters.
+ * @returns Exit status to assign to process.exitCode.
+ */
+export async function runDb3(argv: readonly string[], options: cli.CliOptions = {}): Promise<number> {
+	const loader = register({ namespace: `db3-cli-${randomUUID()}` });
+	try {
+		const { queueCommands } = await import('../queue/commands');
+		const directory = resolve(options.directory ?? process.cwd());
+		const configModule = await loadAppModule(directory, 'server/cli.config', loader.import);
+		const config: cli.CliConfig = configModule ? configModule.default : { commands: [] };
+		// Validate app config before combining it with commands that need no app bootstrap.
+		if (!config || !Array.isArray(config.commands)) throw new Error('CLI configuration must export a commands array.');
+		const repl = createReplCommand(async () => loadReplModels(directory, loader.import), options);
+		return await new Cli({ ...config, commands: [repl, ...queueCommands, ...config.commands] }, { ...options, directory }).run(argv);
+	} catch (error) {
+		(options.writeError ?? console.error)(error instanceof Error ? error.message : 'Unable to load CLI configuration.');
+		return 1;
+	} finally {
+		await loader.unregister();
+	}
+}
+
+/** Loads an optional conventional app module without hiding errors from its imports. */
+async function loadAppModule(directory: string, path: string, importModule: ScopedImport): Promise<Record<string, any> | undefined> {
+	for (const extension of ['ts', 'mjs', 'js']) {
+		const file = resolve(directory, `${path}.${extension}`);
+		try { await access(file); } catch (error) {
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+			throw error;
+		}
+		return importModule(pathToFileURL(file).href, import.meta.url);
+	}
+	return undefined;
+}
+
+/** Exposes named model constructors from the same registry used by app migrations. */
+async function loadReplModels(directory: string, importModule: ScopedImport): Promise<Record<string, unknown>> {
+	const module = await loadAppModule(directory, 'server/database/models', importModule);
+	if (!module) return {};
+	if (!Array.isArray(module.models)) throw new Error('server/database/models must export a models array for the REPL.');
+	const models: Record<string, unknown> = Object.create(null);
+	for (const model of module.models) {
+		if (typeof model !== 'function' || !/^[A-Za-z_$][\w$]*$/.test(model.name)) throw new Error('REPL models must be named constructors.');
+		if (['app', 'models', '__proto__', 'constructor', 'prototype'].includes(model.name) || Object.hasOwn(models, model.name)) throw new Error(`Duplicate or reserved REPL model name: ${model.name}`);
+		models[model.name] = model;
+	}
+	return models;
+}

package/src/cli/runRepl.ts

@@ -0,0 +1,55 @@
+import { start } from 'node:repl';
+import { inspect } from 'node:util';
+import type { ReplOptions } from './contracts';
+
+/**
+ * Runs a Node terminal REPL until `.exit`, end-of-input or a stream failure.
+ *
+ * Expressions support top-level await and persistent variables. Context values
+ * stay inside the REPL's VM rather than becoming process-wide globals. The
+ * caller retains ownership of its application and closes it after this resolves.
+ *
+ * @param options - Context values, prompt and optional terminal streams.
+ * @returns Resolves after the terminal session exits; rejects on stream errors.
+ */
+export async function runRepl(options: ReplOptions): Promise<void> {
+	const input: NodeJS.ReadableStream = options.input ?? process.stdin;
+	const output: NodeJS.WritableStream = options.output ?? process.stdout;
+	const terminal = Boolean((output as NodeJS.WriteStream).isTTY);
+	const session = start({
+		prompt: options.prompt ?? 'db3> ', input, output, terminal,
+		useGlobal: false, ignoreUndefined: true,
+		/** Formats results without invoking arbitrary model or service getters. */
+		writer: value => inspect(value, { colors: terminal, depth: 6, getters: false }),
+	});
+	/** Restores the app bindings when Node creates or clears the session context. */
+	function installValues(): void {
+		for (const [name, value] of Object.entries(options.values)) {
+			Object.defineProperty(session.context, name, { value, configurable: true, enumerable: true, writable: true });
+		}
+	}
+	try {
+		installValues();
+		session.on('reset', installValues);
+		await new Promise<void>((resolve, reject) => {
+			/** Releases stream listeners after normal exit or failure. */
+			function cleanup(): void {
+				input.off('error', fail);
+				output.off('error', fail);
+				session.off('error', fail);
+				session.off('exit', finish);
+			}
+			/** Completes the session after Node has processed its exit command. */
+			function finish(): void { cleanup(); resolve(); }
+			/** Preserves the original stream failure while releasing the REPL. */
+			function fail(error: Error): void { cleanup(); session.close(); reject(error); }
+			input.once('error', fail);
+			output.once('error', fail);
+			session.once('error', fail);
+			session.once('exit', finish);
+		});
+	} finally {
+		session.off('reset', installValues);
+		session.close();
+	}
+}

package/src/config/Config.ts

@@ -0,0 +1,110 @@
+export type ConfigValues = Record<string, unknown>;
+
+/**
+ * Runtime configuration repository with dot-path reads.
+ */
+export class Config<TValues extends ConfigValues = ConfigValues> {
+	/**
+	 * Creates a config repository from a plain object.
+	 *
+	 * @param values - Config values to expose.
+	 */
+	constructor(private readonly values: TValues = {} as TValues) {}
+
+	/**
+	 * Returns all config values.
+	 *
+	 * @returns Config object supplied to this repository.
+	 */
+	all(): TValues {
+		return this.values;
+	}
+
+	/**
+	 * Reads a config value by dot path.
+	 *
+	 * @param path - Dot-separated config path.
+	 * @returns Config value or undefined when the path is missing.
+	 */
+	get<TValue = unknown>(path: string): TValue | undefined;
+	/**
+	 * Reads a config value by dot path with a fallback.
+	 *
+	 * @param path - Dot-separated config path.
+	 * @param fallback - Value to return when the path is missing.
+	 * @returns Config value or fallback.
+	 */
+	get<TValue>(path: string, fallback: TValue): TValue;
+	get<TValue>(path: string, fallback?: TValue): TValue | undefined {
+		const result = resolveConfigPath(this.values, path);
+
+		if (!result.exists) return fallback;
+
+		return result.value as TValue;
+	}
+
+	/**
+	 * Returns true when a dot path exists in this config repository.
+	 *
+	 * @param path - Dot-separated config path.
+	 * @returns True when the path exists.
+	 */
+	has(path: string): boolean {
+		return resolveConfigPath(this.values, path).exists;
+	}
+}
+
+/**
+ * Defines a typed config object without changing its runtime shape.
+ *
+ * @param values - Config values to preserve.
+ * @returns The same config values.
+ */
+export function defineConfig<TValues extends ConfigValues>(values: TValues): TValues {
+	return values;
+}
+
+/**
+ * Resolves a dot path against a config object.
+ *
+ * @param values - Config object to inspect.
+ * @param path - Dot-separated config path.
+ * @returns Resolution result containing existence and value.
+ */
+function resolveConfigPath(values: ConfigValues, path: string): {
+	exists: boolean;
+	value?: unknown;
+} {
+	if (!path) {
+		throw new Error('Config path cannot be empty.');
+	}
+
+	const segments = path.split('.');
+
+	if (segments.some(segment => !segment)) {
+		throw new Error(`Config path "${path}" contains an empty segment.`);
+	}
+
+	let current: unknown = values;
+
+	for (const segment of segments) {
+		if (typeof current !== 'object' || current === null || Array.isArray(current)) {
+			return {
+				exists: false,
+			};
+		}
+
+		if (!Object.hasOwn(current, segment)) {
+			return {
+				exists: false,
+			};
+		}
+
+		current = (current as Record<string, unknown>)[segment];
+	}
+
+	return {
+		exists: true,
+		value: current,
+	};
+}