@znight/cli 0.0.0-stage → 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,679 @@
+import { ArgsDef, ParsedArgs } from "citty";
+import picocolors from "picocolors";
+import { InlineConfig, Plugin } from "vite";
+/** Location of a diagnostic (`Diagnostic.location`, §6.2). */
+interface DiagnosticLocation {
+  readonly file: string;
+  readonly line: number;
+  readonly column: number;
+}
+/** A compiler diagnostic (§6.2). */
+interface Diagnostic {
+  readonly code: string;
+  readonly severity: "error" | "warning";
+  readonly message: string;
+  readonly location?: DiagnosticLocation | undefined;
+  readonly hints?: readonly string[] | undefined;
+  readonly related?: readonly {
+    readonly message: string;
+    readonly location: DiagnosticLocation;
+  }[] | undefined;
+}
+/** A string alias of Vite's `resolve.alias` (`CompileOptions.aliases` of the compiler). */
+interface StringAliasLike {
+  readonly find: string;
+  readonly replacement: string;
+}
+/**
+ * Compiler options (`ZnightOptions`, §6.2, plus the `CompileOptions` the Vite plugin derives from the
+ * Vite config). The CLI reads `root`, `include` and `outFile`; the others are passed through.
+ */
+interface ZnightOptions {
+  readonly root?: string | undefined;
+  readonly include?: readonly string[] | undefined;
+  readonly outFile?: string | undefined;
+  /** String aliases of the Vite config (`resolve.alias`). */
+  readonly aliases?: readonly StringAliasLike[] | undefined;
+  readonly [option: string]: unknown;
+}
+/** What the CLI reads from a compile result (`CompileResult`, §6.2). */
+interface CompileResultLike {
+  /** Content of the generated module (with errors: a module throwing them, or empty). */
+  readonly code: string;
+  /** Absolute path of the generated module. */
+  readonly outFile: string;
+  readonly diagnostics: readonly Diagnostic[];
+  readonly stats?: {
+    readonly files?: number;
+    readonly providers?: number;
+    readonly durationMs?: number;
+  } | undefined;
+  /** Files the result depends on (`createCompiler()` results). */
+  readonly watchFiles?: readonly string[] | undefined;
+}
+/** Result of {@link CompilerApi.generate}. */
+interface GenerateResultLike extends CompileResultLike {
+  /** Whether the generated module was written (its content changed). */
+  readonly written: boolean;
+}
+/** Result of {@link CompilerApi.check}. */
+interface CheckResultLike extends CompileResultLike {
+  /** The generated files on disk are missing or differ from what would be generated. */
+  readonly stale: boolean;
+  /**
+   * The generated files that are missing or out of date (the module, and `znight.providers.json` in
+   * library mode). Empty when `stale` is `false`; empty or absent with `stale` when the compiler
+   * does not say which file is stale.
+   */
+  readonly staleFiles?: readonly string[] | undefined;
+}
+/** Files changed since the previous compile of an {@link IncrementalCompiler}. */
+interface CompilerChanges {
+  readonly changed?: readonly string[];
+  readonly added?: readonly string[];
+  readonly removed?: readonly string[];
+}
+/** Kind of a file system event (`ChangeKind` of the compiler). */
+type ChangeKind = "changed" | "added" | "removed";
+/** A compiler keeping its parse cache between compiles (`createCompiler()`), for watch mode. */
+interface IncrementalCompiler {
+  /** Compiles (only `changes` are re-read, everything without) and writes the module when it changed. */
+  generate(changes?: CompilerChanges): Promise<GenerateResultLike>;
+  /** Whether `file` is the generated module (watchers ignore it). */
+  isOutFile(file: string): boolean;
+  /**
+   * Directories where a created or deleted source changes the scan (`includeRoots()` of the
+   * compiler: the bases of the `include` globs in the project and in every source library, known once
+   * compiled), to watch recursively. The project root when the compiler does not tell.
+   */
+  includeRoots(): readonly string[];
+  /**
+   * Whether a file event can change the next compile (`isRelevantChange()` of the compiler): `watched`
+   * are the `watchFiles` of the last compile, `roots` its {@link includeRoots}. When the compiler does
+   * not tell, every event but the generated module is.
+   */
+  isRelevantChange(kind: ChangeKind, file: string, watched: ReadonlySet<string>, roots: readonly string[]): boolean;
+}
+/** Options of {@link CompilerApi.formatDiagnostics}. */
+interface FormatDiagnosticsOptions {
+  readonly color?: boolean;
+  readonly cwd?: string;
+  /** Append the summary line (`Build failed with 2 errors`). */
+  readonly summary?: boolean;
+}
+/** Options read from `znight.config.*` (`loadZnightConfig()`, §6.3). */
+interface ZnightConfigLike {
+  /** The config file, `undefined` when the project has none. */
+  readonly file: string | undefined;
+  /** Its options, `root` resolved against the config file directory. */
+  readonly options: ZnightOptions;
+}
+/** The part of `@znight/compiler` used by the CLI. */
+interface CompilerApi {
+  /** Compiles and writes the generated module when its content changed (`generate()`). */
+  generate(options: ZnightOptions): Promise<GenerateResultLike>;
+  /** Compiles without writing and compares with the files on disk (`generate({ check: true })`). */
+  check(options: ZnightOptions): Promise<CheckResultLike>;
+  /** An incremental compiler (`createCompiler()`). */
+  createIncremental(options: ZnightOptions): IncrementalCompiler;
+  /** Code frames for diagnostics (`formatDiagnostics()`). */
+  formatDiagnostics(diagnostics: readonly Diagnostic[], options?: FormatDiagnosticsOptions): string;
+  /**
+   * The options of `znight.config.*` (or of the file named by `ZNIGHT_CONFIG`) in `root`
+   * (`loadZnightConfig()`). Absent for compilers without it.
+   */
+  loadConfig?(root: string): Promise<ZnightConfigLike>;
+}
+/** A compile result as returned by any `@znight/compiler` version (extra fields are optional). */
+interface ModuleResult extends CompileResultLike {
+  /** The disk copy of the module (`code` before it existed; they differ in `build` mode only). */
+  readonly diskCode?: string;
+  readonly written?: readonly string[];
+  readonly stale?: boolean;
+  /** The stale generated files (check mode), when the compiler tells. */
+  readonly staleFiles?: readonly string[];
+  /** Library mode: `znight.providers.json` (`library` of a `CompileResult`). */
+  readonly library?: {
+    readonly file?: unknown;
+    readonly content?: unknown;
+  } | undefined;
+}
+/** The parts of a `ZnightCompiler` (`createCompiler()`) the CLI uses; all optional. */
+interface ModuleIncrementalCompiler {
+  generate?: (changes?: CompilerChanges, options?: {
+    check?: boolean;
+  }) => Promise<ModuleResult>;
+  isOutFile?: (file: string) => boolean;
+}
+/** The shape of the `@znight/compiler` module (every export optional: partial versions are adapted). */
+interface CompilerModule {
+  compile?: (options?: ZnightOptions) => Promise<ModuleResult>;
+  generate?: (options?: ZnightOptions & {
+    check?: boolean;
+  }) => Promise<ModuleResult>;
+  createCompiler?: (options?: ZnightOptions) => ModuleIncrementalCompiler;
+  formatDiagnostics?: (diagnostics: readonly Diagnostic[], options?: FormatDiagnosticsOptions) => string;
+  loadZnightConfig?: (cwd?: string) => Promise<ZnightConfigLike>;
+  /** The watch roots of a compiler (`includeRoots(compiler)`). */
+  includeRoots?: (compiler: ModuleIncrementalCompiler) => readonly string[];
+  /** Whether a file event can change the next compile of a compiler (`isRelevantChange(compiler, ...)`). */
+  isRelevantChange?: (compiler: ModuleIncrementalCompiler, kind: ChangeKind, file: string, watched: ReadonlySet<string>, roots: readonly string[]) => boolean;
+}
+/**
+ * Loads `@znight/compiler` as installed in the project (falls back to the CLI's own peer) and adapts
+ * it to {@link CompilerApi}.
+ */
+export declare function loadCompiler(root: string): Promise<CompilerApi>;
+/**
+ * Adapts a loaded compiler module: `generate()` / `generate({ check })` / `createCompiler()` when
+ * available, otherwise the same behaviour built on `compile()`.
+ */
+export declare function adaptCompilerModule(module: CompilerModule): CompilerApi;
+/** Options of `emitOpenApi()` (`@znight/openapi/emit`). */
+interface OpenApiEmitOptionsLike {
+  readonly root: string;
+  readonly output: readonly string[];
+  readonly check?: boolean;
+  readonly prefix?: string;
+  readonly runtime?: "auto" | "node" | "bun";
+  readonly converters?: string;
+  readonly config?: string;
+  readonly configLoader?: string;
+  readonly compilerOptions?: ZnightOptions;
+}
+/** A warning of the assembly. */
+interface OpenApiWarningLike {
+  readonly code: string;
+  readonly message: string;
+}
+/** What the CLI reads from the result of `emitOpenApi()`. */
+interface OpenApiEmitResultLike {
+  readonly ok: boolean;
+  readonly written: readonly string[];
+  readonly stale: boolean;
+  readonly staleFiles: readonly string[];
+  readonly diagnostics: readonly Diagnostic[];
+  readonly warnings: readonly OpenApiWarningLike[];
+  readonly outputs: readonly string[];
+  readonly runtime: "node" | "bun";
+  readonly document?: {
+    readonly paths?: Readonly<Record<string, object>>;
+  } | undefined;
+}
+/** `@znight/openapi/emit`. */
+interface OpenApiEmitApi {
+  emitOpenApi(options: OpenApiEmitOptionsLike): Promise<OpenApiEmitResultLike>;
+}
+/** Options of the `openapi()` Vite plugin. */
+interface OpenApiVitePluginOptionsLike {
+  readonly output?: string;
+  /** HTTP prefix (`servers` default when `@OpenApiDocument` declares none). */
+  readonly prefix?: string;
+}
+/** `@znight/openapi/vite`. */
+interface OpenApiViteApi {
+  openapi(options?: OpenApiVitePluginOptionsLike): Plugin;
+}
+/** How a child process ended. */
+interface ExitStatus {
+  /** Exit code, `null` when killed by a signal or when the process could not start. */
+  readonly code: number | null;
+  readonly signal: NodeJS.Signals | null;
+  /** Spawn failure (`ENOENT`...). */
+  readonly error?: Error | undefined;
+}
+/** A running child process. */
+interface ChildHandle {
+  readonly pid: number | undefined;
+  /** Sends a signal (to its process group when it runs detached). Returns `false` when it already exited. */
+  kill(signal: NodeJS.Signals): boolean;
+  /** Resolves once the process exited (never rejects). */
+  readonly exited: Promise<ExitStatus>;
+}
+/** Options of {@link ProcessService.spawn}. */
+interface SpawnOptions {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** Default `'inherit'`. */
+  readonly stdio?: "inherit" | "ignore";
+  /**
+   * POSIX only: run the process in its own process group, so that a terminal Ctrl+C reaches the CLI
+   * only (the CLI then forwards exactly one signal). The process is killed when the CLI exits.
+   */
+  readonly detached?: boolean;
+}
+/** Result of {@link ProcessService.run}. */
+interface RunResult extends ExitStatus {
+  readonly stdout: string;
+  readonly stderr: string;
+}
+/** Options of {@link ProcessService.run}. */
+interface RunOptions {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Replaces the current process image (`execve(2)`) after changing the working directory to `cwd`.
+ * `args[0]` is the program name. Never returns on success.
+ */
+type ExecveFunction = (file: string, args: readonly string[], env: Readonly<Record<string, string>>, cwd: string) => void;
+/** Process primitives used by the commands. */
+interface ProcessService {
+  spawn(command: string, args: readonly string[], options: SpawnOptions): ChildHandle;
+  /** Runs a command to completion, capturing its output. */
+  run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
+  /** `process.execve` when the runtime supports it (POSIX). */
+  readonly execve?: ExecveFunction | undefined;
+}
+/** A choice of a select / multiselect prompt. */
+interface PromptChoice<T extends string> {
+  readonly value: T;
+  readonly label: string;
+  readonly hint?: string;
+}
+/** Prompts used by the CLI. */
+interface Prompts {
+  intro(title: string): void;
+  outro(message: string): void;
+  text(options: {
+    message: string;
+    placeholder?: string;
+    initialValue?: string;
+    validate?: (value: string) => string | undefined;
+  }): Promise<string>;
+  select<T extends string>(options: {
+    message: string;
+    choices: readonly PromptChoice<T>[];
+    initialValue?: T;
+  }): Promise<T>;
+  multiselect<T extends string>(options: {
+    message: string;
+    choices: readonly PromptChoice<T>[];
+    initialValues?: readonly T[];
+  }): Promise<T[]>;
+  confirm(options: {
+    message: string;
+    initialValue?: boolean;
+  }): Promise<boolean>;
+  /** A spinner; `stop` prints the final message. */
+  spinner(): {
+    start(message: string): void;
+    stop(message: string, failed?: boolean): void;
+  };
+  note(message: string, title?: string): void;
+}
+/** What the CLI reads from a config resolved by Vite (`ResolvedConfig`). */
+interface ResolvedConfigLike {
+  /** Absolute root. */
+  readonly root: string;
+  /** The config file that was loaded. */
+  readonly configFile?: string | undefined;
+  /** Every plugin, flattened. */
+  readonly plugins: readonly unknown[];
+  readonly resolve?: {
+    readonly alias?: unknown;
+  } | undefined;
+}
+/** Subset of the `vite` module used by the CLI. */
+interface ViteApi {
+  build(config: InlineConfig): Promise<unknown>;
+  /** Resolves the config as a build would, without building (absent: `znight generate` uses defaults). */
+  resolveConfig?: (config: InlineConfig, command: "build" | "serve", defaultMode?: string, defaultNodeEnv?: string) => Promise<ResolvedConfigLike>;
+}
+/** A directory to watch. */
+interface WatchTarget {
+  readonly path: string;
+  readonly recursive: boolean;
+}
+/** A running watcher. */
+interface FileWatcher {
+  close(): void;
+}
+/**
+ * Starts watching `targets`; `onChange` receives the absolute path of every changed file or
+ * directory (created, modified, deleted or renamed), except in ignored directories
+ * ({@link isIgnoredPath}).
+ */
+type WatchFactory = (targets: readonly WatchTarget[], onChange: (file: string) => void) => FileWatcher;
+/** picocolors formatters (`colors.red('x')`...). */
+type Colors = ReturnType<typeof picocolors.createColors>;
+/** A writable text stream (`process.stdout`, or a test double). */
+interface OutputStream {
+  write(chunk: string): unknown;
+  readonly isTTY?: boolean | undefined;
+  readonly columns?: number | undefined;
+}
+/** Writes consistent status lines. Errors and warnings go to stderr, everything else to stdout. */
+interface Reporter {
+  readonly colors: Colors;
+  /** A raw line on stdout. */
+  log(message?: string): void;
+  /** `› message` */
+  info(message: string): void;
+  /** `✓ message` */
+  success(message: string): void;
+  /** `! message` (stderr) */
+  warn(message: string, hints?: readonly string[]): void;
+  /** `✗ message` (stderr) */
+  error(message: string, hints?: readonly string[]): void;
+  /** A raw line on stderr. */
+  logError(message?: string): void;
+}
+/** Runtime of the application process. */
+type RuntimeName = "node" | "bun";
+/** `--runtime` values: `auto` picks Bun when the CLI itself runs on Bun, Node.js otherwise. */
+type RuntimeOption = RuntimeName | "auto";
+/** The runtime executing the CLI. */
+interface HostRuntime {
+  readonly name: RuntimeName;
+  /** Absolute path of the running executable (`process.execPath`). */
+  readonly execPath: string;
+  readonly platform: NodeJS.Platform;
+}
+/** A source of process signals (`process` by default). */
+interface SignalSource {
+  on(signal: NodeJS.Signals, listener: () => void): void;
+  off(signal: NodeJS.Signals, listener: () => void): void;
+}
+/** External services, lazily loaded. */
+interface CliServices {
+  /** Loads `@znight/compiler` for the project at `root`. */
+  loadCompiler(root: string): Promise<CompilerApi>;
+  /** Loads `vite` for the project at `root`. */
+  loadVite(root: string): Promise<ViteApi>;
+  /** Loads the interactive prompts. */
+  loadPrompts(): Promise<Prompts>;
+  /** Loads `@znight/openapi/emit` for the project at `root` (`znight openapi`). */
+  loadOpenApi(root: string): Promise<OpenApiEmitApi>;
+  /** Loads `@znight/openapi/vite` for the project at `root` (`znight build --openapi`). */
+  loadOpenApiVite(root: string): Promise<OpenApiViteApi>;
+  readonly processes: ProcessService;
+  readonly watch: WatchFactory;
+}
+/** The execution context of a command. */
+interface CliContext {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly stdout: OutputStream;
+  readonly stderr: OutputStream;
+  /** Whether prompts may be shown (stdin and stdout are TTYs, not in CI). */
+  readonly interactive: boolean;
+  readonly colors: Colors;
+  readonly reporter: Reporter;
+  readonly runtime: HostRuntime;
+  /** Version of `@znight/cli`. */
+  readonly version: string;
+  readonly signals: SignalSource;
+  readonly services: CliServices;
+  /** Print stack traces of unexpected errors. */
+  readonly debug: boolean;
+}
+/** Overrides accepted by {@link createContext}. */
+interface CliContextOptions {
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly stdout?: OutputStream;
+  readonly stderr?: OutputStream;
+  readonly interactive?: boolean;
+  /** `--color` / `--no-color`. */
+  readonly color?: boolean | undefined;
+  readonly runtime?: HostRuntime;
+  readonly version?: string;
+  readonly signals?: SignalSource;
+  readonly services?: Partial<CliServices>;
+  readonly debug?: boolean;
+}
+/**
+ * Creates a context from the current process, with optional overrides. The environment is a copy
+ * of `process.env` taken now: tools running in the CLI process (Vite sets `NODE_ENV`) do not change
+ * what the commands see and pass to the application.
+ */
+export declare function createContext(options?: CliContextOptions): CliContext;
+/** What a command receives. */
+interface CommandRunContext<A extends ArgsDef = ArgsDef> {
+  readonly args: ParsedArgs<A>;
+  readonly cli: CliContext;
+  /** Arguments of the command as typed (before `--`). */
+  readonly rawArgs: readonly string[];
+  /** Arguments after `--` (forwarded to the application by `dev` and `start`). */
+  readonly passthrough: readonly string[];
+}
+/** Description of a command. */
+interface CommandMeta {
+  readonly name: string;
+  readonly description: string;
+  readonly aliases?: readonly string[];
+  /** Usage line after `znight <name>` (default: computed from the arguments). */
+  readonly usage?: string;
+  readonly examples?: readonly string[];
+  /** Extra help paragraph printed after the options. */
+  readonly details?: string | ((colors: Colors) => string);
+}
+/** Definition of a command: typed arguments and the implementation. */
+interface CommandDefinition<A extends ArgsDef> {
+  readonly meta: CommandMeta;
+  readonly args: A;
+  /** Runs the command; the returned number is the exit code (default 0). */
+  run(context: CommandRunContext<A>): number | undefined | Promise<number | undefined>;
+}
+/** A CLI command, ready to execute. */
+interface Command {
+  readonly meta: CommandMeta;
+  readonly args: ArgsDef;
+  /**
+   * Parses `argv` (the arguments after the command name, without `--` pass-through arguments) and
+   * runs the command. Resolves with the exit code.
+   */
+  execute(argv: readonly string[], passthrough: readonly string[], cli: CliContext): Promise<number>;
+}
+/** Creates a {@link Command}; `args` keep their literal types in `run`. */
+export declare function defineCommand<const A extends ArgsDef>(definition: CommandDefinition<A>): Command;
+/** Notifications of an {@link AppSupervisor}. */
+interface SupervisorEvents {
+  /** A process was started (`restart` is false for the first one). */
+  onStart?(child: ChildHandle, restart: boolean): void;
+  /** A process stopped by the supervisor exited (`forced`: it needed SIGKILL). */
+  onStop?(status: ExitStatus, forced: boolean): void;
+  /** The current process exited by itself (crash, or the application ended). */
+  onExit?(status: ExitStatus): void;
+  /** Starting a process failed synchronously. */
+  onError?(error: unknown): void;
+}
+/** Options of {@link AppSupervisor}. */
+interface AppSupervisorOptions {
+  /** Starts a new application process. */
+  readonly spawn: () => ChildHandle;
+  /** Delay applied by {@link AppSupervisor.scheduleRestart}. Default 100 ms. */
+  readonly debounceMs?: number;
+  /** Time a process gets to exit after SIGTERM before SIGKILL. Default 5000 ms. */
+  readonly killTimeoutMs?: number;
+  readonly events?: SupervisorEvents;
+}
+/** Keeps one application process running and restarts it on demand. */
+export declare class AppSupervisor {
+  #private;
+  constructor(options: AppSupervisorOptions);
+  /** Whether an application process is running. */
+  get running(): boolean;
+  /** The running process. */
+  get current(): ChildHandle | undefined;
+  /** Number of processes started so far. */
+  get starts(): number;
+  /** Restarts after `debounceMs`; calls in between postpone it. */
+  scheduleRestart(): void;
+  /**
+   * Cancels a restart scheduled by {@link scheduleRestart} and not started yet (the output it would
+   * run turned out to be broken, e.g. a failed compilation). Returns whether one was pending.
+   */
+  cancelRestart(): boolean;
+  /**
+   * Stops the current process (if any) and starts a new one. Restarts never overlap; a restart
+   * requested while another one is waiting to run is merged with it.
+   */
+  restart(): Promise<void>;
+  /** Stops the current process with `signal` (SIGKILL after the timeout) and refuses new starts. */
+  stop(signal?: NodeJS.Signals): Promise<void>;
+  /** Immediately SIGKILLs every process (a second Ctrl+C). */
+  kill(): void;
+}
+/** Choices of `znight new`. */
+/** Package managers supported by `znight new`. */
+type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
+/** HTTP adapters of `@znight/http`. */
+type HttpAdapterName = "node" | "fastify" | "express" | "hono";
+/** Optional features of a new project. */
+type Feature = "config" | "observability" | "messaging" | "schedule" | "openapi";
+/** Every package manager, in display order. */
+export declare const PACKAGE_MANAGERS: readonly PackageManager[];
+/** Every HTTP adapter, in display order. */
+export declare const HTTP_ADAPTERS: readonly HttpAdapterName[];
+/** Every feature, in display (and canonical) order. */
+export declare const FEATURES: readonly Feature[];
+/** Features selected when none are given. */
+export declare const DEFAULT_FEATURES: readonly Feature[];
+/** Everything that determines the files of a new project. */
+interface ProjectOptions {
+  /** npm package name. */
+  readonly name: string;
+  readonly packageManager: PackageManager;
+  readonly adapter: HttpAdapterName;
+  /** Selected features, in canonical order. */
+  readonly features: readonly Feature[];
+  /** Version range base of the `@znight/*` packages (the CLI version). */
+  readonly znightVersion: string;
+}
+/** A file of the new project. */
+interface ProjectFile {
+  /** POSIX path relative to the project directory. */
+  readonly path: string;
+  readonly content: string;
+}
+/** Every file of a new project, sorted by path. */
+export declare function renderProject(options: ProjectOptions): ProjectFile[];
+/** Available schematics. */
+type SchematicName = "service" | "controller" | "consumer" | "config" | "guard" | "interceptor" | "factory" | "job";
+/** Names derived from the user input. */
+interface SchematicNames {
+  /** `user-profile` */
+  readonly kebab: string;
+  /** `UserProfile` */
+  readonly pascal: string;
+  /** `userProfile` */
+  readonly camel: string;
+  /** `UserProfileService` */
+  readonly className: string;
+  /**
+   * Dotted name of the element in the application: the directories of its file relative to `src/`
+   * (or to the project root, for a `--path` outside `src/`) and its kebab name, without the directory
+   * named after it (`reports.digest` for `src/reports/digest.jobs.ts`, `digest` for
+   * `src/digest/digest.jobs.ts`). Unlike `kebab`, it tells apart elements of the same name in different
+   * directories: the default name of a job (job names are unique in the application).
+   */
+  readonly qualified: string;
+}
+/** Project facts that change the generated code. */
+interface SchematicContext {
+  /** The project depends on `zod`: consumers get a message schema. */
+  readonly zod: boolean;
+  /** `interceptor` only: a method interceptor (`@Intercept`, AOP) instead of an HTTP interceptor. */
+  readonly aop: boolean;
+}
+/** A schematic. */
+interface Schematic {
+  readonly name: SchematicName;
+  readonly aliases: readonly string[];
+  readonly description: string;
+  /** File and class suffix (`service` → `user.service.ts`, `UserService`). */
+  readonly suffix: string;
+  render(names: SchematicNames, context: SchematicContext): string;
+  /** What to do next, printed after the file is created. */
+  hint?(names: SchematicNames, context: SchematicContext): string | undefined;
+}
+/** Every schematic, in display order. */
+export declare const SCHEMATICS: readonly Schematic[];
+/** Finds a schematic by name or alias. */
+export declare function findSchematic(name: string): Schematic | undefined;
+/** Where and what to generate. */
+interface SchematicPlan {
+  readonly schematic: Schematic;
+  readonly names: SchematicNames;
+  /** Absolute path of the file. */
+  readonly file: string;
+  readonly content: string;
+  readonly hint: string | undefined;
+}
+/** Inputs of {@link planSchematic}. */
+interface PlanSchematicOptions {
+  readonly schematic: Schematic;
+  readonly name: string;
+  /** Project root (contains `src/`). */
+  readonly root: string;
+  /** Directory of `--path` (absolute), replacing `<root>/src`. */
+  readonly path?: string | undefined;
+  /** Do not create a directory named after the element. */
+  readonly flat?: boolean;
+  readonly context: SchematicContext;
+}
+/**
+ * Computes the file of a schematic:
+ *
+ * | Input                        | File                                  |
+ * | ---------------------------- | ------------------------------------- |
+ * | `service user`               | `src/user/user.service.ts`            |
+ * | `service users/user`         | `src/users/user.service.ts`           |
+ * | `service user --flat`        | `src/user.service.ts`                 |
+ * | `service user --path lib/x`  | `lib/x/user.service.ts`               |
+ */
+export declare function planSchematic(options: PlanSchematicOptions): SchematicPlan;
+/**
+ * Errors thrown by commands. The dispatcher turns them into a message on stderr and an exit code;
+ * any other error is reported as an unexpected failure (exit code 1, stack trace with `--debug`).
+ */
+/** Exit codes of the `znight` binary. */
+export declare const ExitCode: {
+  /** The command succeeded. */
+  readonly Ok: 0;
+  /** The command failed (compilation errors, failed build, stale generated file...). */
+  readonly Failure: 1;
+  /** Invalid usage: unknown command or option, missing or invalid argument. */
+  readonly Usage: 2;
+  /** The user cancelled an interactive prompt or interrupted the command. */
+  readonly Cancelled: 130;
+};
+/** Options of a {@link CliError}. */
+interface CliErrorOptions {
+  /** Exit code of the process. Default {@link ExitCode.Failure}. */
+  readonly exitCode?: number;
+  /** Lines printed after the message (`= hint: ...`). */
+  readonly hints?: readonly string[];
+  /** Original error. */
+  readonly cause?: unknown;
+}
+/** An expected failure: printed without stack trace. */
+export declare class CliError extends Error {
+  readonly exitCode: number;
+  readonly hints: readonly string[];
+  constructor(message: string, options?: CliErrorOptions);
+}
+/** Invalid command line usage (exit code 2). The usage of the command is printed after the message. */
+export declare class UsageError extends CliError {
+  constructor(message: string, hints?: readonly string[]);
+}
+/** The user cancelled a prompt (exit code 130). */
+export declare class CancelledError extends CliError {
+  constructor(message?: string);
+}
+/** Every command, in help order. */
+export declare const COMMANDS: readonly Command[];
+/**
+ * Runs the CLI with `argv` (without the executable and script, i.e. `process.argv.slice(2)`).
+ * Resolves with the exit code; never throws.
+ */
+export declare function main(argv: readonly string[], options?: CliContextOptions): Promise<number>;
+/**
+ * Version of `@znight/cli`, read from its `package.json` (one level above both `src/` and `dist/`).
+ * Projects created by `znight new` depend on `@znight/*` packages at `^<version>`.
+ */
+export declare function cliVersion(): string;
+export type { AppSupervisorOptions, CheckResultLike, ChildHandle, CliContext, CliContextOptions, CliServices, Command, CommandDefinition, CommandMeta, CommandRunContext, CompileResultLike, CompilerApi, CompilerChanges, CompilerModule, Diagnostic, DiagnosticLocation, ExecveFunction, ExitStatus, Feature, FileWatcher, FormatDiagnosticsOptions, GenerateResultLike, HostRuntime, HttpAdapterName, IncrementalCompiler, OpenApiEmitApi, OpenApiEmitOptionsLike, OpenApiEmitResultLike, OpenApiViteApi, OpenApiVitePluginOptionsLike, OpenApiWarningLike, OutputStream, PackageManager, PlanSchematicOptions, ProcessService, ProjectFile, ProjectOptions, PromptChoice, Prompts, Reporter, RunOptions, RunResult, RuntimeName, RuntimeOption, Schematic, SchematicContext, SchematicName, SchematicNames, SchematicPlan, SignalSource, SpawnOptions, SupervisorEvents, WatchFactory, WatchTarget, ZnightConfigLike, ZnightOptions };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1 @@
+export { d as AppSupervisor, t as COMMANDS, _ as CancelledError, v as CliError, s as DEFAULT_FEATURES, y as ExitCode, c as FEATURES, l as HTTP_ADAPTERS, u as PACKAGE_MANAGERS, r as SCHEMATICS, b as UsageError, m as adaptCompilerModule, p as cliVersion, f as createContext, g as defineCommand, i as findSchematic, h as loadCompiler, n as main, a as planSchematic, o as renderProject } from "./main-BWsiUsxN.mjs";