@arkstack/common 0.5.1 → 0.5.3

package/dist/index.d.ts

@@ -1,15 +1,24 @@
 /// <reference path="./app.d.ts" />
-import { DotPath } from "@h3ravel/support";
+import { a as abortIf, c as initializeGlobalContext, d as Hash, f as Encryption, i as abort, l as isClass, n as ModelConstructor, o as assertFound, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as perPage } from "./helpers-BrQ0B-EX.js";
+import { JitiOptions, JitiResolveOptions } from "jiti";
+import { Arkstack } from "@arkstack/contract";
 import pino from "pino";
 import { ChalkInstance } from "chalk";
-import { TOTP } from "otpauth";
-import { Model, ModelStatic } from "arkormx";
 
 //#region src/lifecycle.d.ts
-declare const bindGracefulShutdown: (shutdown: () => Promise<void> | void) => void;
+declare const bindGracefulShutdown: (shutdown: () => Promise<void> | void, defer?: boolean) => void;
 //#endregion
 //#region src/network.d.ts
-declare const bootWithDetectedPort: (boot: (port: number) => Promise<void>, preferredPort?: number, app?: any) => Promise<void>;
+/**
+ * Boots the app using an available port close to the requested port
+ *when requested port is not available
+ *
+ * @param boot
+ * @param preferredPort
+ * @param app
+ * @param defer
+ */
+declare const bootWithDetectedPort: <TApp, TRoutes = unknown, THandler = unknown>(boot: (port: number) => Promise<void>, preferredPort?: number, app?: Arkstack<TApp, TRoutes, THandler>, defer?: boolean) => Promise<void>;
 declare const renderError: ({
   message,
   stack,
@@ -34,51 +43,281 @@ declare class Console {
   static error: (...args: any[]) => void[];
 }
 declare class Logger {
+  /**
+   * Global verbosity configuration
+   */
   private static verbosity;
   private static isQuiet;
   private static isSilent;
+  /**
+   * Configure global verbosity levels
+   */
   static configure(options?: {
     verbosity?: number;
     quiet?: boolean;
     silent?: boolean;
   }): void;
+  /**
+   * Check if output should be suppressed
+   */
   private static shouldSuppressOutput;
+  /**
+   * Logs the message in two columns
+   *
+   * @param name
+   * @param value
+   * @param log If set to false, array of [name, dots, value] output will be returned and not logged
+   * @returns
+   */
   static twoColumnDetail(name: string, value: string, log?: true, spacer?: string): void;
   static twoColumnDetail(name: string, value: string, log?: false, spacer?: string): [string, string, string];
+  /**
+   * Logs the message in two columns
+   *
+   * @param name
+   * @param desc
+   * @param width
+   * @param log If set to false, array of [name, dots, value] output will be returned and not logged
+   * @returns
+   */
   static describe(name: string, desc: string, width?: number, log?: true): void;
   static describe(name: string, desc: string, width?: number, log?: false): [string, string, string];
+  /**
+   * Logs the message in two columns but allways passing status
+   *
+   * @param name
+   * @param value
+   * @param status
+   * @param exit
+   * @param preserveCol
+   */
   static split(name: string, value: string, status?: 'success' | 'info' | 'error', exit?: boolean, preserveCol?: boolean, spacer?: string): void;
+  /**
+   * Wraps text with chalk
+   *
+   * @param txt
+   * @param color
+   * @param preserveCol
+   * @returns
+   */
   static textFormat(txt: unknown | unknown[], color: (...text: unknown[]) => string, preserveCol?: boolean): string;
+  /**
+   * Logs a success message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
   static success(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs an informational message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
   static info(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs an error message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
   static error(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs a warning message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
   static warn(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs a debug message (only shown with verbosity >= 3)
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
   static debug<M = any>(msg: M | M[], exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Terminates the process
+   */
   static quiet(): void;
   static chalker(styles: LoggerChalk[]): (input: any) => string;
+  /**
+   * Parse an array formated message and logs it
+   *
+   * @param config
+   * @param joiner
+   * @param log If set to false, string output will be returned and not logged
+   * @param sc color to use ue on split text if : is found
+   */
   static parse(config: LoggerParseSignature, joiner?: string, log?: true, sc?: LoggerChalk): void;
   static parse(config: LoggerParseSignature, joiner?: string, log?: false, sc?: LoggerChalk): string;
+  /**
+   * Ouput formater object or format the output
+   *
+   * @returns
+   */
   static log: LoggerLog;
+  /**
+   * A simple console like output logger
+   *
+   * @returns
+   */
   static console(): typeof Console;
 }
 //#endregion
+//#region src/locales.d.ts
+declare const locales: readonly ["af_ZA", "ar", "az", "bn_BD", "cs_CZ", "cy", "da", "de", "de_AT", "de_CH", "dv", "el", "en", "en_AU", "en_AU_ocker", "en_BORK", "en_CA", "en_GB", "en_GH", "en_HK", "en_IE", "en_IN", "en_NG", "en_US", "en_ZA", "eo", "es", "es_MX", "fa", "fi", "fr", "fr_BE", "fr_CA", "fr_CH", "fr_LU", "fr_SN", "he", "hr", "hu", "hy", "id_ID", "it", "ja", "ka_GE", "ko", "ku_ckb", "ku_kmr_latin", "lv", "mk", "mn_MN_cyrl", "nb_NO", "ne", "nl", "nl_BE", "pl", "pt_BR", "pt_PT", "ro", "ro_MD", "ru", "sk", "sl_SI", "sr_RS_latin", "sv", "ta_IN", "th", "tr", "uk", "ur", "uz_UZ_latin", "vi", "yo_NG", "zh_CN", "zh_TW", "zu_ZA"];
+//#endregion
 //#region src/types.d.ts
+interface ConfigRegistry {}
+/**
+ * Map of known environment variables to their (coerced) value types.
+ *
+ * Used to give {@link GlobalEnv | env()} precise return types. Unknown keys fall
+ * back to `string`. Augment this interface (declaration merging) to register
+ * application-specific variables:
+ *
+ * ```ts
+ * declare module '@arkstack/common' {
+ *   interface EnvRegistry { MY_FLAG: boolean }
+ * }
+ * ```
+ */
+interface EnvRegistry {
+  APP_NAME: string;
+  APP_ENV: 'development' | 'production' | 'staging' | 'local';
+  APP_KEY: string;
+  APP_URL: string;
+  APP_HOST: string;
+  APP_PORT: number;
+  APP_DEBUG: boolean;
+  APP_TIMEZONE: string;
+  APP_LOCALE: typeof locales[number];
+  APP_FALLBACK_LOCALE: typeof locales[number];
+  APP_FAKER_LOCALE: typeof locales[number];
+  NODE_ENV: 'development' | 'production' | 'test';
+  PORT: number;
+  HOST: string;
+  FRONTEND_URL: string;
+  OUTPUT_DIR: string;
+  OUTPUT_DIR_DEV: string;
+  CONFIG_PATH: string;
+  TUNNEL: boolean;
+  NGROK_AUTHTOKEN: string;
+  NGROK_DOMAIN: string;
+  FILESYSTEM_DISK: string;
+  CACHE_STORE: string;
+  CACHE_PREFIX: string;
+  CACHE_TABLE: string;
+  QUEUE_CONNECTION: string;
+  QUEUE_TABLE: string;
+  QUEUE_NAME: string;
+  QUEUE_RETRY_AFTER: number;
+  REDIS_HOST: string;
+  REDIS_PORT: number;
+  REDIS_PASSWORD: string;
+  REDIS_CACHE_DB: number;
+  REDIS_QUEUE_DB: number;
+  JWT_EXPIRES_IN: string;
+  SESSION_LIFETIME: number;
+  TWO_FACTOR_SMS_TTL_MINUTES: number;
+  DATABASE_URL: string;
+  DB_CONNECTION: string;
+  DB_HOST: string;
+  DB_PORT: number;
+  DB_DATABASE: string;
+  DB_USERNAME: string;
+  DB_PASSWORD: string;
+  MAIL_HOST: string;
+  MAIL_PORT: number;
+  MAIL_SECURE: boolean;
+  MAIL_USERNAME: string;
+  MAIL_PASSWORD: string;
+  MAIL_FROM_ADDRESS: string;
+  MAIL_TEST_ADDRESS: string;
+  AWS_ACCESS_KEY_ID: string;
+  AWS_SECRET_ACCESS_KEY: string;
+  AWS_DEFAULT_REGION: string;
+  AWS_BUCKET: string;
+  AWS_URL: string;
+  AWS_ENDPOINT: string;
+}
+/**
+ * App Confifuration
+ */
+interface AppConfig {
+  [key: string]: any;
+  env: string;
+  key: string;
+  url: string;
+  host: string;
+  name: string;
+  frontend_url: string;
+  debug: boolean;
+  timezone: string;
+  locale: typeof locales[number];
+  fallback_locale: typeof locales[number];
+  faker_locale: typeof locales[number];
+}
+/**
+ * Known environment variable names.
+ */
+type EnvKey = keyof EnvRegistry & string;
+/** The registered type for a known key, or `string` for an unknown one. */
+type EnvLookup<K extends string> = [K] extends [EnvKey] ? EnvRegistry[K] : string;
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+type MergedConfig<X> = UnionToIntersection<X>;
+type Primitive = string | number | boolean | null | undefined | Function;
 type LoggerChalk = keyof ChalkInstance | ChalkInstance | (keyof ChalkInstance)[];
 type LoggerParseSignature = [string, LoggerChalk][];
 type DotPathValue<T, P extends string> = P extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? DotPathValue<T[Head], Tail> : never : P extends keyof T ? T[P] : never;
+type DotPath<T> = T extends Primitive ? never : T extends any[] ? never : { [K in keyof T & string]: T[K] extends Primitive ? `${K}` : T[K] extends any[] ? `${K}` : `${K}` | `${K}.${DotPath<T[K]>}` }[keyof T & string];
+/**
+ * Ouput formater object or format the output
+ *
+ * @param config
+ * @param joiner
+ * @param log If set to false, string output will be returned and not logged
+ * @param sc color to use ue on split text if : is found
+ *
+ * @returns
+ */
 interface LoggerLog {
   (): typeof Logger;
   <L extends boolean>(config: string, joiner: LoggerChalk, log?: L, sc?: LoggerChalk): L extends true ? void : string;
   <L extends boolean>(config: LoggerParseSignature, joiner?: string, log?: L, sc?: LoggerChalk): L extends true ? void : string;
   <L extends boolean>(config?: LoggerParseSignature, joiner?: string, log?: L, sc?: LoggerChalk): L extends true ? void : string | Logger;
 }
+/**
+ * Return type of {@link GlobalEnv | env()}.
+ *
+ * When an explicit value type `X` is given it wins (backward compatible with
+ * `env<boolean>('FLAG')`). Otherwise the type registered for the key `K` is used
+ * — falling back to `string` for unknown keys. A provided default `D` is unioned
+ * into the result.
+ */
+type EnvReturn<X, K extends string, D> = [X] extends [never] ? [D] extends [undefined] ? EnvLookup<K> : EnvLookup<K> | D : [D] extends [undefined] ? X : X | D;
 interface GlobalEnv {
-  <X = string, Y = undefined | X>(env: string, defaultValue?: Y): Y extends undefined ? X : Y;
+  <X = never, D = undefined, K extends (keyof EnvRegistry | (string & {})) = keyof EnvRegistry>(env: K, defaultValue?: D): EnvReturn<X, K, D>;
 }
+type ConfigShape = keyof ConfigRegistry extends never ? Record<string, any> : ConfigRegistry;
 interface GlobalConfig {
-  <X extends Record<string, any>>(): X;
-  <X extends Record<string, any>, P extends DotPath<X>>(key: P): DotPathValue<X, P>;
-  <X extends Record<string, any>, P extends DotPath<X>, D>(key: P, defaultValue: D): DotPathValue<X, P> | D;
+  <X extends ConfigShape>(): X;
+  <X extends ConfigShape, P extends DotPath<X>>(key: P): DotPathValue<X, P>;
+  <X extends ConfigShape, P extends DotPath<X>>(key: Record<P, Partial<DotPathValue<X, P>>>): void;
+  <X extends ConfigShape, P extends DotPath<X>, D>(key: P, defaultValue: D): DotPathValue<X, P> | D;
+}
+interface FileImporter {
+  <T = unknown>(filePath: string): Promise<T>;
+  <T = unknown>(filePath: string, userOptions?: JitiOptions | undefined): Promise<T>;
+  <T = unknown>(filePath: string, userOptions?: JitiOptions | undefined, resolveOptions?: (JitiResolveOptions & {
+    default?: true;
+  })): Promise<T>;
 }
 type ArkstackErrorShape = Error & {
   cause?: unknown;
@@ -86,7 +325,8 @@ type ArkstackErrorShape = Error & {
   errors?: unknown;
   getModelName?: () => string;
   status?: number;
-  statusCode?: number;
+  statusCode?: number; /** Custom properties merged into the error response payload. */
+  body?: Record<string, unknown>;
 };
 interface ArkstackErrorPayload {
   status: 'error';
@@ -94,15 +334,196 @@ interface ArkstackErrorPayload {
   message: string;
   errors?: unknown;
   stack?: string;
+  /** Custom fields contributed by an exception's `body`. */
+  [key: string]: unknown;
+}
+interface HookRegistry {}
+type Position = 'before' | 'after' | (string & {});
+type IHook = { [P in Position]?: (...args: any[]) => void };
+type HookName = keyof HookRegistry extends never ? string : keyof HookRegistry | (string & {});
+type HookFor<N extends string> = N extends keyof HookRegistry ? HookRegistry[N] : IHook;
+type HookPos<N extends string, P extends string> = N extends keyof HookRegistry ? P extends keyof HookRegistry[N] ? HookRegistry[N][P] : (...args: any[]) => void : (...args: any[]) => void;
+type HookPositions<N extends string> = N extends keyof HookRegistry ? keyof HookRegistry[N] : Position;
+type HookArgs<N extends string, P extends string> = N extends keyof HookRegistry ? P extends keyof HookRegistry[N] ? HookRegistry[N][P] extends ((...args: infer A) => any) ? A : any[] : any[] : any[];
+/**
+* A single source → destination mapping a package wants to publish into the
+* consuming application.
+*/
+interface PublishEntry {
+  /** Absolute path to the file or directory shipped by the package. */
+  from: string;
+  /**
+   * Destination path, relative to the application root, where the artifact is
+   * written when published.
+   */
+  to: string;
+}
+/**
+ * A group of publishable artifacts registered by a package.
+ */
+interface PublishGroup {
+  /** The package registering the artifacts, e.g. `@arkstack/cache`. */
+  package: string;
+  /**
+   * Optional tag for selective publishing (`ark publish --tag <tag>`). A
+   * package may register several groups under different tags.
+   */
+  tag?: string;
+  /** The files/directories to publish. */
+  entries: PublishEntry[];
+}
+/** Optional filter applied when reading the registry. */
+interface PublishFilter {
+  package?: string;
+  tag?: string;
 }
 //#endregion
 //#region src/system.d.ts
+/**
+ * Read the .env file
+ *
+ * @param env
+ * @param def
+ * @returns
+ */
 declare const env: GlobalEnv;
+/**
+ * Build the app url
+ *
+ * @param link
+ * @returns
+ */
 declare const appUrl: (link?: string) => string;
+/**
+ * Gets the application configuration.
+ *
+ * @param key             The configuration key to retrieve.
+ * @param defaultValue    The default value to return if the key is not found.
+ * @returns               The configuration value.
+ */
 declare const config: GlobalConfig;
+/**
+ * Resolve the unified application key.
+ *
+ * `APP_KEY` (exposed as `config('app.key')`) is the single secret used for
+ * signing and encryption across the framework. Resolution order:
+ *
+ *   1. An explicit `APP_KEY` environment variable.
+ *   2. Any legacy environment variable(s) passed in, for backward compatibility
+ *      with apps that predate `APP_KEY` (e.g. `JWT_SECRET`,
+ *      `TWO_FACTOR_ENCRYPTION_KEY`).
+ *   3. `config('app.key')` — the value from `src/config/app.ts`, which may itself
+ *      be a placeholder default when no config is loaded.
+ *
+ * @param legacy  Legacy env var name(s) to fall back to.
+ * @returns       The resolved key, or `undefined` when none is configured.
+ */
+declare const appKey: (legacy?: string | string[]) => string | undefined;
+/**
+ * Gets the current Node environment (development or production).
+ *
+ * @returns
+ */
 declare const nodeEnv: () => "prod" | "dev";
+/**
+ * Gets the output directory for the application based on the current environment.
+ *
+ * @param cwd  The current working directory (optional, defaults to Arkstack.rootDir()).
+ * @returns
+ */
 declare const outputDir: (cwd?: string) => string;
-declare const importFile: <T = unknown>(filePath: string) => Promise<T>;
+/**
+ * Map an application source path to its build-output counterpart.
+ *
+ * Application code is authored under `src/` and compiled into {@link outputDir},
+ * which strips the leading `src/` segment and emits JavaScript (e.g.
+ * `src/app/models/User.ts` -> `dist/app/models/User.js`). A TypeScript source
+ * extension is rewritten to `.js`; paths without one (directories) keep their
+ * shape. Absolute or root-relative paths outside the app root are returned
+ * unchanged.
+ *
+ * This is a pure path transform — it does not touch the filesystem. Use
+ * {@link resolveRuntimeModule} / {@link resolveRuntimeDir} when you need an
+ * existing file/dir for the current environment.
+ *
+ * @param sourcePath  Absolute or root-relative source path.
+ */
+declare const toOutputPath: (sourcePath: string) => string;
+/**
+ * Resolve an application module's source path to a file that can be imported at
+ * runtime.
+ *
+ * In development the TypeScript source is loaded directly (jiti compiles on the
+ * fly); in production only the build output ships, so the path is remapped into
+ * {@link outputDir} with a compiled extension. The first existing candidate
+ * wins — production prefers the build output, development prefers source — so a
+ * deploy that ships only `dist` never reaches for `src`.
+ *
+ * @param sourcePath  Absolute or root-relative source path, with or without extension.
+ * @returns           An existing importable path, or `sourcePath` unchanged when none exists.
+ */
+declare const resolveRuntimeModule: (sourcePath: string) => string;
+/**
+ * Resolve an application source directory to the directory that exists at
+ * runtime.
+ *
+ * The directory counterpart of {@link resolveRuntimeModule}: it maps the source
+ * directory into {@link outputDir} (stripping the leading `src/` segment) but
+ * appends no file extension. Production prefers the build output, development
+ * prefers source, and the absolute source path is returned when neither exists.
+ *
+ * @param sourcePath  Absolute or root-relative source directory.
+ * @returns           An existing directory path, or the absolute source path when none exists.
+ */
+declare const resolveRuntimeDir: (sourcePath: string) => string;
+/**
+ * Rebuild the application output (tsdown) into {@link outputDir}, wiping it first
+ * so no stale emitted modules survive a source change. Standalone — it does NOT
+ * boot the app — so the console kernel can call it to self-heal a stale or
+ * incomplete build artifact that would otherwise wedge startup. Build-only: it
+ * sets `CLI_BUILD` so tsdown emits without starting a watcher/dev server, and
+ * inherits the current `NODE_ENV` so it targets the same dir the kernel reads.
+ */
+declare const rebuildOutput: () => Promise<void>;
+/**
+ *
+ * Dynamically imports a file at the given path with full TypeScript support,
+ * including `tsconfig.json` path aliases.
+ *
+ * @param filePath - The path to the file to import.
+ * @returns The imported module typed as `T`.
+ *
+ * @example
+ * const config = await importFile<AppConfig>('./config/app.ts')
+ */
+declare const importFile: FileImporter;
+/**
+ * Discover console command classes from the application's command directory.
+ *
+ * Commands are loaded straight from TypeScript source through {@link importFile}
+ * (jiti), so they are picked up without a build and reflect edits on every run.
+ * The built output is only used as a fallback when the source directory is
+ * absent — e.g. a production deploy that ships `dist` without `src`.
+ *
+ * This exists because musket's own glob discovery imports paths with native
+ * `import()`, which silently skips `.ts` files — the reason commands previously
+ * only appeared after a `build --dev` and never reflected later edits.
+ *
+ * @param subPath   Command directory relative to the app root (src/dist aware).
+ * @returns         The discovered command classes.
+ */
+declare const discoverCommands: <T = unknown>(subPath?: string) => Promise<T[]>;
+/**
+ * Resolves the default export from a module, handling both CJS and ESM interop.
+ * In CJS modules, the default export is often the module itself (a function or object),
+ * while in ESM the default is nested under the `default` property.
+ *
+ * @param imp - The imported module
+ * @returns The resolved default export
+ */
+declare const interopDefault: <T>(imp: T | {
+  default: T;
+}) => T;
 //#endregion
 //#region src/Exceptions/Exception.d.ts
 declare class Exception extends Error {
@@ -116,6 +537,21 @@ declare class AppException extends Exception {
     [key: string]: string[] | string;
   } | undefined;
   statusCode: number;
+  /**
+   * Custom properties merged into the error response payload.
+   *
+   * When set, these are merged over the standard error payload (`status`,
+   * `code`, `message`, …), letting a subclass add fields to — or reshape — the
+   * returned error body.
+   *
+   * @example
+   * ```ts
+   * class PaymentException extends AppException {
+   *   body = { error_code: 'PAYMENT_FAILED', retryable: true }
+   * }
+   * ```
+   */
+  body?: Record<string, unknown>;
   constructor(message?: string, statusCode?: number, options?: ErrorOptions);
 }
 //#endregion
@@ -123,7 +559,33 @@ declare class AppException extends Exception {
 declare class RequestException extends AppException {
   statusCode: number;
   constructor(message?: string, statusCode?: number, options?: ErrorOptions);
+  /**
+   * Asserts that a value is not null or undefined.
+   *
+   * @param value
+   * @param message
+   * @param code
+   * @throws {RequestException} Throws if the value is null or undefined.
+   */
+  static assertFound<T>(value: T | null | undefined, message: string, code?: number): asserts value is T;
+  /**
+   * Asserts that a value is not null or undefined.
+   *
+   * @param value
+   * @param message
+   * @param code
+   * @throws {RequestException} Throws if the value is null or undefined.
+   * @deprecated Use assertFound instead
+   */
   static assertNotEmpty<T>(value: T | null | undefined, message: string, code?: number): asserts value is T;
+  /**
+   * Asserts that a boolean condition is true.
+   *
+   * @param boolean
+   * @param message
+   * @param code
+   * @throws {RequestException} Throws if the boolean condition is true.
+   */
   static abortIf<T>(boolean: T, message: string, code?: number): asserts boolean is T;
 }
 //#endregion
@@ -157,47 +619,198 @@ declare const shouldLogError: typeof ErrorHandler.shouldLogError;
 declare const createErrorPayload: typeof ErrorHandler.createErrorPayload;
 declare const logUnhandledError: typeof ErrorHandler.logUnhandledError;
 //#endregion
+//#region src/Publisher.d.ts
+/**
+ * Registry of artifacts packages want to publish into the consuming application.
+ *
+ * Packages call {@link Publisher.publishes} from their `setup` module so that
+ * `ark publish` can copy the artifacts (migrations, config stubs, assets, …)
+ * into the app. The registry is backed by a global symbol so it stays a single
+ * shared instance even across duplicated module copies.
+ */
+declare class Publisher {
+  /** The shared, global-symbol-backed registry of publishable groups. */
+  private static get registry();
+  /**
+   * Register artifacts a package wants to publish into the application.
+   *
+   * @example
+   * ```ts
+   * Publisher.publishes({
+   *     package: '@arkstack/cache',
+   *     tag: 'cache-migrations',
+   *     entries: [{ from: join(here, '../stubs/...'), to: 'src/database/migrations/...' }],
+   * })
+   * ```
+   *
+   * @param group  The publishable group to register.
+   */
+  static publishes(group: PublishGroup): void;
+  /**
+   * Read the registered publishable groups, optionally filtered by package or
+   * tag.
+   *
+   * @param filter  Restrict the result to a package and/or tag.
+   * @returns       The matching publishable groups.
+   */
+  static publishables(filter?: PublishFilter): PublishGroup[];
+  /** Remove every registered publishable group (primarily for tests). */
+  static clear(): void;
+}
+//#endregion
 //#region src/Hook.d.ts
-type Position = 'before' | 'after' | (string & {});
-type IHook = { [P in Position]?: (...args: any[]) => void };
 declare class Hook {
   private static hooks;
-  static set: (name: string, hook: IHook) => void;
-  static has: (name: string, pos?: Position) => boolean;
-  static get<N extends string>(name: N): IHook | undefined;
-  static get<N extends string>(name: N, pos: Position): IHook[Position] | undefined;
-  static getAll: () => Record<string, IHook>;
-  static unset: (name?: string, pos?: Position) => undefined;
+  /**
+   * Hooks define code that should run within defined boundaries to add extra functionalities.
+   *
+   * @param name
+   * @param value
+   */
+  static set<N extends HookName>(name: N | (string & {}), hook: HookFor<N>): void;
+  /**
+   * Check if a hook is defined by name
+   *
+   * @param name
+   */
+  static has<N extends HookName, P extends HookPositions<N>>(name: N | (string & {}), pos?: P): boolean;
+  /**
+   * Retrieve a defined hook by name
+   *
+   * @param name
+   */
+  static get<N extends HookName>(name: N): HookFor<N> | undefined;
+  /**
+   * Retrieve a defined hook by name and position
+   *
+   * @param name
+   * @param pos
+   */
+  static get<N extends HookName, P extends HookPositions<N>>(name: N, pos: P): HookPos<N, P> | undefined;
+  /**
+   * Retrieve a defined hook by name and position the set args for callback
+   *
+   * @param name
+   * @param pos
+   */
+  static get<N extends HookName, P extends HookPositions<N>>(name: N, pos: P, ...args: HookArgs<N, P>): void;
+  /**
+   * Retrieve all defined hooks
+   *
+   * @param name
+   */
+  static getAll: () => Record<string, IHook> & HookRegistry;
+  /**
+   * Remove the defined hook
+   *
+   * @param name
+   */
+  static unset<N extends HookName, P extends HookPositions<N>>(name?: N | (string & {}), pos?: P): undefined;
+  /**
+   * Clear all the defined hooks
+   */
   static clear: () => void;
 }
 //#endregion
-//#region src/utils/encryption.d.ts
-declare class Encryption {
-  private static readonly algorithm;
-  private static getKey;
-  static encrypt(value: string): string;
-  static decrypt(payload: string): string;
-}
-//#endregion
-//#region src/utils/hash.d.ts
-declare class Hash {
-  static make(value: string): Promise<string>;
-  static verify(value: string, hashedValue: string): Promise<boolean>;
-  static otp(digits?: number, label?: string, period?: number): TOTP;
-  static totp(secret: string, label: string, issuer?: string, period?: number): TOTP;
-}
-//#endregion
-//#region src/utils/helpers.d.ts
-type AbstractModelConstructor<TModel = unknown> = abstract new (attributes?: Record<string, unknown>) => TModel;
-type ModelConstructor<TModel extends Model = Model> = AbstractModelConstructor<TModel> & Pick<ModelStatic<TModel>, keyof ModelStatic<TModel>>;
-interface ModelRegistry {}
-type ModelName = Extract<keyof ModelRegistry, string>;
-declare const perPage: (query: {
-  limit?: number;
-  perPage?: number;
-}) => number;
-declare function getModel<TName extends ModelName>(modelName: TName): Promise<ModelRegistry[TName]>;
-declare function getModel<TModel extends AbstractModelConstructor = ModelConstructor>(modelName: string): Promise<TModel>;
-//#endregion
-export { AbstractModelConstructor, AppException, ArkstackErrorPayload, ArkstackErrorShape, DotPathValue, Encryption, ErrorHandler, Exception, GlobalConfig, GlobalEnv, Hash, Hook, IHook, Logger, LoggerChalk, LoggerLog, LoggerParseSignature, ModelConstructor, ModelRegistry, RequestException, appUrl, bindGracefulShutdown, bootWithDetectedPort, config, createErrorPayload, env, getErrorLogger, getModel, getPrimaryError, getValidationErrors, importFile, isModelNotFoundError, isValidationError, loadPrototypes, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, renderError, serializeError, shouldHideStack, shouldLogError, toErrorShape };
-//# sourceMappingURL=index.d.ts.map
+//#region src/EnvLoader.d.ts
+/**
+ * Loads environment variables, reading the `.env` file on first access.
+ *
+ * The `.env` file is loaded lazily the first time a variable is read, so
+ * environment access never depends on a side-effect `import 'dotenv/config'`
+ * running first. Import ordering — which linters and bundlers may rewrite —
+ * could otherwise place an env-reading module before dotenv has populated
+ * `process.env`, leaving that module with default/stale values.
+ * `dotenv.config()` never overrides variables already set, so the lazy load is
+ * safe alongside other loaders.
+ */
+declare class EnvLoader {
+  private loaded;
+  /**
+   * Load the `.env` file once.
+   *
+   * @returns
+   */
+  private ensureLoaded;
+  /**
+   * Read an environment variable, coercing booleans, numbers and `null`, and
+   * falling back to `defaultValue` when it is unset.
+   *
+   * @param name          The variable name.
+   * @param defaultValue  Returned when the variable is unset.
+   */
+  get<X = never, D = undefined, K extends string = string>(name: K, defaultValue?: D): EnvReturn<X, K, D>;
+}
+/**
+ * Shared environment loader backing {@link env}.
+ */
+declare const envLoader: EnvLoader;
+//#endregion
+//#region src/ConfigLoader.d.ts
+declare const CONFIG_KEY: unique symbol;
+/**
+ * Loads and resolves application configuration from the config directory.
+ *
+ * Config modules are read once (lazily) from the output directory and cached on
+ * a global symbol, then queried by dot-path. A partial config object can also be
+ * merged in at runtime.
+ */
+declare class ConfigLoader {
+  /**
+   * The cached config store, shared across instances via a global symbol.
+   */
+  private get store();
+  private set store(value);
+  /**
+   * Read and cache config modules from the config directory on first use.
+   */
+  private load;
+  /**
+   * Resolve the directory to load config modules from.
+   *
+   * Prefers an explicit `CONFIG_PATH`, then the environment-selected output
+   * directory. Falls back to the other build output (`dist` ⇄
+   * `.arkstack/build`) so config still loads if the selected directory is
+   * missing or transiently emptied — e.g. a concurrent rebuild (`clean: true`)
+   * during a test run.
+   */
+  private resolveConfigDir;
+  /**
+   * Resolve configuration: read a dot-path value, merge a partial config
+   * object, or return the whole config.
+   *
+   * @param key           Dot-path to read, or an object to merge in.
+   * @param defaultValue  Returned when a string key is not found.
+   */
+  resolve<X extends ConfigRegistry | unknown = unknown, P extends DotPath<X> | undefined = undefined>(key?: P, defaultValue?: any): any;
+}
+/**
+ * Shared config loader backing {@link config}.
+ */
+declare const configLoader: ConfigLoader;
+//#endregion
+//#region src/tls.d.ts
+interface TlsCredentials {
+  /** PEM-encoded private key. */
+  key: string;
+  /** PEM-encoded certificate. */
+  cert: string;
+}
+/**
+ * Generate (and cache) an in-memory self-signed TLS certificate for local HTTPS
+ * development. `selfsigned` is imported lazily so it's only loaded when secure
+ * dev mode is actually used.
+ *
+ * The certificate is not trusted by browsers (expect the usual self-signed
+ * warning); it exists only so the dev server can speak HTTPS.
+ *
+ * @param host  The common name for the certificate (defaults to `localhost`).
+ */
+declare const devTlsCredentials: (host?: string) => Promise<TlsCredentials>;
+/**
+ * The machine's first non-internal IPv4 address — its address on the local
+ * network — or `undefined` when only loopback interfaces are available.
+ */
+declare const localNetworkAddress: () => string | undefined;
+//#endregion
+export { AbstractModelConstructor, AppConfig, AppException, ArkstackErrorPayload, ArkstackErrorShape, CONFIG_KEY, ConfigLoader, ConfigRegistry, ConfigShape, DotPath, DotPathValue, Encryption, EnvKey, EnvLoader, EnvLookup, EnvRegistry, EnvReturn, ErrorHandler, Exception, FileImporter, GlobalConfig, GlobalEnv, Hash, Hook, HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, IHook, Logger, LoggerChalk, LoggerLog, LoggerParseSignature, MergedConfig, ModelConstructor, ModelRegistry, Primitive, PublishEntry, PublishFilter, PublishGroup, Publisher, RequestException, TlsCredentials, UnionToIntersection, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, devTlsCredentials, discoverCommands, env, envLoader, getErrorLogger, getModel, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, localNetworkAddress, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };