gemi 0.51.0 → 0.52.0

package/dist/config/index.js

@@ -1,4 +1,4 @@
 // @bun
-import"../chunk-zwpx6z5f.js";function j(h){return h}export{j as defineConfig};
+import"../chunk-0h3jr9d9.js";function j(h){return h}export{j as defineConfig};
 
 //# debugId=FB1D7FB1C6C96D0964756E2164756E21

package/dist/console/Command.d.ts

@@ -0,0 +1,143 @@
+/**
+ * A command an operator runs by hand: `gemi run backfill-avatars --dry-run`.
+ *
+ * This file is the *runtime* shape — the base class discovery walks the
+ * prototype chain for, and the statics the runner reads. It is not the
+ * authoring surface. Applications write commands with `defineCommand` in
+ * `./builder`, which produces one of these; see that file for why the authoring
+ * surface is a builder and not a class body.
+ *
+ * ### Why the schema is descriptors and not a signature string
+ *
+ * Laravel spells this `protected $signature = 'mail:send {user} {--queue}'`, and
+ * the string is the whole schema. It reads beautifully and TypeScript cannot see
+ * a word of it: a brace in the wrong place is a parse error the first time
+ * somebody runs the command, months after it was written, and the parser is a
+ * piece of framework surface with its own failure modes. The descriptors below
+ * say the same thing in a shape the compiler checks — and, through the builder,
+ * in a shape that types the handler's own body.
+ *
+ * ### Why the name is declared and never falls back to the class name
+ *
+ * `Job` keys off `static name`, which shadows `Function.name`. That is the right
+ * trade there: a job's name *is* its class name, and the shadow is what makes it
+ * a string literal that survives minification. Here it is the wrong one twice
+ * over. A command's name is a CLI token (`backfill-avatars`, `db:seed`) with no
+ * relationship to the class name, so an implicit fallback would only ever be
+ * wrong; and shadowing `Function.name` costs the one error anybody will actually
+ * hit — "two commands claim `db:seed`" — the ability to say *which two*.
+ *
+ * ### The minification hazard does not reach here
+ *
+ * `services/discovery.ts` warns about a job that never declared `static name`,
+ * because two halves have to agree on one string across a bundler: the
+ * dispatcher, minified into `dist/server/server.mjs`, and discovery, reading the
+ * source. A command has one half — a human types the name and it is matched
+ * against discovery-on-source. Nothing in the server bundle names a command, and
+ * `gemi build` keeps `app/commands` out of the bundle anyway. So there is no
+ * `warnIfNameWillNotSurviveTheBuild` equivalent below, and adding one by analogy
+ * would be noise.
+ *
+ * If a `Command.call("db:seed")` reachable from a controller is ever added, that
+ * changes — and `commandName` being a declared string literal already covers it,
+ * which is one more reason not to fall back to the class binding.
+ */
+/** A positional argument. `variadic` collects the rest and must come last. */
+export interface ArgSpec {
+    description?: string;
+    /**
+     * Missing it is a usage error rather than an `undefined` in the handler.
+     * Mutually exclusive with `default` — an argument that is supplied when absent
+     * cannot also be absent, and declaring both is refused rather than silently
+     * resolved in one direction.
+     */
+    required?: boolean;
+    /** Collects every remaining positional. Only legal on the last argument. */
+    variadic?: boolean;
+    /** Supplied when the argument is absent, which makes it always present. */
+    default?: string;
+}
+/**
+ * A flag. The `type` decides both how the value is parsed and what the handler
+ * sees, which is why it is required rather than defaulted to `string`: a
+ * `--dry-run` declared without a type would arrive as the string `""`, and every
+ * `if (options.dryRun)` over it would be wrong in the one direction nobody
+ * tests.
+ */
+export type OptionSpec = {
+    type: "boolean";
+    description?: string;
+    /** Single character, without the dash. */
+    alias?: string;
+    default?: boolean;
+} | {
+    type: "string";
+    description?: string;
+    alias?: string;
+    default?: string;
+    required?: boolean;
+} | {
+    type: "number";
+    description?: string;
+    alias?: string;
+    default?: number;
+    required?: boolean;
+};
+/** An argument as stored on the class: the spec, plus the name it was given. */
+export type CommandArgument = ArgSpec & {
+    name: string;
+};
+/** An option as stored on the class: the spec, plus the name it was given. */
+export type CommandOption = OptionSpec & {
+    name: string;
+};
+/** What a handler may return. `void` and `0` mean the same thing. */
+export type CommandResult = Promise<number | void> | number | void;
+/**
+ * A command that failed on purpose.
+ *
+ * The distinction `bin/check-models.ts` draws between `CheckModelsError` and
+ * everything else, in the one place an application can reach it: this is a
+ * sentence written for the terminal and is printed without a stack, while
+ * anything else that escapes a handler is a bug and keeps its stack.
+ */
+export declare class CommandFailed extends Error {
+    readonly code: number;
+    constructor(message: string, code?: number);
+}
+/**
+ * The base class. Discovery finds subclasses of this; the runner reads the
+ * statics and calls `run`.
+ *
+ * Subclassing it by hand works and is what `defineCommand` does under the hood,
+ * but it gives up the typing that is the whole point of the builder — `run`'s
+ * parameter cannot be inferred from statics declared on the subclass, because
+ * TypeScript does not contextually type an overriding method's parameters. Write
+ * commands with `defineCommand`.
+ */
+export declare class Command {
+    /**
+     * The name typed on the command line. Mandatory: there is no sensible default
+     * and the class name is not one.
+     */
+    static commandName: string;
+    /** One line, printed by `gemi run` with no name and at the top of `--help`. */
+    static description: string;
+    /** Positional arguments, in order. A variadic one must be last. */
+    static args: CommandArgument[];
+    /** Flags. Declared in camelCase; `dryRun` is spelled `--dry-run` on the CLI. */
+    static options: CommandOption[];
+    /**
+     * The body.
+     *
+     * Runs inside `kernel.run()`, so `app(MailManager)` and a model read resolve
+     * exactly as they do in a request handler. Resolve services *here* rather than
+     * at module load: a command file is imported by discovery before the container
+     * has finished booting, and a service captured at the top of the file is
+     * captured from a container that is not ready.
+     */
+    run(_ctx: any): CommandResult;
+}
+/** The type of a class `defineCommand(...).handle(...)` produces. */
+export type CommandClass = typeof Command;
+//# sourceMappingURL=Command.d.ts.map

package/dist/console/Command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Command.d.ts","sourceRoot":"","sources":["../../console/Command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,OAAO;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAClB;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEN,gFAAgF;AAChF,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;AAEnE;;;;;;;GAOG;AACH,qBAAa,aAAc,SAAQ,KAAK;IAGpC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBADrB,OAAO,EAAE,MAAM,EACN,IAAI,GAAE,MAAU;CAK5B;AAED;;;;;;;;;GASG;AACH,qBAAa,OAAO;IAClB;;;OAGG;IACH,MAAM,CAAC,WAAW,SAAW;IAE7B,+EAA+E;IAC/E,MAAM,CAAC,WAAW,SAAM;IAExB,mEAAmE;IACnE,MAAM,CAAC,IAAI,EAAE,eAAe,EAAE,CAAM;IAEpC,gFAAgF;IAChF,MAAM,CAAC,OAAO,EAAE,aAAa,EAAE,CAAM;IAErC;;;;;;;;OAQG;IACH,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,aAAa;CAC9B;AAED,qEAAqE;AACrE,MAAM,MAAM,YAAY,GAAG,OAAO,OAAO,CAAC"}

package/dist/console/CommandRegistry.d.ts

@@ -0,0 +1,46 @@
+import type { CommandClass } from "./Command";
+/**
+ * The commands an application has, and the rules about what a command may be.
+ *
+ * A plain class, not a container service, and that is a decision rather than an
+ * omission. `QueueManager` and `Scheduler` are bound and populated during boot
+ * because the server needs them: a dispatch or a tick can arrive at any moment
+ * after boot finishes. A command registry has exactly one consumer — `gemi run`,
+ * which builds one, uses it, and exits. Making it a boot step would import every
+ * file under `app/commands` into every `gemi dev`, every `gemi start` and every
+ * deployed server process, on every start, for code no request will ever reach.
+ * That is the cost `bin/check-models.ts` argues against at length, and there is
+ * no benefit here to weigh against it.
+ *
+ * What the class is for is the rules below, and the `commands` getter — the same
+ * seam `QueueManager.registeredJobs` and `Scheduler.jobs` exist to give a test:
+ * what was actually taken, rather than what a walk would find if asked again.
+ */
+export declare class CommandRegistry {
+    private readonly byName;
+    /**
+     * @throws ConsoleError naming the offending class for a command that cannot
+     * be run.
+     *
+     * Every refusal here is loud and immediate. There is a human at a terminal,
+     * and every one of these is a mistake in the application's own source that
+     * they are better off seeing now than after the command they meant to run
+     * silently did not exist.
+     *
+     * `ConsoleError` rather than a plain `Error` so the runner prints the message
+     * alone. These are sentences with the fix named in them, and burying one under
+     * `at new CommandRegistry (…)` plus the runner's own frames points the reader
+     * at framework code when the mistake is in their `app/commands`.
+     */
+    constructor(commands: CommandClass[]);
+    /** What was actually taken. */
+    get commands(): CommandClass[];
+    get(name: string): CommandClass | undefined;
+    /**
+     * The nearest names to something that did not match, for the "did you mean"
+     * line. Prefix matches first, then substring, then names sharing a namespace —
+     * `db:sed` should find `db:seed`, and a typo in a namespace is the common case.
+     */
+    suggest(name: string): string[];
+}
+//# sourceMappingURL=CommandRegistry.d.ts.map

package/dist/console/CommandRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandRegistry.d.ts","sourceRoot":"","sources":["../../console/CommandRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAE1D;;;;;;;;;;;;;OAaG;gBACS,QAAQ,EAAE,YAAY,EAAE;IAgCpC,+BAA+B;IAC/B,IAAI,QAAQ,IAAI,YAAY,EAAE,CAE7B;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAI3C;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;CAuBhC"}

package/dist/console/builder.d.ts

@@ -0,0 +1,115 @@
+import { type ArgSpec, type CommandClass, type CommandResult, type OptionSpec } from "./Command";
+import type { CommandContext } from "./context";
+/**
+ * Declaring a command, in the one shape that can type its own body.
+ *
+ * ### Why a builder and not a class
+ *
+ * The point of declaring arguments and options at all is that the handler then
+ * knows what it has. A class body cannot deliver that, and the reason is a hard
+ * TypeScript rule rather than a matter of arrangement: **TypeScript does not
+ * contextually type a method's parameters from the base-class method it
+ * overrides.** So both class-shaped designs fail in the same place:
+ *
+ * ```ts
+ * class Backfill extends Command {
+ *   static args = [{ name: "since", required: true }];
+ *   async run(ctx) {}                       // implicit any
+ * }
+ *
+ * class Backfill extends Command.define({ since: { required: true } }) {
+ *   async run(ctx) {}                       // still implicit any — the
+ * }                                         // configured base's signature does
+ *                                           // not flow into the override
+ * ```
+ *
+ * The author's only way out is to restate the type by hand, which is the
+ * ceremony the descriptors existed to remove — and which nothing enforces, so a
+ * wrong restatement compiles.
+ *
+ * A **function expression passed as an argument is contextually typed**. That is
+ * the entire mechanism here, and it is why this is a builder rather than sugar:
+ * `.handle(fn)` carries the accumulated argument and option types into `fn`'s
+ * parameter with nothing written by hand and nothing to keep in step.
+ *
+ * ### What it produces
+ *
+ * A `Command` subclass, so nothing downstream knows the difference: discovery
+ * finds it by prototype chain, and the registry, parser and `--help` read the
+ * same statics they would read off a hand-written class. The builder is an
+ * authoring surface over one runtime shape, not a second mechanism.
+ */
+/**
+ * Marks a builder that was never finished. `discoverCommands` looks for this on
+ * the exports it is about to discard — see the note on `handle` below.
+ */
+export declare const BUILDER_BRAND: unique symbol;
+/** Flattens an accumulated intersection so editor hovers stay readable. */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * What the handler sees for one argument.
+ *
+ * The order matters: `variadic` first because it wins over everything, then the
+ * two ways an argument is guaranteed present. Anything else can be absent and
+ * says so.
+ */
+export type ArgValue<S> = S extends {
+    variadic: true;
+} ? string[] : S extends {
+    required: true;
+} ? string : S extends {
+    default: string;
+} ? string : string | undefined;
+/** What the handler sees for one option. */
+export type OptionValue<S> = S extends {
+    type: "boolean";
+} ? boolean : S extends {
+    type: "number";
+} ? S extends {
+    default: number;
+} ? number : S extends {
+    required: true;
+} ? number : number | undefined : S extends {
+    default: string;
+} ? string : S extends {
+    required: true;
+} ? string : string | undefined;
+export interface CommandBuilder<A extends Record<string, unknown>, O extends Record<string, unknown>> {
+    /** One line, shown in the listing and at the top of `--help`. */
+    describe(text: string): CommandBuilder<A, O>;
+    /**
+     * A positional argument. Declared in the order it is read from the command
+     * line; a `variadic` one must be last.
+     */
+    arg<N extends string, const S extends ArgSpec = {}>(name: N, spec?: S): CommandBuilder<A & {
+        [K in N]: ArgValue<S>;
+    }, O>;
+    /**
+     * A flag. Declared in camelCase and spelled in kebab-case on the command line,
+     * so `.option("dryRun", …)` is `--dry-run` for the operator and
+     * `options.dryRun` in the handler — no string key nobody can autocomplete, and
+     * no CLI flag with a capital letter in it.
+     */
+    option<N extends string, const S extends OptionSpec>(name: N, spec: S): CommandBuilder<A, O & {
+        [K in N]: OptionValue<S>;
+    }>;
+    /**
+     * The body, and the terminal of the chain.
+     *
+     * A builder that never reaches here is not a class, so discovery would skip it
+     * and the command would simply vanish from `gemi run` with nothing raised —
+     * the silence #322 and #323 exist to remove, reintroduced by a new authoring
+     * surface. `discoverCommands` therefore looks for `BUILDER_BRAND` among the
+     * exports it discards and refuses the file by name.
+     */
+    handle(fn: (ctx: CommandContext<Simplify<A>, Simplify<O>>) => CommandResult): CommandClass;
+}
+export declare function defineCommand(name: string): CommandBuilder<{}, {}>;
+/** True for a builder that never called `.handle()`. */
+export declare function isUnfinishedBuilder(value: unknown): value is {
+    [BUILDER_BRAND]: string;
+};
+export {};
+//# sourceMappingURL=builder.d.ts.map

package/dist/console/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../console/builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,OAAO,EAEZ,KAAK,YAAY,EAEjB,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,OAAO,MAA2C,CAAC;AAE/E,2EAA2E;AAC3E,KAAK,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,EAAE,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAClD,MAAM,EAAE,GACR,CAAC,SAAS;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC1B,MAAM,GACN,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3B,MAAM,GACN,MAAM,GAAG,SAAS,CAAC;AAE3B,4CAA4C;AAC5C,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACtD,OAAO,GACP,CAAC,SAAS;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC1B,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3B,MAAM,GACN,CAAC,SAAS;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC1B,MAAM,GACN,MAAM,GAAG,SAAS,GACtB,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3B,MAAM,GACN,CAAC,SAAS;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC1B,MAAM,GACN,MAAM,GAAG,SAAS,CAAC;AAE7B,MAAM,WAAW,cAAc,CAC7B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAEjC,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAE7C;;;OAGG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,OAAO,GAAG,EAAE,EAChD,IAAI,EAAE,CAAC,EACP,IAAI,CAAC,EAAE,CAAC,GACP,cAAc,CAAC,CAAC,GAAG;SAAG,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;KAAE,EAAE,CAAC,CAAC,CAAC;IAEpD;;;;;OAKG;IACH,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,UAAU,EACjD,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,CAAC,GACN,cAAc,CAAC,CAAC,EAAE,CAAC,GAAG;SAAG,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;KAAE,CAAC,CAAC;IAEvD;;;;;;;;OAQG;IACH,MAAM,CACJ,EAAE,EAAE,CAAC,GAAG,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,aAAa,GACnE,YAAY,CAAC;CACjB;AA4BD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,EAAE,EAAE,EAAE,CAAC,CAqIlE;AAED,wDAAwD;AACxD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI;IAAE,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAMtC"}

package/dist/console/builder.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=builder.test-d.d.ts.map

package/dist/console/builder.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.test-d.d.ts","sourceRoot":"","sources":["../../console/builder.test-d.ts"],"names":[],"mappings":""}

package/dist/console/config.d.ts

@@ -0,0 +1,40 @@
+import type { CommandClass } from "./Command";
+export interface CommandConfig {
+    /**
+     * The `Command` classes this application can run, or nothing.
+     *
+     * ### The rule, exactly
+     *
+     * **Declared wins, and `[]` is declared.** A `commands` that is present is
+     * used verbatim and no directory is read — the escape hatch for an app whose
+     * commands live somewhere the walk cannot reach, and for a deploy that ships
+     * no source. An empty array means an app with no commands and says so; it does
+     * not mean "find some".
+     *
+     * **Absent or `undefined` discovers.** `undefined` counts as absent for the
+     * same reason `withDefaults` treats it that way everywhere else: a key spread
+     * in from an optional value is an omission, not an instruction.
+     *
+     * ### One way this differs from `queue` and `schedule`
+     *
+     * There, the cost of the list and the directory disagreeing is silence — a
+     * dispatch dropped with a line on stderr nobody reads, a report that stops
+     * arriving. Here it is a person typing `gemi run thing` and being told, in
+     * those words, that there is no command called `thing`. The rule is kept for
+     * consistency and for the source-less-deploy case, not because the stakes are
+     * the same.
+     */
+    commands?: CommandClass[];
+    /**
+     * Where to look when `commands` was not declared. Relative to the project
+     * root, or absolute.
+     *
+     * Every `.ts`/`.tsx` file underneath is imported when a command is run, so
+     * this wants to be a directory of command declarations rather than a directory
+     * that merely contains some.
+     */
+    commandsDir?: string;
+}
+export declare function defineCommandConfig(config: CommandConfig): CommandConfig;
+export declare function commandConfigDefaults(): Required<CommandConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/console/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../console/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAU9C,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAE1B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAExE;AAED,wBAAgB,qBAAqB,IAAI,QAAQ,CAAC,aAAa,CAAC,CAK/D"}

package/dist/console/context.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The single argument a command handler receives.
+ *
+ * ### Why the output helpers live here and not on `this`
+ *
+ * The authoring surface is a builder terminating in `.handle(fn)`, and `fn` is
+ * an arrow function with no useful `this`. That turns out to be the better
+ * arrangement rather than a cost to work around: the helpers are destructured on
+ * the first line of the handler, so a reader sees which streams a command writes
+ * to before reading any of it, and a test supplies its own writers by passing a
+ * context instead of subclassing.
+ *
+ * ### Why there are three of them
+ *
+ * The load-bearing thing a framework can own here is **stream discipline, not
+ * colour**. A diagnostic printed to stdout is what breaks
+ * `TOTAL=$(gemi run count-users)` and what makes a CI grep match a progress line
+ * instead of the answer, and that mistake is invisible until somebody pipes the
+ * command somewhere.
+ *
+ * So: `line` is the command's answer and goes to stdout, `error` is a diagnostic
+ * and goes to stderr, and `fail` ends the command. Deliberately absent are
+ * `info`/`success` (`line` with a colour, and colour is the application's
+ * business), `warn` (identical to `error`; two names for one stream is a coin
+ * flip at every call site), and tables or progress bars — a console formatting
+ * library is a project, not a feature.
+ */
+export interface CommandContext<A = Record<string, unknown>, O = Record<string, unknown>> {
+    /** The positional arguments, by the names `.arg()` declared. */
+    args: A;
+    /** The flags, by the names `.option()` declared. */
+    options: O;
+    /**
+     * Everything after the command name, unparsed.
+     *
+     * The escape hatch, for a command that wants to forward its tail to something
+     * else. Present even when parsing succeeded, so a command never has to choose
+     * between the declared schema and the raw truth.
+     */
+    argv: readonly string[];
+    /** The command's answer, on stdout. */
+    line(message?: string): void;
+    /** A diagnostic, on stderr. Does not end the command. */
+    error(message: string): void;
+    /**
+     * Ends the command with a message and an exit code, and no stack.
+     *
+     * Throws rather than returning, so it type-checks as the last statement of any
+     * branch and a caller cannot forget to `return` after it.
+     */
+    fail(message: string, code?: number): never;
+}
+/** Where a context writes. Injectable so tests can capture without spawning. */
+export interface CommandWriters {
+    stdout: (chunk: string) => void;
+    stderr: (chunk: string) => void;
+}
+/**
+ * Writers onto this process's streams, and the means to know they landed.
+ *
+ * ### Why `flush` exists
+ *
+ * `process.stdout.write` is asynchronous when stdout is a pipe, and `gemi run`
+ * ends in an explicit `process.exit` — which it must, or a command holding a
+ * database pool open would finish its work and then sit there. Those two facts
+ * together truncate output at the pipe buffer: measured on Bun 1.3.14, a
+ * 2,000,000-byte write followed immediately by `process.exit(0)` delivers
+ * exactly 65,536 bytes through a pipe, and exits 0 while doing it. So
+ * `gemi run export-users | gzip > out.gz` silently stores a fragment — the exact
+ * idiom the three-stream design above exists to protect.
+ *
+ * The fence is the *last* write's completion callback. Chunks are flushed in
+ * order, so awaiting the newest one awaits all of them. The obvious alternatives
+ * do not work here: a zero-length `write("", cb)` used as a fence delivered only
+ * 1,310,720 of those bytes, and `writableLength` reports 0 while data is still
+ * pending, so a drain loop exits immediately. Both were measured rather than
+ * assumed.
+ */
+export interface ProcessWriters extends CommandWriters {
+    /** Resolves once everything written so far has reached the OS. */
+    flush(): Promise<void>;
+}
+export declare function processWriters(): ProcessWriters;
+export declare function createContext<A, O>(params: {
+    args: A;
+    options: O;
+    argv: readonly string[];
+    writers?: CommandWriters;
+}): CommandContext<A, O>;
+//# sourceMappingURL=context.d.ts.map

package/dist/console/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../console/context.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,cAAc,CAC7B,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3B,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAE3B,gEAAgE;IAChE,IAAI,EAAE,CAAC,CAAC;IAER,oDAAoD;IACpD,OAAO,EAAE,CAAC,CAAC;IAEX;;;;;;OAMG;IACH,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAExB,uCAAuC;IACvC,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,yDAAyD;IACzD,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC7C;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,cAAe,SAAQ,cAAc;IACpD,kEAAkE;IAClE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAgB,cAAc,IAAI,cAAc,CAyB/C;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE;IAC1C,IAAI,EAAE,CAAC,CAAC;IACR,OAAO,EAAE,CAAC,CAAC;IACX,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAavB"}

package/dist/console/errors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The failures `gemi run` prints as sentences rather than stack traces.
+ *
+ * Its own file rather than a declaration in `runner.ts`, because the classes
+ * that *raise* these are the ones the runner imports — `CommandRegistry` most of
+ * all — and a registry importing the runner to reach its error type is a cycle
+ * for no reason.
+ *
+ * The split this exists to serve is the one `bin/gemi.ts` already draws around
+ * `CheckModelsError`: a message written for the operator standing at the
+ * terminal, with the fix named in it, is printed alone; anything else is a bug
+ * in the framework and keeps its stack so it can be reported.
+ */
+export declare class ConsoleError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/console/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../console/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D"}

package/dist/console/parse.d.ts

@@ -0,0 +1,65 @@
+import type { CommandArgument, CommandOption } from "./Command";
+/**
+ * Turning what an operator typed into what a handler declared it wanted.
+ *
+ * A pure function over `(spec, argv)`, deliberately: this is where every
+ * off-by-one in argument handling lives, and a pure function is one a test can
+ * exercise a hundred ways without a project on disk, a spawned process or a
+ * booted container. `runner.ts` does the parts that need those.
+ *
+ * ### Why gemi parses this itself instead of handing it to commander
+ *
+ * commander is a dependency of this package and would resolve here, and an
+ * earlier draft used it. Two things argued it back out. The schema is already
+ * declared — named options with a `type`, not commander's `"-t, --tries <n>"`
+ * flag strings — so using commander means translating one declaration into
+ * another and then translating its output back, with the type information lost
+ * in the middle. And commander is currently a *CLI-side* concern: `bin/gemi.ts`
+ * uses it, and nothing that runs inside an application does. Keeping it that way
+ * means a command's parsing has no dependency at all, which matters more here
+ * than it looks — this code runs in the application's process, next to the
+ * application's own module graph.
+ *
+ * `usage.ts` renders `--help` from the same spec this reads, so the help and the
+ * parser cannot drift.
+ */
+/** `dryRun` -> `dry-run`. What the operator types. */
+export declare function kebab(name: string): string;
+export interface CommandSpec {
+    commandName: string;
+    args: CommandArgument[];
+    options: CommandOption[];
+}
+export type ParseResult = {
+    /**
+     * The invocation asked for help rather than for work.
+     *
+     * Reported by the parse rather than by a separate scan, because whether a
+     * `--help` is a request for help or the *value* of the option before it is a
+     * question only something tracking option arity can answer. A flat token scan
+     * reads `--message --help` as a request for help, prints usage and exits 0 —
+     * so the message is never sent and a cron wrapper branching on the exit code
+     * records a success for work that did not happen.
+     *
+     * Present on both branches, and the runner checks it first: `--help` has to
+     * work on an invocation that would otherwise be a usage error, which is
+     * precisely when somebody reaches for it.
+     */
+    help: boolean;
+} & ({
+    ok: true;
+    args: Record<string, string | string[] | undefined>;
+    options: Record<string, string | number | boolean | undefined>;
+} | {
+    ok: false;
+    errors: string[];
+});
+/**
+ * Whether this invocation is asking for help rather than running.
+ *
+ * A thin read of the parse, so the two cannot disagree about what counts as a
+ * `--help`. See `ParseResult["help"]` for why that question needs a parse at all.
+ */
+export declare function wantsHelp(spec: CommandSpec, argv: readonly string[]): boolean;
+export declare function parseArgv(spec: CommandSpec, argv: readonly string[]): ParseResult;
+//# sourceMappingURL=parse.d.ts.map

package/dist/console/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../console/parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,sDAAsD;AACtD,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK1C;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,WAAW,GAAG;IACxB;;;;;;;;;;;;;OAaG;IACH,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,CACA;IACE,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACpD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;CAChE,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAClC,CAAC;AAkBF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE7E;AAuBD,wBAAgB,SAAS,CACvB,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,WAAW,CA2Rb"}

package/dist/console/run.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run.d.ts.map

package/dist/console/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../console/run.ts"],"names":[],"mappings":""}

package/dist/console/run.js

@@ -0,0 +1,16 @@
+// @bun
+import{Ba as A,Ca as l}from"../chunk-p22rkf1g.js";import{nb as q,qb as m,yb as p}from"../chunk-tmk4zfz9.js";import{Cb as c}from"../chunk-ha7n1c94.js";import{Ce as u}from"../chunk-3y9nf09k.js";import"../chunk-mt2755rs.js";import"../chunk-qyaqg07q.js";import"../chunk-0h3jr9d9.js";function F(){let z=Promise.resolve(),M=Promise.resolve(),X=(Q,G)=>new Promise(($)=>{Q.write(G,()=>$())});return{stdout:(Q)=>{z=X(process.stdout,Q)},stderr:(Q)=>{M=X(process.stderr,Q)},flush:async()=>{await Promise.all([z,M])}}}function b(z){let M=z.writers??F();return{args:z.args,options:z.options,argv:z.argv,line:(X="")=>M.stdout(`${X}
+`),error:(X)=>M.stderr(`${X}
+`),fail:(X,Q=1)=>{throw new q(X,Q)}}}import w from"path";function V(z){return z.replace(/([a-z0-9])([A-Z])/g,"$1-$2").replace(/([A-Z])([A-Z][a-z])/g,"$1-$2").toLowerCase()}function t(z){let M=new Map,X=new Map;for(let Q of z){M.set(V(Q.name),Q),M.set(Q.name,Q);let G="alias"in Q?Q.alias:void 0;if(G)X.set(G,Q)}return{byName:M,byAlias:X}}function x(z){if(z==="--")return!0;if(!z.startsWith("-"))return!1;if(z==="-")return!1;if(/^-(\d|\.\d)/.test(z))return!1;return!0}function k(z,M){let{byName:X,byAlias:Q}=t(z.options),G=[],$=[],Z=new Map,S=!X.has("help"),C=!Q.has("h"),P=!1,D=!1,I=(J)=>G.push(`Unknown option ${J} for command "${z.commandName}".`),T=(J,Y)=>{if(Y==="--help"||Y==="-h")D=!0;G.push(Y===void 0?`Option ${J} needs a value.`:`Option ${J} needs a value, but the next token is ${JSON.stringify(Y)}, which is another option. If that really is the value, write ${J}=${Y}.`)},_=0;while(_<M.length){let J=M[_];if(J==="--"){$.push(...M.slice(_+1));break}if(J.startsWith("--")){let Y=J.slice(2),j=Y.indexOf("="),B=j===-1?Y:Y.slice(0,j),K=j===-1?void 0:Y.slice(j+1),H=X.get(B),E=!1;if(!H&&B.startsWith("no-")){let W=X.get(B.slice(3));if(W&&W.type==="boolean")H=W,E=!0}if(!H&&B==="help"&&S){P=!0,_+=1;continue}if(!H){I(`--${B}`),_+=1;continue}if(H.type==="boolean"){if(K!==void 0&&K!=="true"&&K!=="false")G.push(`Option --${V(H.name)} is a flag and takes no value, but got ${JSON.stringify(K)}.`);else{let W=K===void 0?!0:K==="true";Z.set(H.name,E?!W:W)}_+=1;continue}if(K!==void 0){Z.set(H.name,K),_+=1;continue}let U=M[_+1];if(U===void 0||x(U)){T(`--${V(H.name)}`,U),_+=1;continue}Z.set(H.name,U),_+=2;continue}if(J.startsWith("-")&&J.length>1){let Y=J.slice(1),j=!1;for(let B=0;B<Y.length;B+=1){let K=Q.get(Y[B]);if(!K){if(Y[B]==="h"&&C){P=!0;continue}I(`-${Y[B]}`);break}if(K.type==="boolean"){Z.set(K.name,!0);continue}let H=Y.slice(B+1),E=H.startsWith("=")?H.slice(1):H;if(E!==""){Z.set(K.name,E);break}let U=M[_+1];if(U===void 0||x(U)){T(`-${K.alias}`,U);break}Z.set(K.name,U),j=!0;break}_+=j?2:1;continue}$.push(J),_+=1}let L={},O=0;for(let J of z.args){if(J.variadic){let j=$.slice(O);if(O=$.length,L[J.name]=j,J.required&&j.length===0)G.push(`Missing required argument <${J.name}...>. Command "${z.commandName}" needs at least one.`);continue}let Y=$[O];if(O+=1,Y!==void 0){L[J.name]=Y;continue}if(J.default!==void 0){L[J.name]=J.default;continue}if(J.required)G.push(`Missing required argument <${J.name}>.`);L[J.name]=void 0}if(O<$.length){let J=$.slice(O);G.push(`Unexpected argument${J.length===1?"":"s"} ${J.map((Y)=>JSON.stringify(Y)).join(", ")}. Command "${z.commandName}" takes ${z.args.length} argument${z.args.length===1?"":"s"}.`)}let R={};for(let J of z.options){let Y=Z.get(J.name);if(J.type==="boolean"){R[J.name]=Y===void 0?J.default??!1:Boolean(Y);continue}if(Y===void 0){if(J.default!==void 0)R[J.name]=J.default;else if(J.required)G.push(`Missing required option --${V(J.name)}.`),R[J.name]=void 0;else R[J.name]=void 0;continue}let j=String(Y);if(J.type==="number"){let B=Number(j);if(j.trim()===""||!Number.isFinite(B))G.push(`Option --${V(J.name)} expects a number, but got ${JSON.stringify(j)}.`),R[J.name]=void 0;else R[J.name]=B;continue}R[J.name]=j}let N=P&&!D;if(G.length>0)return{ok:!1,help:N,errors:G};return{ok:!0,help:N,args:L,options:R}}function f(z,M="  "){let X=z.reduce((Q,[G])=>Math.max(Q,G.length),0);return z.map(([Q,G])=>G===""?`${M}${Q}`:`${M}${Q.padEnd(X)}  ${G}`)}function g(z){let M=z.variadic?`${z.name}...`:z.name;return z.required?`<${M}>`:`[${M}]`}function s(z){let M=(G)=>z.options.some(G),X=M((G)=>G.name==="help"||V(G.name)==="help"),Q=M((G)=>("alias"in G)&&G.alias==="h");if(X&&Q)return[];if(X)return[["-h","Show this message"]];return[[`${Q?"":"-h, "}--help`,"Show this message"]]}function v(z){let M=[],X=z.args.map(g).join(" "),Q=["gemi run",z.commandName,z.options.length>0?"[options]":"",X].filter(Boolean).join(" ");if(M.push(`Usage: ${Q}`),z.description)M.push("",z.description);if(z.args.length>0)M.push("","Arguments:"),M.push(...f(z.args.map((G)=>{let $=[G.description??"",G.default!==void 0?`(default: ${JSON.stringify(G.default)})`:""].filter(Boolean).join(" ");return[g(G),$]})));return M.push("","Options:"),M.push(...f([...z.options.map((G)=>{let $="alias"in G&&G.alias?`-${G.alias}, `:"",Z=G.type==="boolean"?"":` <${G.type}>`,S=[G.description??"",G.default!==void 0?`(default: ${JSON.stringify(G.default)})`:"","required"in G&&G.required?"(required)":""].filter(Boolean).join(" ");return[`${$}--${V(G.name)}${Z}`,S]}),...s(z)])),M.join(`
+`)}function y(z,M){let X=M.declared?`${z.length} command${z.length===1?"":"s"} declared in app/config/command.ts:`:`Commands in ${M.dir}:`;if(z.length===0)return M.declared?`app/config/command.ts declares no commands.
+
+Remove the \`commands\` key from that slice to discover the classes under ${M.dir} instead \u2014 a declared list wins, and an empty one `+'means "none, and I mean it".':`No commands found in ${M.dir}.
+
+A command is registered by existing: write a file there that exports a \`defineCommand(...).handle(...)\` chain and it will appear here.`;let Q=[...z].sort((G,$)=>G.commandName<$.commandName?-1:G.commandName>$.commandName?1:0);return[X,"",...f(Q.map((G)=>[G.commandName,G.description])),"","Run one with `gemi run <name>`, and see its arguments with `gemi run <name> --help`."].join(`
+`)}async function d(z){let M=z.writers??F(),X=(Z)=>M.stdout(`${Z}
+`),Q=(Z)=>M.stderr(`${Z}
+`),G,$;try{G=await n(z.rootDir),G.boot();let Z=G.app.config.get("command",{}),S=u(m(),Z).commandsDir,C=w.isAbsolute(S)?S:w.join(z.rootDir,S),P=Z.commands!==void 0,D=P?Z.commands:await p(C),I=new l(D),T={declared:P,dir:S};if(z.name===void 0)return X(y(I.commands,T)),0;let _=I.get(z.name);if($=_,!_){let J=I.suggest(z.name);return Q(`No command named \`${z.name}\`.`+(J.length>0?` Did you mean ${J.map((Y)=>`\`${Y}\``).join(", or ")}?`:"")),Q(""),Q(y(I.commands,T)),1}let L={commandName:_.commandName,args:_.args,options:_.options},O=k(L,z.argv);if(O.help)return X(v(_)),0;if(O.ok===!1){for(let J of O.errors)Q(J);return Q(""),Q(v(_)),1}await G.waitForBoot();let R=b({args:O.args,options:O.options,argv:z.argv,writers:M}),N=await G.run(()=>Promise.resolve(new _().run(R)));return h(N,_,Q)}catch(Z){if(Z instanceof q)return Q(Z.message),h(Z.code,$,Q,"called fail() with");if(Z instanceof A||Z instanceof c)return Q(Z.message),1;return Q(String(Z?.stack??Z)),1}finally{G?.destroy()}}async function n(z){let M=w.resolve(z,"app/kernel/Kernel.ts"),X;try{X=await import(M)}catch(Q){throw new A(`Could not load ${M}:
+    ${Q.message}
+\`gemi run\` boots your application the way the server does, so it needs the Kernel. Run it from the root of a gemi project.`,{cause:Q})}if(typeof X.default!=="function")throw new A(`${M} has no default export. gemi expects the Kernel subclass to be the default export of that file.`);return new X.default}function h(z,M,X,Q="returned"){if(z===void 0||z===null)return 0;if(typeof z==="number"&&Number.isInteger(z)&&z>=0&&z<=255)return z;let G=M?`Command "${M.commandName}"`:"The command";return X(`${G} ${Q} ${JSON.stringify(z)}, which is not an exit `+"code \u2014 an exit code is an integer from 0 to 255. Treating this as a "+"failure."),1}var[a,...o]=process.argv.slice(2),i=F();d({rootDir:process.cwd(),name:a,argv:o,writers:i}).then(async(z)=>{await i.flush(),process.exit(z)});
+
+//# debugId=3A559D4973E0E24564756E2164756E21