@seedcli/core 0.1.0

package/dist/runtime/runtime.js

@@ -0,0 +1,424 @@
+import { renderCommandHelp, renderGlobalHelp } from "../command/help.js";
+import { ParseError, parse } from "../command/parser.js";
+import { route } from "../command/router.js";
+import { discover } from "../discovery/auto-discover.js";
+import { ExtensionSetupError } from "../plugin/errors.js";
+import { loadPlugins } from "../plugin/loader.js";
+import { PluginRegistry } from "../plugin/registry.js";
+import { topoSort } from "../plugin/topo-sort.js";
+import { validateSeedcliVersion } from "../plugin/validator.js";
+/**
+ * Quick-start function for simple CLIs without the builder pattern.
+ *
+ * ```ts
+ * import { run } from "@seedcli/core";
+ *
+ * await run({
+ *   name: "mycli",
+ *   version: "1.0.0",
+ *   commands: [hello, deploy],
+ * });
+ * ```
+ */
+export async function run(config) {
+    const { build } = await import("./builder.js");
+    const builder = build(config.name).commands(config.commands).help().version(config.version);
+    if (config.defaultCommand) {
+        builder.defaultCommand(config.defaultCommand);
+    }
+    const runtime = builder.create();
+    await runtime.run();
+}
+const DEFAULT_SETUP_TIMEOUT = 10_000;
+/**
+ * The CLI runtime — executes the full lifecycle:
+ * 1. Load and validate plugins
+ * 2. Parse argv
+ * 3. Route to command
+ * 4. Run extensions setup (topological order)
+ * 5. Execute middleware chain
+ * 6. Run command handler
+ * 7. Run extensions teardown (reverse order)
+ */
+export class Runtime {
+    config;
+    registry = new PluginRegistry();
+    initialized = false;
+    constructor(config) {
+        this.config = config;
+    }
+    async run(argv) {
+        const raw = argv ?? process.argv.slice(2);
+        try {
+            // ─── Handle --version ───
+            if (this.config.versionEnabled && (raw.includes("--version") || raw.includes("-v"))) {
+                const version = this.config.version ?? "0.0.0";
+                console.log(`${this.config.brand} v${version}`);
+                return;
+            }
+            // ─── Handle --help (global) ───
+            if (this.config.helpEnabled && raw.length === 0) {
+                await this.initPlugins();
+                this.printGlobalHelp();
+                return;
+            }
+            if (this.config.helpEnabled &&
+                (raw.includes("--help") || raw.includes("-h")) &&
+                raw.length === 1) {
+                await this.initPlugins();
+                this.printGlobalHelp();
+                return;
+            }
+            // ─── Initialize plugins ───
+            await this.initPlugins();
+            // ─── Route to command ───
+            const result = route(raw, this.config.commands);
+            if (!result.command) {
+                // Try default command
+                if (this.config.defaultCommand) {
+                    await this.executeCommand(this.config.defaultCommand, raw);
+                    return;
+                }
+                // No match — show suggestions or help
+                if (result.suggestions.length > 0) {
+                    const suggestions = result.suggestions
+                        .map((s) => `  ${s.name}    ${s.description ?? ""}`)
+                        .join("\n");
+                    console.error(`Command "${raw[0]}" not found.\n\nDid you mean?\n${suggestions}\n\nRun \`${this.config.brand} --help\` for a list of available commands.`);
+                }
+                else if (this.config.helpEnabled) {
+                    this.printGlobalHelp();
+                }
+                else {
+                    console.error(`Command "${raw[0]}" not found.`);
+                }
+                process.exitCode = 1;
+                return;
+            }
+            // ─── Handle per-command --help ───
+            if (this.config.helpEnabled && result.argv.includes("--help")) {
+                const helpText = renderCommandHelp(result.command, {
+                    brand: this.config.brand,
+                    ...this.config.helpOptions,
+                });
+                console.log(helpText);
+                return;
+            }
+            // ─── Execute command ───
+            await this.executeCommand(result.command, result.argv);
+        }
+        catch (err) {
+            await this.handleError(err);
+        }
+    }
+    async initPlugins() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+        // ─── Auto-discovery ───
+        if (this.config.srcDir) {
+            const discovered = await discover(this.config.srcDir);
+            this.config.commands.push(...discovered.commands);
+            this.config.extensions.push(...discovered.extensions);
+        }
+        // ─── Scan plugin directories ───
+        for (const { dir, options } of this.config.pluginDirs) {
+            const scanned = await this.scanPluginDir(dir, options?.matching);
+            this.config.plugins.push(...scanned);
+        }
+        if (this.config.plugins.length === 0) {
+            // Still inject completions even without plugins
+            if (this.config.completionsEnabled) {
+                this.config.commands.push(this.createCompletionsCommand());
+            }
+            return;
+        }
+        // Load all plugin configs (dynamic imports for string sources)
+        const loaded = await loadPlugins(this.config.plugins);
+        // Validate seedcli version compatibility
+        const runtimeVersion = this.config.version ?? "0.0.0";
+        for (const plugin of loaded) {
+            validateSeedcliVersion(plugin, runtimeVersion);
+        }
+        // Register each plugin (validates on register, deduplicates, checks conflicts)
+        for (const plugin of loaded) {
+            this.registry.register(plugin);
+        }
+        // Validate peer dependencies across all plugins
+        this.registry.validateAll();
+        // Merge plugin commands into config
+        const pluginCommands = this.registry.commands();
+        this.config.commands.push(...pluginCommands);
+        // Merge plugin extensions into config
+        const pluginExtensions = this.registry.extensions();
+        this.config.extensions.push(...pluginExtensions);
+        // Inject completions command if enabled
+        if (this.config.completionsEnabled) {
+            this.config.commands.push(this.createCompletionsCommand());
+        }
+    }
+    async scanPluginDir(dir, matching) {
+        const { resolve } = await import("node:path");
+        const { readdir } = await import("node:fs/promises");
+        const resolvedDir = resolve(dir);
+        const entries = await readdir(resolvedDir, { withFileTypes: true });
+        const pluginPaths = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (matching) {
+                const glob = new Bun.Glob(matching);
+                if (!glob.match(entry.name))
+                    continue;
+            }
+            pluginPaths.push(resolve(resolvedDir, entry.name));
+        }
+        return pluginPaths;
+    }
+    async executeCommand(cmd, argv) {
+        // Parse args and flags
+        const parsed = parse(argv, cmd);
+        // Assemble toolbox
+        const toolbox = this.assembleToolbox(parsed.args, parsed.flags, cmd.name);
+        // Run onReady
+        if (this.config.onReady) {
+            await this.config.onReady(toolbox);
+        }
+        // ─── Run extension setup (topological order) ───
+        const allExtensions = [...this.config.extensions];
+        const sorted = allExtensions.length > 0 ? topoSort(allExtensions) : [];
+        const setupCompleted = [];
+        for (const ext of sorted) {
+            await this.runExtensionSetup(ext, toolbox);
+            setupCompleted.push(ext);
+        }
+        try {
+            // Build middleware chain
+            const allMiddleware = [...this.config.middleware, ...(cmd.middleware ?? [])];
+            if (allMiddleware.length > 0) {
+                await this.runMiddleware(allMiddleware, toolbox, async () => {
+                    if (cmd.run) {
+                        await cmd.run(toolbox);
+                    }
+                });
+            }
+            else if (cmd.run) {
+                await cmd.run(toolbox);
+            }
+        }
+        finally {
+            // ─── Run extension teardown (reverse order) ───
+            for (const ext of [...setupCompleted].reverse()) {
+                if (ext.teardown) {
+                    try {
+                        await ext.teardown(toolbox);
+                    }
+                    catch {
+                        // Teardown errors are swallowed to ensure all teardowns run
+                    }
+                }
+            }
+        }
+    }
+    async runExtensionSetup(ext, toolbox) {
+        const timeout = DEFAULT_SETUP_TIMEOUT;
+        const setupPromise = Promise.resolve(ext.setup(toolbox));
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new ExtensionSetupError(`Extension "${ext.name}" setup timed out after ${timeout}ms`, ext.name));
+            }, timeout);
+        });
+        await Promise.race([setupPromise, timeoutPromise]);
+    }
+    async runMiddleware(middleware, toolbox, final) {
+        let index = 0;
+        const next = async () => {
+            if (index < middleware.length) {
+                const fn = middleware[index++];
+                await fn(toolbox, next);
+            }
+            else {
+                await final();
+            }
+        };
+        await next();
+    }
+    assembleToolbox(args, flags, commandName) {
+        const cache = {};
+        const excluded = new Set(this.config.excludeModules ?? []);
+        const toolbox = {
+            args,
+            flags,
+            parameters: {
+                raw: process.argv.slice(2),
+                argv: Object.values(args).map(String),
+                command: commandName,
+            },
+            meta: {
+                version: this.config.version ?? "0.0.0",
+                commandName,
+                brand: this.config.brand,
+            },
+        };
+        // [toolbox key, package name, named export to extract]
+        // When a named export is specified, that export is used instead of the
+        // full module namespace. This is needed when the module's namespace
+        // contains raw functions whose signatures differ from the toolbox
+        // interface (e.g. @seedcli/print exports table() returning string,
+        // but PrintModule.table() returns void because it logs automatically).
+        const modules = [
+            ["print", "@seedcli/print", "print"],
+            ["prompt", "@seedcli/prompt"],
+            ["filesystem", "@seedcli/filesystem"],
+            ["system", "@seedcli/system"],
+            ["http", "@seedcli/http"],
+            ["template", "@seedcli/template"],
+            ["strings", "@seedcli/strings"],
+            ["semver", "@seedcli/semver"],
+            ["packageManager", "@seedcli/package-manager"],
+            ["config", "@seedcli/config"],
+            ["patching", "@seedcli/patching"],
+        ];
+        for (const [name, pkg, namedExport] of modules) {
+            if (excluded.has(name)) {
+                Object.defineProperty(toolbox, name, {
+                    get: () => {
+                        throw new Error(`The "${name}" module was excluded from this CLI. To use it, remove "${name}" from the .exclude() call in your CLI builder.`);
+                    },
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+            else {
+                Object.defineProperty(toolbox, name, {
+                    get: () => {
+                        if (!cache[name]) {
+                            const mod = require(pkg);
+                            cache[name] = namedExport ? mod[namedExport] : mod;
+                        }
+                        return cache[name];
+                    },
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+        }
+        return toolbox;
+    }
+    extractCompletionInfo() {
+        return {
+            brand: this.config.brand,
+            commands: this.config.commands
+                .filter((c) => c.name !== "completions" && !c.hidden)
+                .map((cmd) => ({
+                name: cmd.name,
+                description: cmd.description,
+                aliases: cmd.alias,
+                subcommands: cmd.subcommands?.map((sub) => ({
+                    name: sub.name,
+                    description: sub.description,
+                    flags: sub.flags
+                        ? Object.entries(sub.flags).map(([name, def]) => ({
+                            name,
+                            alias: def.alias,
+                            description: def.description,
+                            type: def.type,
+                            choices: def.choices,
+                        }))
+                        : undefined,
+                })),
+                flags: cmd.flags
+                    ? Object.entries(cmd.flags).map(([name, def]) => ({
+                        name,
+                        alias: def.alias,
+                        description: def.description,
+                        type: def.type,
+                        choices: def.choices,
+                    }))
+                    : undefined,
+                args: cmd.args
+                    ? Object.entries(cmd.args).map(([name, def]) => ({
+                        name,
+                        description: def.description,
+                        choices: def.choices,
+                    }))
+                    : undefined,
+            })),
+        };
+    }
+    createCompletionsCommand() {
+        return {
+            name: "completions",
+            description: "Generate shell completion scripts",
+            subcommands: [
+                {
+                    name: "install",
+                    description: "Auto-detect shell and install completions",
+                    run: async () => {
+                        const { install } = await import("@seedcli/completions");
+                        const info = this.extractCompletionInfo();
+                        const result = await install(info);
+                        console.log(`Installed ${result.shell} completions to ${result.path}`);
+                    },
+                },
+                {
+                    name: "bash",
+                    description: "Print bash completion script",
+                    run: async () => {
+                        const { bash } = await import("@seedcli/completions");
+                        console.log(bash(this.extractCompletionInfo()));
+                    },
+                },
+                {
+                    name: "zsh",
+                    description: "Print zsh completion script",
+                    run: async () => {
+                        const { zsh } = await import("@seedcli/completions");
+                        console.log(zsh(this.extractCompletionInfo()));
+                    },
+                },
+                {
+                    name: "fish",
+                    description: "Print fish completion script",
+                    run: async () => {
+                        const { fish } = await import("@seedcli/completions");
+                        console.log(fish(this.extractCompletionInfo()));
+                    },
+                },
+                {
+                    name: "powershell",
+                    description: "Print PowerShell completion script",
+                    run: async () => {
+                        const { powershell } = await import("@seedcli/completions");
+                        console.log(powershell(this.extractCompletionInfo()));
+                    },
+                },
+            ],
+        };
+    }
+    printGlobalHelp() {
+        const helpText = renderGlobalHelp(this.config.commands, {
+            brand: this.config.brand,
+            version: this.config.version,
+            ...this.config.helpOptions,
+        });
+        console.log(helpText);
+    }
+    async handleError(err) {
+        if (err instanceof ParseError) {
+            console.error(`ERROR: ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        const error = err instanceof Error ? err : new Error(String(err));
+        if (this.config.onError) {
+            const toolbox = this.assembleToolbox({}, {}, "");
+            await this.config.onError(error, toolbox);
+        }
+        else {
+            console.error(`ERROR: ${error.message}`);
+            process.exitCode = 1;
+        }
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/runtime/runtime.ts"],"names":[],"mappings":"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"}

package/dist/types/args.d.ts

@@ -0,0 +1,93 @@
+export type ArgType = "string" | "number";
+export interface ArgDef<TType extends ArgType = ArgType, TRequired extends boolean = boolean, TChoices extends readonly string[] | undefined = readonly string[] | undefined, TDefault extends string | number | undefined = string | number | undefined> {
+    type: TType;
+    required?: TRequired;
+    choices?: TChoices;
+    default?: TDefault;
+    description?: string;
+    validate?: (value: unknown) => boolean | string;
+}
+export type FlagType = "boolean" | "string" | "number" | "string[]" | "number[]";
+export interface FlagDef<TType extends FlagType = FlagType, TRequired extends boolean = boolean, TChoices extends readonly string[] | undefined = readonly string[] | undefined, TDefault = unknown> {
+    type: TType;
+    required?: TRequired;
+    choices?: TChoices;
+    default?: TDefault;
+    alias?: string;
+    description?: string;
+    hidden?: boolean;
+    validate?: (value: unknown) => boolean | string;
+}
+/**
+ * Resolve the TypeScript type for an arg definition.
+ *
+ * Priority:
+ * 1. If choices are defined → union of choices
+ * 2. Else use the declared type (string | number)
+ * 3. If required or has default → non-optional
+ * 4. Else → T | undefined
+ */
+export type ResolveArgType<T extends ArgDef> = T extends {
+    choices: readonly (infer C)[];
+} ? T extends {
+    required: true;
+} ? C : T extends {
+    default: infer _D;
+} ? C : C | undefined : T extends {
+    type: "number";
+} ? T extends {
+    required: true;
+} ? number : T extends {
+    default: infer _D;
+} ? number : number | undefined : T extends {
+    required: true;
+} ? string : T extends {
+    default: infer _D;
+} ? string : string | undefined;
+/**
+ * Resolve the TypeScript type for a flag definition.
+ */
+export type ResolveFlagType<T extends FlagDef> = T extends {
+    type: "boolean";
+} ? T extends {
+    default: infer _D;
+} ? boolean : boolean | undefined : T extends {
+    type: "string";
+} ? T extends {
+    choices: readonly (infer C)[];
+} ? T extends {
+    required: true;
+} ? C : T extends {
+    default: infer _D;
+} ? C : C | undefined : T extends {
+    required: true;
+} ? string : T extends {
+    default: infer _D;
+} ? string : string | undefined : T extends {
+    type: "number";
+} ? T extends {
+    required: true;
+} ? number : T extends {
+    default: infer _D;
+} ? number : number | undefined : T extends {
+    type: "string[]";
+} ? T extends {
+    required: true;
+} ? string[] : T extends {
+    default: infer _D;
+} ? string[] : string[] | undefined : T extends {
+    type: "number[]";
+} ? T extends {
+    required: true;
+} ? number[] : T extends {
+    default: infer _D;
+} ? number[] : number[] | undefined : unknown;
+export type InferArgs<T extends Record<string, ArgDef>> = {
+    [K in keyof T]: ResolveArgType<T[K]>;
+};
+export type InferFlags<T extends Record<string, FlagDef>> = {
+    [K in keyof T]: ResolveFlagType<T[K]>;
+};
+export declare function arg<TType extends ArgType, TRequired extends boolean = false, TChoices extends readonly string[] | undefined = undefined, TDefault extends string | number | undefined = undefined>(def: ArgDef<TType, TRequired, TChoices, TDefault>): ArgDef<TType, TRequired, TChoices, TDefault>;
+export declare function flag<TType extends FlagType, TRequired extends boolean = false, TChoices extends readonly string[] | undefined = undefined, TDefault = undefined>(def: FlagDef<TType, TRequired, TChoices, TDefault>): FlagDef<TType, TRequired, TChoices, TDefault>;
+//# sourceMappingURL=args.d.ts.map

package/dist/types/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/types/args.ts"],"names":[],"mappings":"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"}

package/dist/types/args.js

@@ -0,0 +1,9 @@
+// ─── Arg Definition Types ───
+// ─── Factory functions (type-safe constructors) ───
+export function arg(def) {
+    return def;
+}
+export function flag(def) {
+    return def;
+}
+//# sourceMappingURL=args.js.map

package/dist/types/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/types/args.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAwH/B,qDAAqD;AAErD,MAAM,UAAU,GAAG,CAKjB,GAAiD;IAClD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,IAAI,CAMnB,GAAkD;IAElD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/types/command.d.ts

@@ -0,0 +1,60 @@
+import type { ArgDef, FlagDef, InferArgs, InferFlags } from "./args.js";
+import type { Toolbox } from "./toolbox.js";
+export type Middleware = (toolbox: Toolbox<Record<string, unknown>, Record<string, unknown>>, next: () => Promise<void>) => Promise<void> | void;
+export interface CommandConfig<TArgs extends Record<string, ArgDef> = Record<string, ArgDef>, TFlags extends Record<string, FlagDef> = Record<string, FlagDef>> {
+    /** Command name (used for routing) */
+    name: string;
+    /** Human-readable description (shown in help) */
+    description?: string;
+    /** Alternative names for this command */
+    alias?: string[];
+    /** Hide from help output */
+    hidden?: boolean;
+    /** Positional argument definitions */
+    args?: TArgs;
+    /** Flag/option definitions */
+    flags?: TFlags;
+    /** Nested subcommands */
+    subcommands?: Command[];
+    /** Per-command middleware */
+    middleware?: Middleware[];
+    /** The command handler */
+    run?: (toolbox: Toolbox<InferArgs<TArgs>, InferFlags<TFlags>>) => Promise<void> | void;
+}
+/**
+ * A resolved command object (output of `command()`).
+ */
+export interface Command {
+    name: string;
+    description?: string;
+    alias?: string[];
+    hidden?: boolean;
+    args?: Record<string, ArgDef>;
+    flags?: Record<string, FlagDef>;
+    subcommands?: Command[];
+    middleware?: Middleware[];
+    run?: (toolbox: Toolbox<Record<string, unknown>, Record<string, unknown>>) => Promise<void> | void;
+}
+/**
+ * Define a command with full type inference for args and flags.
+ *
+ * ```ts
+ * const greet = command({
+ *   name: "greet",
+ *   args: {
+ *     name: arg({ type: "string", required: true }),
+ *   },
+ *   flags: {
+ *     loud: flag({ type: "boolean", default: false }),
+ *   },
+ *   run: async ({ args, flags, print }) => {
+ *     // args.name: string (inferred as required)
+ *     // flags.loud: boolean (inferred from default)
+ *     const msg = `Hello, ${args.name}!`;
+ *     print.info(flags.loud ? msg.toUpperCase() : msg);
+ *   },
+ * });
+ * ```
+ */
+export declare function command<TArgs extends Record<string, ArgDef>, TFlags extends Record<string, FlagDef>>(config: CommandConfig<TArgs, TFlags>): Command;
+//# sourceMappingURL=command.d.ts.map

package/dist/types/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/types/command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAI5C,MAAM,MAAM,UAAU,GAAG,CACxB,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAClE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KACrB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAI1B,MAAM,WAAW,aAAa,CAC7B,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7D,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAEhE,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IAEb,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,sCAAsC;IACtC,IAAI,CAAC,EAAE,KAAK,CAAC;IAEb,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,yBAAyB;IACzB,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;IAExB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IAE1B,0BAA0B;IAC1B,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACvF;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IAC1B,GAAG,CAAC,EAAE,CACL,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KAC9D,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC1B;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CACtB,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,MAAM,EAAE,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,CAE/C"}

package/dist/types/command.js

@@ -0,0 +1,26 @@
+// ─── Command Factory ───
+/**
+ * Define a command with full type inference for args and flags.
+ *
+ * ```ts
+ * const greet = command({
+ *   name: "greet",
+ *   args: {
+ *     name: arg({ type: "string", required: true }),
+ *   },
+ *   flags: {
+ *     loud: flag({ type: "boolean", default: false }),
+ *   },
+ *   run: async ({ args, flags, print }) => {
+ *     // args.name: string (inferred as required)
+ *     // flags.loud: boolean (inferred from default)
+ *     const msg = `Hello, ${args.name}!`;
+ *     print.info(flags.loud ? msg.toUpperCase() : msg);
+ *   },
+ * });
+ * ```
+ */
+export function command(config) {
+    return config;
+}
+//# sourceMappingURL=command.js.map

package/dist/types/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/types/command.ts"],"names":[],"mappings":"AA6DA,0BAA0B;AAE1B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,OAAO,CAGrB,MAAoC;IACrC,OAAO,MAA4B,CAAC;AACrC,CAAC"}