ensure-running 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,356 @@
+/**
+ * Strips node, runner, and script path tokens from raw {@link process.argv}.
+ */
+declare function normalizeArgv(argv: string[]): string[];
+
+/**
+ * Result of parsing service-specific CLI flags.
+ */
+interface ServiceParseResult<TOptions = unknown> {
+    options: TOptions;
+    remaining: string[];
+}
+/**
+ * Contract for a service that can be ensured before running a command.
+ *
+ * Custom services in `.er/services` should use {@link defineEnsureService} and `export default`.
+ */
+interface EnsureService<TOptions = unknown> {
+    /** Stable service id used on the CLI (e.g. `docker`). */
+    readonly id: string;
+    /** Optional short aliases (e.g. `d`). */
+    readonly aliases?: readonly string[];
+    /**
+     * Consumes service flags from the start of {@link argv}.
+     * Stops at the first token that is not a service flag.
+     */
+    parseArgs(argv: string[]): ServiceParseResult<TOptions>;
+    /** Runs the ensure/check flow and returns a process exit code. */
+    run(options: TOptions): Promise<number>;
+    /** Prints service-specific help to stdout. */
+    printHelp?(): void;
+}
+
+/**
+ * Defines an ensure service with compile-time shape checking.
+ *
+ * Use in `.er/services` files:
+ *
+ * ```ts
+ * export default defineEnsureService({
+ *     id: "postgres",
+ *     parseArgs(argv) { return { options: {}, remaining: argv }; },
+ *     async run() { return 0; }
+ * });
+ * ```
+ */
+declare function defineEnsureService<TOptions = unknown>(service: EnsureService<TOptions>): EnsureService<TOptions>;
+
+/**
+ * Registry of ensure services addressable from the CLI.
+ */
+declare class ServiceRegistry {
+    private readonly services;
+    /**
+     * Registers a service by id and optional aliases.
+     */
+    register(service: EnsureService): void;
+    /**
+     * Resolves a service by id or alias.
+     */
+    resolve(name: string): EnsureService | undefined;
+    /**
+     * Returns registered services without alias duplicates.
+     */
+    list(): EnsureService[];
+}
+
+/** Separator between service chain and trailing command. */
+declare const CommandSeparator = "--";
+/**
+ * Thrown when argv tokens appear after services without {@link CommandSeparator}.
+ */
+declare class CommandSeparatorError extends Error {
+    constructor(token: string);
+}
+/**
+ * Thrown when {@link CommandSeparator} is present without a trailing command.
+ */
+declare class MissingCommandError extends Error {
+    constructor();
+}
+/**
+ * One service invocation parsed from argv.
+ */
+interface ServiceInvocation {
+    service: EnsureService;
+    options: unknown;
+}
+/**
+ * Parsed ensure-running CLI invocation.
+ */
+interface ParsedInvocation {
+    services: ServiceInvocation[];
+    command?: string[];
+}
+/**
+ * Parses argv into chained service invocations and an optional trailing command.
+ * A trailing command requires an explicit {@link CommandSeparator} after services.
+ */
+declare function parseInvocation(argv: string[], registry: ServiceRegistry): ParsedInvocation;
+/**
+ * Ensures all services in order, then optionally runs a command.
+ */
+declare function runInvocation(invocation: ParsedInvocation): Promise<number>;
+/**
+ * Spawns a command with inherited stdio.
+ */
+declare function runCommand(command: string[]): Promise<number>;
+
+/**
+ * Shared types and default option values.
+ */
+/**
+ * Optional logger hooks for progress output.
+ */
+interface DockerLogger {
+    info?(message: string): void;
+    warn?(message: string): void;
+    debug?(message: string): void;
+}
+/**
+ * Options for {@link ensureDockerRunning}.
+ */
+interface EnsureDockerOptions {
+    /** Maximum wait time in ms for the daemon to become ready. Default: 120_000. */
+    timeout?: number;
+    /** Poll interval in ms between readiness checks. Default: 1_000. */
+    interval?: number;
+    /** When true, attempt to start Docker if the daemon is not running. Default: true. */
+    autoStart?: boolean;
+    /** Optional logger for progress messages. */
+    logger?: DockerLogger;
+}
+/**
+ * Result of {@link detectDocker}.
+ */
+interface DockerDetectionResult {
+    installed: boolean;
+    running: boolean;
+    version?: string;
+    executable?: string;
+}
+/**
+ * Default options merged into {@link ensureDockerRunning} calls.
+ */
+declare const DefaultEnsureDockerOptions: Required<Pick<EnsureDockerOptions, "timeout" | "interval" | "autoStart">>;
+
+/**
+ * Returns true when the Docker daemon is reachable. Never throws.
+ */
+declare function isDockerRunning(): Promise<boolean>;
+/**
+ * Ensures Docker is installed, started, and ready for use.
+ *
+ * @param options Timeout, polling, auto-start, and logger options.
+ */
+declare function ensureDockerRunning(options?: EnsureDockerOptions): Promise<void>;
+
+/**
+ * Detects Docker installation and daemon status.
+ */
+declare function detectDocker(): Promise<DockerDetectionResult>;
+
+/**
+ * Stable error codes for Docker-related failures.
+ */
+declare enum DockerErrorCode {
+    NOT_INSTALLED = "NOT_INSTALLED",
+    NOT_RUNNING = "NOT_RUNNING",
+    START_FAILED = "START_FAILED",
+    TIMEOUT = "TIMEOUT"
+}
+/**
+ * Base error for all Docker ensure failures.
+ */
+declare class DockerError extends Error {
+    readonly code: DockerErrorCode;
+    constructor(message: string, code: DockerErrorCode, options?: ErrorOptions);
+}
+/**
+ * Thrown when the Docker CLI is not installed or not on PATH.
+ */
+declare class DockerNotInstalledError extends DockerError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when Docker is installed but the daemon is not reachable and autoStart is false.
+ */
+declare class DockerNotRunningError extends DockerError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when auto-start was attempted but every strategy failed.
+ */
+declare class DockerStartError extends DockerError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when the daemon did not become ready within the configured timeout.
+ */
+declare class DockerTimeoutError extends DockerError {
+    constructor(timeoutMs: number);
+}
+
+/**
+ * Docker service CLI modes.
+ */
+declare enum DockerServiceMode {
+    ENSURE = "ENSURE",
+    CHECK = "CHECK"
+}
+/**
+ * Parsed docker service CLI options.
+ */
+interface DockerServiceOptions {
+    mode: DockerServiceMode;
+    timeout: number;
+    interval: number;
+    autoStart: boolean;
+    quiet: boolean;
+}
+/**
+ * Parses docker-specific flags from argv without consuming the trailing command.
+ */
+declare function parseDockerServiceArgs(argv: string[]): ServiceParseResult<DockerServiceOptions>;
+/**
+ * Runs the docker service and returns a process exit code.
+ */
+declare function runDockerService(options: DockerServiceOptions): Promise<number>;
+/**
+ * Prints docker service help.
+ */
+declare function printDockerServiceHelp(): void;
+/**
+ * Built-in Docker ensure service.
+ */
+declare const dockerService: EnsureService<DockerServiceOptions>;
+
+/**
+ * Thrown when one or more services fail during {@link ensureRunning}.
+ */
+declare class EnsureRunningError extends Error {
+    readonly serviceId: string;
+    readonly exitCode: number;
+    constructor(serviceId: string, exitCode: number, message?: string);
+}
+/**
+ * Supported service ids for the default registry.
+ */
+declare enum EnsureServiceId {
+    DOCKER = "docker"
+}
+/**
+ * Docker-specific options for the programmatic API.
+ */
+interface EnsureDockerApiOptions {
+    /** When true, only checks daemon reachability and never auto-starts. */
+    check?: boolean;
+    /** Max wait in ms for daemon readiness after start. */
+    timeout?: number;
+    /** Poll interval in ms between readiness checks. */
+    interval?: number;
+    /** Attempt to start Docker when the daemon is down. */
+    autoStart?: boolean;
+    /** Suppress service progress output. */
+    quiet?: boolean;
+    /** Optional logger hooks (ignored when `quiet` is true). */
+    logger?: EnsureDockerOptions["logger"];
+}
+/**
+ * One service entry for {@link ensureRunning}.
+ */
+type EnsureServiceInput = EnsureServiceId | "docker" | "d" | {
+    service: EnsureServiceId.DOCKER | "docker";
+    options?: EnsureDockerApiOptions;
+};
+/**
+ * Programmatic ensure-running request.
+ */
+interface EnsureRunningRequest {
+    /** Services to run in order. */
+    services: EnsureServiceInput[];
+    /** Optional command to spawn after all services succeed. */
+    command?: string[];
+    /** Custom service registry (defaults to built-in + `.er/services`). */
+    registry?: ServiceRegistry;
+    /** Working directory used to discover `.er/services` when registry is omitted. */
+    cwd?: string;
+}
+/**
+ * Ensures one or more services are ready. Throws {@link EnsureRunningError} on failure.
+ */
+declare function ensureRunning(services: EnsureServiceInput[]): Promise<void>;
+declare function ensureRunning(request: EnsureRunningRequest): Promise<void>;
+/**
+ * Ensures services, then optionally runs a command. Returns a process exit code.
+ */
+declare function runEnsureRunning(request: EnsureRunningRequest): Promise<number>;
+/**
+ * Ensures Docker is installed, started, and ready. Throws typed docker errors.
+ */
+declare function ensureDocker(options?: EnsureDockerApiOptions): Promise<void>;
+/**
+ * Namespaced helpers for programmatic use.
+ */
+declare const ensure: {
+    docker: typeof ensureDocker;
+    running: typeof ensureRunning;
+};
+
+/**
+ * Creates a registry with built-in services and project-local `.er/services`.
+ */
+declare function createServiceRegistry(cwd?: string): Promise<ServiceRegistry>;
+/**
+ * Built-in services only (sync, for tests and programmatic use without custom loading).
+ */
+declare function createBuiltInServiceRegistry(): ServiceRegistry;
+
+/**
+ * Global CLI modes.
+ */
+declare enum CliMode {
+    HELP = "HELP",
+    VERSION = "VERSION",
+    RUN = "RUN"
+}
+
+/**
+ * Reads the package version from package.json.
+ */
+declare function readPackageVersion(): string;
+/**
+ * Prints top-level CLI usage.
+ */
+declare function printCliHelp(registry: ServiceRegistry): void;
+/**
+ * Runs the ensure-running CLI.
+ */
+declare function runCli(argv: string[], registry?: ServiceRegistry): Promise<number>;
+
+/**
+ * Validates a custom service loaded from `.er/services`.
+ */
+declare function assertEnsureService(value: unknown, source: string): EnsureService;
+
+/**
+ * Finds the nearest `.er/services` directory walking up from startDir.
+ */
+declare function findCustomServicesDir(startDir: string): string | undefined;
+/**
+ * Loads custom services from `.er/services` and registers them.
+ */
+declare function loadCustomServices(registry: ServiceRegistry, cwd?: string): Promise<void>;
+
+export { CliMode, CommandSeparator, CommandSeparatorError, ServiceRegistry as CoreServiceRegistry, DefaultEnsureDockerOptions, type DockerDetectionResult, DockerError, DockerErrorCode, type DockerLogger, DockerNotInstalledError, DockerNotRunningError, DockerServiceMode, type DockerServiceOptions, DockerStartError, DockerTimeoutError, type EnsureDockerApiOptions, type EnsureDockerOptions, EnsureRunningError, type EnsureRunningRequest, type EnsureService, EnsureServiceId, type EnsureServiceInput, MissingCommandError, type ParsedInvocation, type ServiceInvocation, type ServiceParseResult, ServiceRegistry, assertEnsureService, createBuiltInServiceRegistry, createServiceRegistry, defineEnsureService, detectDocker, dockerService, ensure, ensureDocker, ensureDockerRunning, ensureRunning, findCustomServicesDir, isDockerRunning, loadCustomServices, normalizeArgv, parseDockerServiceArgs, parseInvocation, printCliHelp, printDockerServiceHelp, readPackageVersion, runCli, runCommand, runDockerService, runEnsureRunning, runInvocation };