@zmdb/cli 1.0.0-beta.1

package/src/lifecycle.ts

@@ -0,0 +1,73 @@
+import type { ResolvedConfig } from '@zmdb/compiler/config';
+
+/** Own only the driver requested during this invocation, including non-enumerable disposal methods. */
+export async function withConfiguredDriver<T>(
+  config: ResolvedConfig,
+  run: (config: ResolvedConfig) => Promise<T>,
+): Promise<T> {
+  const create = config.driver;
+  if (create === undefined) return run(config);
+  let opened: Awaited<ReturnType<typeof create>> | undefined;
+  let pending: Promise<Awaited<ReturnType<typeof create>>> | undefined;
+  let outcome: { readonly ok: true; readonly value: T } | { readonly ok: false; readonly error: unknown };
+  try {
+    outcome = {
+      ok: true,
+      value: await run({
+        ...config,
+        driver() {
+          pending ??= Promise.resolve()
+            .then(create)
+            .then(driver => {
+              opened = driver;
+              return driver;
+            });
+          return pending;
+        },
+      }),
+    };
+  } catch (error) {
+    outcome = { ok: false, error };
+  }
+  try {
+    if (opened !== undefined) {
+      const disposeAsync: unknown = Reflect.get(opened, Symbol.asyncDispose);
+      const dispose: unknown = Reflect.get(opened, Symbol.dispose);
+      if (typeof disposeAsync === 'function') await disposeAsync.call(opened);
+      else if (typeof dispose === 'function') dispose.call(opened);
+    }
+  } catch (cleanupError) {
+    if (!outcome.ok) throw new SuppressedError(cleanupError, outcome.error, 'command and driver cleanup failed');
+    throw cleanupError;
+  }
+  if (!outcome.ok) throw outcome.error;
+  return outcome.value;
+}
+
+/** Translate process termination into the command's existing cancellable lifetime. */
+export async function withSignals<T>(run: (until: Promise<void>) => Promise<T>): Promise<T | undefined> {
+  const until = Promise.withResolvers<void>();
+  let interrupted = false;
+  const stop = (): void => {
+    interrupted = true;
+    until.resolve();
+  };
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+  try {
+    return await run(until.promise);
+  } catch (error) {
+    // A terminal signal also terminates the TypeScript child in the same process group.
+    // The watch has already run its cleanup before this closed-channel error arrives.
+    if (
+      interrupted &&
+      error instanceof Error &&
+      error.message.startsWith('Unexpected EOF while reading from child process')
+    )
+      return undefined;
+    throw error;
+  } finally {
+    process.off('SIGINT', stop);
+    process.off('SIGTERM', stop);
+  }
+}

package/src/migration-project.ts

@@ -0,0 +1,91 @@
+import type { ResolvedConfig } from '@zmdb/compiler/config';
+import { schemasFromFiles } from '@zmdb/compiler/testing';
+import type { MigrationDriver, MigrationProject, SnapshotableSchema } from '@zmdb/migrations';
+import { emitDeclarations } from '@zmdb/migrations/declarations';
+import { dialectName, type Introspector } from '@zmdb/sql';
+import type { FormatConfig } from 'oxfmt';
+
+import { configuredIntrospector } from './database.js';
+import { CliInvocationError } from './errors.js';
+
+const FORMAT_OPTIONS: FormatConfig = {
+  arrowParens: 'avoid',
+  bracketSpacing: true,
+  endOfLine: 'lf',
+  insertFinalNewline: true,
+  objectWrap: 'preserve',
+  printWidth: 120,
+  quoteProps: 'as-needed',
+  semi: true,
+  singleQuote: true,
+  sortImports: true,
+  sortPackageJson: true,
+  tabWidth: 2,
+  trailingComma: 'all',
+  useTabs: false,
+};
+
+interface MigrationProjectOptions {
+  readonly schemas?: readonly SnapshotableSchema[];
+  readonly driver?: MigrationDriver;
+  readonly introspector?: Introspector;
+}
+
+export function migrationProject(config: ResolvedConfig, options: MigrationProjectOptions = {}): MigrationProject {
+  return {
+    configPath: config.configPath,
+    outDir: config.outDir,
+    dialect: config.dialect,
+    schemas: options.schemas ?? [],
+    emitDeclarations,
+    formatSource,
+    ...(config.migrations === undefined ? {} : { migrations: config.migrations }),
+    ...(config.introspect === undefined ? {} : { introspect: config.introspect }),
+    ...(options.driver === undefined ? {} : { driver: options.driver }),
+    ...(options.introspector === undefined ? {} : { introspector: options.introspector }),
+  };
+}
+
+async function formatSource(path: string, source: string): Promise<string> {
+  const { format } = await import('oxfmt');
+  const result = await format(path, source, FORMAT_OPTIONS);
+  if (result.errors.length > 0) {
+    throw new TypeError(`oxfmt could not format generated ${path}: ${JSON.stringify(result.errors)}`);
+  }
+  return result.code;
+}
+
+export function reflectedMigrationProject(config: ResolvedConfig, driver?: MigrationDriver): MigrationProject {
+  const schemas = schemasFromFiles(config.schemaFiles, {
+    project: config.project,
+    naming: config.resolvedNaming,
+  });
+  return migrationProject(config, {
+    schemas,
+    ...(driver === undefined ? {} : { driver }),
+    ...(driver === undefined ? {} : { introspector: configuredIntrospector(driver.dialect) }),
+  });
+}
+
+export async function configuredMigrationDriver(config: ResolvedConfig): Promise<MigrationDriver> {
+  if (config.driver === undefined) {
+    throw new CliInvocationError(`config ${config.configPath} needs a driver for this command`);
+  }
+  const driver = await config.driver();
+  if (driver.dialect === undefined) {
+    throw new CliInvocationError(`config ${config.configPath} driver needs an explicit database dialect object`);
+  }
+  if (dialectName(driver.dialect) !== dialectName(config.dialect)) {
+    throw new CliInvocationError(
+      `config ${config.configPath} declares ${dialectName(config.dialect)} but its driver declares ${dialectName(driver.dialect)}`,
+    );
+  }
+  return { ...driver, dialect: driver.dialect };
+}
+
+export function rethrowProjectError(error: unknown): never {
+  if (error instanceof Error && error.name === 'MigrationProjectError') {
+    throw new CliInvocationError(error.message);
+  }
+  throw error;
+}

package/src/output.ts

@@ -0,0 +1,77 @@
+export interface CliResult<T> {
+  readonly ok: boolean;
+  readonly command: string;
+  readonly config: string;
+  readonly result?: T;
+  readonly errors?: readonly { readonly message: string; readonly path?: string }[];
+}
+
+export interface OutputStreams {
+  readonly stdout: (text: string) => void;
+  readonly stderr: (text: string) => void;
+}
+
+/** The only place a non-interactive command decides which stream receives text. */
+export class CliOutput {
+  readonly #command: string;
+  readonly #config: string;
+  readonly #json: boolean;
+  readonly #streams: OutputStreams;
+
+  constructor(command: string, config: string, json: boolean, streams: OutputStreams) {
+    this.#command = command;
+    this.#config = config;
+    this.#json = json;
+    this.#streams = streams;
+  }
+
+  withConfig(config: string): CliOutput {
+    return new CliOutput(this.#command, config, this.#json, this.#streams);
+  }
+
+  help(text: string): number {
+    return this.result({ help: text }, text);
+  }
+
+  writeStdout(text: string): void {
+    this.#streams.stdout(text);
+  }
+
+  writeStderr(text: string): void {
+    this.#streams.stderr(text);
+  }
+
+  progress(text: string): void {
+    if (this.#json) this.writeStderr(text);
+    else this.writeStdout(text);
+  }
+
+  result<T>(value: T, human: string, exitCode = 0): number {
+    if (this.#json) {
+      const body: CliResult<T> = {
+        ok: exitCode === 0,
+        command: this.#command,
+        config: this.#config,
+        result: value,
+      };
+      this.writeStdout(`${JSON.stringify(body)}\n`);
+    } else {
+      this.writeStdout(human);
+    }
+    return exitCode;
+  }
+
+  failure(message: string, exitCode: 1 | 2, path?: string): number {
+    if (this.#json) {
+      const body: CliResult<never> = {
+        ok: false,
+        command: this.#command,
+        config: this.#config,
+        errors: [{ message, ...(path === undefined ? {} : { path }) }],
+      };
+      this.writeStdout(`${JSON.stringify(body)}\n`);
+    }
+    this.writeStderr(`zmdb ${this.#command}: ${message}\n`);
+    return exitCode;
+  }
+}

package/src/repl.ts

@@ -0,0 +1,328 @@
+import { existsSync } from 'node:fs';
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { start, type REPLServer } from 'node:repl';
+
+import type { Token } from '@zmdb/app/di';
+import { moduleDefOf, type ModuleClass } from '@zmdb/app/modules';
+import { createApp, type WebApplication } from '@zmdb/web/app';
+import { describeGraph, renderTree, type GraphDescription } from '@zmdb/web/devtools';
+import type { WebRequest, WebResponse } from '@zmdb/web/pipeline';
+
+export interface ReplGet {
+  <T>(token: Token<T>): T;
+  (description: string): unknown;
+}
+
+export interface ReplScope {
+  readonly app: WebApplication;
+  readonly container: WebApplication['container'];
+  readonly get: ReplGet;
+  readonly tokens: readonly string[];
+  readonly describe: () => string;
+  readonly request: (request: WebRequest | string) => Promise<WebResponse>;
+  readonly load: (name: string) => Promise<void>;
+}
+
+export interface ReplSessionOptions {
+  readonly configPath: string;
+  readonly moduleSpec: string;
+  readonly cwd?: string;
+  readonly input?: NodeJS.ReadableStream;
+  readonly output?: NodeJS.WritableStream;
+  readonly stderr?: (text: string) => void;
+  readonly historyPath?: string | null;
+  readonly terminal?: boolean;
+}
+
+export interface ReplSession extends AsyncDisposable {
+  readonly app: WebApplication;
+  readonly graph: GraphDescription;
+  readonly scope: ReplScope;
+  readonly server: REPLServer;
+  readonly closed: Promise<void>;
+  evaluate(source: string): Promise<unknown>;
+}
+
+interface TokenRecord {
+  readonly token: Token<unknown>;
+  readonly description: string;
+}
+
+/**
+ * Boot the real application and start a local, stream-only Node REPL.
+ *
+ * No socket or adapter is created. The caller owns the returned async resource;
+ * disposing it closes the prompt and runs the application's normal shutdown
+ * lifecycle.
+ */
+export async function createReplSession(rootModule: ModuleClass, options: ReplSessionOptions): Promise<ReplSession> {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const stderr = options.stderr ?? (text => process.stderr.write(text));
+  const cwd = options.cwd ?? process.cwd();
+  const graph = describeGraph(rootModule);
+  const tokenRecords = providerTokensOf(rootModule);
+  const app = createApp(rootModule);
+
+  try {
+    await app.init();
+  } catch (error) {
+    try {
+      await app[Symbol.asyncDispose]();
+    } catch (cleanupError) {
+      throw new SuppressedError(cleanupError, error, 'REPL operation and application cleanup failed');
+    }
+    throw error;
+  }
+
+  let server: REPLServer | undefined;
+  try {
+    const scope = replScope(app, graph, tokenRecords);
+    stderr(
+      [
+        'zmdb repl — development shell with the application container',
+        `config: ${options.configPath}`,
+        'dialect: application-owned (the application does not read zmdb.config.ts)',
+        'database: application-owned (provider values are not inspected or printed)',
+        `module: ${options.moduleSpec} (${rootModule.name || '<anonymous>'})`,
+        'scope: app, container, get(tokenOrDescription), tokens, describe(), request(req), load(name)',
+        `tokens: ${scope.tokens.length === 0 ? '(none)' : scope.tokens.join(', ')}`,
+        `history: ${options.historyPath === null ? 'disabled' : (options.historyPath ?? 'disabled')}`,
+        '',
+      ].join('\n'),
+    );
+
+    server = start({
+      prompt: 'zmdb> ',
+      input,
+      output,
+      terminal: options.terminal,
+      ignoreUndefined: true,
+    });
+    const activeServer = server;
+    let closed = false;
+    const enteredLines: string[] = [];
+    if (options.historyPath !== null && options.historyPath !== undefined) {
+      activeServer.on('line', line => {
+        if (line.length > 0 && line !== '.exit') {
+          enteredLines.unshift(line);
+        }
+      });
+    }
+    const historyReady = Promise.withResolvers<() => Promise<void>>();
+    const whenClosed = new Promise<void>((resolveClosed, rejectClosed) => {
+      activeServer.once('exit', () => {
+        closed = true;
+        void historyReady.promise.then(flush => flush()).then(resolveClosed, rejectClosed);
+      });
+    });
+    Object.assign(activeServer.context, scope);
+
+    try {
+      const flushHistory =
+        options.historyPath === null || options.historyPath === undefined
+          ? async (): Promise<void> => {}
+          : await configureHistory(activeServer, options.historyPath, cwd, enteredLines);
+      historyReady.resolve(flushHistory);
+    } catch (error) {
+      historyReady.resolve(async (): Promise<void> => {});
+      throw error;
+    }
+
+    let disposed = false;
+    return {
+      app,
+      graph,
+      scope,
+      server: activeServer,
+      closed: whenClosed,
+      evaluate: source => evaluate(activeServer, source),
+      [Symbol.asyncDispose]: async () => {
+        if (disposed) {
+          return;
+        }
+        disposed = true;
+        if (!closed) {
+          activeServer.close();
+        }
+        let outcome: { readonly ok: true } | { readonly ok: false; readonly error: unknown };
+        try {
+          await whenClosed;
+          outcome = { ok: true };
+        } catch (error) {
+          outcome = { ok: false, error };
+        }
+        try {
+          await app[Symbol.asyncDispose]();
+        } catch (cleanupError) {
+          if (!outcome.ok)
+            throw new SuppressedError(cleanupError, outcome.error, 'REPL close and application cleanup failed');
+          throw cleanupError;
+        }
+        if (!outcome.ok) throw outcome.error;
+      },
+    };
+  } catch (error) {
+    server?.close();
+    try {
+      await app[Symbol.asyncDispose]();
+    } catch (cleanupError) {
+      throw new SuppressedError(cleanupError, error, 'REPL operation and application cleanup failed');
+    }
+    throw error;
+  }
+}
+
+/** Resolve the default history path without ever making it relative to the project. */
+export function replHistoryPath(
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+  homeDirectory: string = homedir(),
+): string {
+  const configured = environment['ZMDB_REPL_HISTORY'];
+  if (configured === undefined || configured.length === 0) {
+    return resolve(homeDirectory, '.zmdb_repl_history');
+  }
+  return isAbsolute(configured) ? configured : resolve(homeDirectory, configured);
+}
+
+function replScope(app: WebApplication, graph: GraphDescription, records: readonly TokenRecord[]): ReplScope {
+  const get = createGet(app, records);
+  const tokens = graph.providers.map(provider => provider.token).toSorted();
+  return {
+    app,
+    container: app.container,
+    get,
+    tokens,
+    describe: () => renderTree(graph, graph.providers.length <= 50 ? { providers: true } : undefined),
+    request: request => {
+      const input: WebRequest = typeof request === 'string' ? { method: 'GET', path: request, headers: {} } : request;
+      return app.handle(input);
+    },
+    load: async name => {
+      const matches = app.lazy.filter(handle => handle.name === name);
+      if (matches.length === 0) {
+        throw new Error(`zmdb repl: no lazy module named "${name}"`);
+      }
+      if (matches.length > 1) {
+        throw new Error(`zmdb repl: lazy module name "${name}" is ambiguous (${String(matches.length)} handles)`);
+      }
+      await matches[0]?.load();
+    },
+  };
+}
+
+function createGet(app: WebApplication, records: readonly TokenRecord[]): ReplGet {
+  return <T>(tokenOrDescription: Token<T> | string): T | unknown => {
+    if (typeof tokenOrDescription !== 'string') {
+      return app.container.resolve(tokenOrDescription);
+    }
+    const matches = records.filter(record => record.description === tokenOrDescription);
+    if (matches.length === 0) {
+      throw new Error(`zmdb repl: no provider token is described as "${tokenOrDescription}"`);
+    }
+    if (matches.length > 1) {
+      throw new Error(
+        `zmdb repl: token description "${tokenOrDescription}" is ambiguous (${String(matches.length)} distinct tokens)`,
+      );
+    }
+    const record = matches[0];
+    if (record === undefined) {
+      throw new Error(`zmdb repl: no provider token is described as "${tokenOrDescription}"`);
+    }
+    return app.container.resolve(record.token);
+  };
+}
+
+function providerTokensOf(rootModule: ModuleClass): readonly TokenRecord[] {
+  const seenModules = new Set<ModuleClass>();
+  const seenTokens = new Set<Token<unknown>>();
+  const records: TokenRecord[] = [];
+
+  const visit = (moduleClass: ModuleClass): void => {
+    if (seenModules.has(moduleClass)) {
+      return;
+    }
+    seenModules.add(moduleClass);
+    const definition = moduleDefOf(moduleClass);
+    for (const provider of definition?.providers ?? []) {
+      if (!seenTokens.has(provider.token)) {
+        seenTokens.add(provider.token);
+        records.push({ token: provider.token, description: provider.token.description });
+      }
+    }
+    for (const imported of definition?.imports ?? []) {
+      visit(typeof imported === 'function' ? imported : imported.module);
+    }
+  };
+
+  visit(rootModule);
+  return records;
+}
+
+async function configureHistory(
+  server: REPLServer,
+  historyPath: string,
+  cwd: string,
+  enteredLines: readonly string[],
+): Promise<() => Promise<void>> {
+  if (isWithin(projectRootOf(cwd), historyPath)) {
+    throw new Error(`zmdb repl: history path "${historyPath}" must be outside the project tree`);
+  }
+  await mkdir(dirname(historyPath), { recursive: true, mode: 0o700 });
+  let existing = '';
+  try {
+    existing = await readFile(historyPath, 'utf8');
+  } catch (error) {
+    if (!isNotFound(error)) {
+      throw error;
+    }
+  }
+  await writeFile(historyPath, existing, { encoding: 'utf8', mode: 0o600 });
+  await chmod(historyPath, 0o600);
+  const existingLines = existing.split(/\r?\n/).filter(line => line.length > 0);
+  Reflect.set(server, 'history', existingLines);
+
+  return async () => {
+    const lines = [...enteredLines, ...existingLines];
+    await writeFile(historyPath, lines.join('\n'), { encoding: 'utf8', mode: 0o600 });
+    await chmod(historyPath, 0o600);
+  };
+}
+
+function projectRootOf(cwd: string): string {
+  let current = resolve(cwd);
+  while (true) {
+    if (existsSync(resolve(current, 'package.json'))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return resolve(cwd);
+    }
+    current = parent;
+  }
+}
+
+function isWithin(base: string, target: string): boolean {
+  const path = relative(resolve(base), resolve(target));
+  return path === '' || (!path.startsWith(`..${sep}`) && path !== '..' && !isAbsolute(path));
+}
+
+function isNotFound(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+
+function evaluate(server: REPLServer, source: string): Promise<unknown> {
+  const command = source.endsWith('\n') ? source : `${source}\n`;
+  return new Promise<unknown>((resolveResult, rejectResult) => {
+    server.eval(command, server.context, 'zmdb-repl', (error, result) => {
+      if (error === null) {
+        resolveResult(result);
+      } else {
+        rejectResult(error);
+      }
+    });
+  });
+}