@kidd-cli/core 0.1.0

package/dist/index.js

@@ -0,0 +1,1034 @@
+import { createCliLogger } from "./lib/logger.js";
+import { i as createSpinner, r as createPromptUtils } from "./prompts-lLfUSgd6.js";
+import { n as DEFAULT_EXIT_CODE, t as createConfigClient } from "./config-BvGapuFJ.js";
+import { n as decorateContext, t as middleware } from "./middleware-D3psyhYo.js";
+import "./project-NPtYX2ZX.js";
+import { basename, extname, join, resolve } from "node:path";
+import { loadConfig } from "@kidd-cli/config/loader";
+import { attemptAsync, err, isPlainObject, isString, ok } from "@kidd-cli/utils/fp";
+import yargs from "yargs";
+import { TAG, hasTag, withTag } from "@kidd-cli/utils/tag";
+import { jsonStringify } from "@kidd-cli/utils/json";
+import { readdir } from "node:fs/promises";
+import { formatZodIssues } from "@kidd-cli/utils/validate";
+import { match as match$1 } from "ts-pattern";
+import { defineConfig } from "@kidd-cli/config";
+
+//#region src/context/error.ts
+/**
+* Create a ContextError with an exit code and optional error code.
+*
+* Used to surface user-facing CLI errors with clean messages.
+* The error carries a Symbol-based tag for reliable type-narrowing
+* via {@link isContextError}.
+*
+* @param message - Human-readable error message.
+* @param options - Optional error code and exit code overrides.
+* @returns A ContextError instance.
+*/
+function createContextError(message, options) {
+	const data = createContextErrorData(message, options);
+	const error = new Error(data.message);
+	error.name = "ContextError";
+	Object.defineProperty(error, TAG, {
+		enumerable: false,
+		value: "ContextError",
+		writable: false
+	});
+	Object.defineProperty(error, "code", {
+		enumerable: true,
+		value: data.code,
+		writable: false
+	});
+	Object.defineProperty(error, "exitCode", {
+		enumerable: true,
+		value: data.exitCode,
+		writable: false
+	});
+	return error;
+}
+/**
+* Type guard that narrows an unknown value to {@link ContextError}.
+*
+* Checks that the value is an Error instance whose `[TAG]` property
+* equals `'ContextError'`, which distinguishes CLI-layer errors from
+* unexpected exceptions.
+*
+* @param error - The value to check.
+* @returns `true` when the value is a ContextError.
+*/
+function isContextError(error) {
+	if (error instanceof Error) return hasTag(error, "ContextError");
+	return false;
+}
+function resolveExitCode(options) {
+	if (options && options.exitCode !== void 0) return options.exitCode;
+	return DEFAULT_EXIT_CODE;
+}
+function resolveCode(options) {
+	if (options && options.code !== void 0) return options.code;
+}
+function createContextErrorData(message, options) {
+	return withTag({
+		code: resolveCode(options),
+		exitCode: resolveExitCode(options),
+		message
+	}, "ContextError");
+}
+
+//#endregion
+//#region src/context/output.ts
+/**
+* Create the structured output methods for a context.
+*
+* @private
+* @param stream - The writable stream to write output to.
+* @returns An Output instance backed by the given stream.
+*/
+function createContextOutput(stream) {
+	return {
+		markdown(content) {
+			stream.write(`${content}\n`);
+		},
+		raw(content) {
+			stream.write(content);
+		},
+		table(rows, options) {
+			if (options && options.json) {
+				const [, json] = jsonStringify(rows, { pretty: true });
+				stream.write(`${json}\n`);
+				return;
+			}
+			if (rows.length === 0) return;
+			const [firstRow] = rows;
+			if (!firstRow) return;
+			writeTableToStream(stream, rows, Object.keys(firstRow));
+		},
+		write(data, options) {
+			if (options && options.json || typeof data === "object" && data !== null) {
+				const [, json] = jsonStringify(data, { pretty: true });
+				stream.write(`${json}\n`);
+			} else stream.write(`${String(data)}\n`);
+		}
+	};
+}
+/**
+* Format an unknown value as a string for table cell display.
+*
+* @private
+* @param val - The value to format.
+* @returns The stringified value, or empty string for undefined.
+*/
+function formatStringValue(val) {
+	if (val === void 0) return "";
+	return String(val);
+}
+/**
+* Create a padded header row string from column keys and widths.
+*
+* @private
+* @param options - The keys and column widths.
+* @returns A formatted header string.
+*/
+function createTableHeader(options) {
+	const { keys, widths } = options;
+	return keys.map((key, idx) => {
+		const width = widths[idx];
+		if (width === void 0) return key;
+		return key.padEnd(width);
+	}).join("  ");
+}
+/**
+* Create a padded row string from a data record, column keys, and widths.
+*
+* @private
+* @param options - The row data, keys, and column widths.
+* @returns A formatted row string.
+*/
+function createTableRow(options) {
+	const { row, keys, widths } = options;
+	return keys.map((key, idx) => {
+		const width = widths[idx];
+		const val = formatStringValue(row[key]);
+		if (width === void 0) return val;
+		return val.padEnd(width);
+	}).join("  ");
+}
+/**
+* Compute the maximum column width for each key across all rows.
+*
+* @private
+* @param rows - The data rows.
+* @param keys - The column keys.
+* @returns An array of column widths.
+*/
+function computeColumnWidths(rows, keys) {
+	return keys.map((key) => {
+		const values = rows.map((row) => formatStringValue(row[key]));
+		return Math.max(key.length, ...values.map((val) => val.length));
+	});
+}
+/**
+* Write a formatted table (header, separator, rows) to a writable stream.
+*
+* @private
+* @param stream - The writable stream.
+* @param rows - The data rows.
+* @param keys - The column keys.
+*/
+function writeTableToStream(stream, rows, keys) {
+	const widths = computeColumnWidths(rows, keys);
+	const content = [
+		createTableHeader({
+			keys,
+			widths
+		}),
+		widths.map((width) => "-".repeat(width)).join("  "),
+		...rows.map((row) => createTableRow({
+			keys,
+			row,
+			widths
+		}))
+	].join("\n");
+	stream.write(`${content}\n`);
+}
+
+//#endregion
+//#region src/context/prompts.ts
+/**
+* Create the interactive prompt methods for a context.
+*
+* @private
+* @returns A Prompts instance backed by clack.
+*/
+function createContextPrompts() {
+	const utils = createPromptUtils();
+	return {
+		async confirm(opts) {
+			return unwrapCancelSignal(utils, await utils.confirm(opts));
+		},
+		async multiselect(opts) {
+			return unwrapCancelSignal(utils, await utils.multiselect(opts));
+		},
+		async password(opts) {
+			return unwrapCancelSignal(utils, await utils.password(opts));
+		},
+		async select(opts) {
+			return unwrapCancelSignal(utils, await utils.select(opts));
+		},
+		async text(opts) {
+			return unwrapCancelSignal(utils, await utils.text(opts));
+		}
+	};
+}
+/**
+* Unwrap a prompt result that may be a cancel symbol.
+*
+* If the user cancelled (Ctrl-C), throws a ContextError. Otherwise returns
+* the typed result value.
+*
+* @private
+* @param utils - The prompt utils instance (for isCancel and cancel).
+* @param result - The raw prompt result (value or cancel symbol).
+* @returns The unwrapped typed value.
+*/
+function unwrapCancelSignal(utils, result) {
+	if (utils.isCancel(result)) {
+		utils.cancel("Operation cancelled.");
+		throw createContextError("Prompt cancelled by user", {
+			code: "PROMPT_CANCELLED",
+			exitCode: DEFAULT_EXIT_CODE
+		});
+	}
+	return result;
+}
+
+//#endregion
+//#region src/context/store.ts
+/**
+* Create an in-memory key-value store.
+*
+* @private
+* @returns A Store instance backed by a Map.
+*/
+function createMemoryStore() {
+	const map = /* @__PURE__ */ new Map();
+	return {
+		clear() {
+			map.clear();
+		},
+		delete(key) {
+			return map.delete(key);
+		},
+		get(key) {
+			return map.get(key);
+		},
+		has(key) {
+			return map.has(key);
+		},
+		set(key, value) {
+			map.set(key, value);
+		}
+	};
+}
+
+//#endregion
+//#region src/context/create-context.ts
+/**
+* Create the {@link Context} object threaded through middleware and command handlers.
+*
+* Assembles logger, spinner, output, store, prompts, and meta from
+* the provided options into a single immutable context. Each sub-system is
+* constructed via its own factory so this function remains a lean orchestrator.
+*
+* @param options - Args, config, and meta for the current invocation.
+* @returns A fully constructed Context.
+*/
+function createContext(options) {
+	const ctxLogger = options.logger ?? createCliLogger();
+	const ctxSpinner = createSpinner();
+	const ctxOutput = createContextOutput(options.output ?? process.stdout);
+	const ctxStore = createMemoryStore();
+	const ctxPrompts = createContextPrompts();
+	const ctxMeta = {
+		command: options.meta.command,
+		name: options.meta.name,
+		version: options.meta.version
+	};
+	return {
+		args: options.args,
+		config: options.config,
+		fail(message, failOptions) {
+			throw createContextError(message, failOptions);
+		},
+		logger: ctxLogger,
+		meta: ctxMeta,
+		output: ctxOutput,
+		prompts: ctxPrompts,
+		spinner: ctxSpinner,
+		store: ctxStore
+	};
+}
+
+//#endregion
+//#region src/autoloader.ts
+const VALID_EXTENSIONS = new Set([
+	".ts",
+	".js",
+	".mjs"
+]);
+const INDEX_NAME = "index";
+/**
+* Scan a directory for command files and produce a CommandMap.
+*
+* @param options - Autoload configuration (directory override, etc.).
+* @returns A promise resolving to a CommandMap built from the directory tree.
+*/
+async function autoload(options) {
+	const dir = resolveDir(options);
+	const entries = await readdir(dir, { withFileTypes: true });
+	const fileEntries = entries.filter(isCommandFile);
+	const dirEntries = entries.filter(isCommandDir);
+	const fileResults = await Promise.all(fileEntries.map(async (entry) => {
+		const cmd = await importCommand(join(dir, entry.name));
+		if (!cmd) return;
+		return [deriveCommandName(entry), cmd];
+	}));
+	const dirResults = await Promise.all(dirEntries.map((entry) => buildDirCommand(join(dir, entry.name))));
+	const validPairs = [...fileResults, ...dirResults].filter((pair) => pair !== void 0);
+	return Object.fromEntries(validPairs);
+}
+/**
+* Resolve the target directory from autoload options.
+*
+* @private
+* @param options - Optional autoload configuration.
+* @returns The resolved absolute directory path.
+*/
+function resolveDir(options) {
+	if (options && isString(options.dir)) return resolve(options.dir);
+	return resolve("./commands");
+}
+/**
+* Scan a subdirectory and assemble it as a parent command with subcommands.
+*
+* If the directory contains an `index.ts`/`index.js`, that becomes the parent
+* handler. Otherwise a handler-less group command is created that demands a
+* subcommand.
+*
+* @private
+* @param dir - Absolute path to the subdirectory.
+* @returns A tuple of [name, Command] or undefined if the directory is empty.
+*/
+async function buildDirCommand(dir) {
+	const name = basename(dir);
+	const dirEntries = await readdir(dir, { withFileTypes: true });
+	const subCommands = await buildSubCommands(dir, dirEntries);
+	const indexFile = findIndexInEntries(dirEntries);
+	if (indexFile) {
+		const parentCommand = await importCommand(join(dir, indexFile.name));
+		if (parentCommand) return [name, withTag({
+			...parentCommand,
+			commands: subCommands
+		}, "Command")];
+	}
+	if (Object.keys(subCommands).length === 0) return;
+	return [name, withTag({ commands: subCommands }, "Command")];
+}
+/**
+* Build subcommands from already-read directory entries, avoiding a redundant readdir call.
+*
+* @private
+* @param dir - Absolute path to the directory.
+* @param entries - Pre-read directory entries.
+* @returns A CommandMap built from the entries.
+*/
+async function buildSubCommands(dir, entries) {
+	const fileEntries = entries.filter(isCommandFile);
+	const dirEntries = entries.filter(isCommandDir);
+	const fileResults = await Promise.all(fileEntries.map(async (entry) => {
+		const cmd = await importCommand(join(dir, entry.name));
+		if (!cmd) return;
+		return [deriveCommandName(entry), cmd];
+	}));
+	const dirResults = await Promise.all(dirEntries.map((entry) => buildDirCommand(join(dir, entry.name))));
+	const validPairs = [...fileResults, ...dirResults].filter((pair) => pair !== void 0);
+	return Object.fromEntries(validPairs);
+}
+/**
+* Find the index file (index.ts or index.js) in pre-read directory entries.
+*
+* @private
+* @param entries - Pre-read directory entries.
+* @returns The index file's Dirent or undefined.
+*/
+function findIndexInEntries(entries) {
+	return entries.find((entry) => entry.isFile() && VALID_EXTENSIONS.has(extname(entry.name)) && basename(entry.name, extname(entry.name)) === INDEX_NAME);
+}
+/**
+* Dynamically import a file and validate that its default export is a Command.
+*
+* @private
+* @param filePath - Absolute path to the file to import.
+* @returns The Command if valid, or undefined.
+*/
+async function importCommand(filePath) {
+	const mod = await import(filePath);
+	if (isCommandExport(mod)) return mod.default;
+}
+/**
+* Check whether a module's default export is a Command object.
+*
+* ES module namespace objects have a null prototype, so isPlainObject
+* rejects them. We only need to verify the namespace is a non-null
+* object with a default export that is a plain Command object.
+*
+* @private
+* @param mod - The imported module to inspect.
+* @returns True when the module has a Command as its default export.
+*/
+function isCommandExport(mod) {
+	if (typeof mod !== "object" || mod === null) return false;
+	const def = mod["default"];
+	if (!isPlainObject(def)) return false;
+	return hasTag(def, "Command");
+}
+/**
+* Derive a command name from a directory entry by stripping its extension.
+*
+* @private
+* @param entry - The directory entry to derive the name from.
+* @returns The file name without its extension.
+*/
+function deriveCommandName(entry) {
+	return basename(entry.name, extname(entry.name));
+}
+/**
+* Predicate: entry is a command file (.ts/.js, not index, not _/. prefixed).
+*
+* @private
+* @param entry - The directory entry to check.
+* @returns True when the entry is a valid command file.
+*/
+function isCommandFile(entry) {
+	if (!entry.isFile()) return false;
+	if (entry.name.startsWith("_") || entry.name.startsWith(".")) return false;
+	if (!VALID_EXTENSIONS.has(extname(entry.name))) return false;
+	return deriveCommandName(entry) !== INDEX_NAME;
+}
+/**
+* Predicate: entry is a scannable command directory (not _/. prefixed).
+*
+* @private
+* @param entry - The directory entry to check.
+* @returns True when the entry is a valid command directory.
+*/
+function isCommandDir(entry) {
+	if (!entry.isDirectory()) return false;
+	return !entry.name.startsWith("_") && !entry.name.startsWith(".");
+}
+
+//#endregion
+//#region src/runtime/args/zod.ts
+/**
+* Type guard that checks whether a value is a zod object schema.
+*
+* @param args - The value to check.
+* @returns True when args is a ZodObject.
+*/
+function isZodSchema(args) {
+	return typeof args === "object" && args !== null && "_def" in args && typeof args._def === "object" && args._def !== null && args._def.type === "object";
+}
+/**
+* Convert an entire zod object schema into a record of yargs options.
+*
+* @param schema - The zod object schema.
+* @returns A record mapping field names to yargs option definitions.
+*/
+function zodSchemaToYargsOptions(schema) {
+	const shape = schema.shape;
+	return Object.fromEntries(Object.entries(shape).map(([key, fieldSchema]) => [key, getZodTypeOption(fieldSchema)]));
+}
+/**
+* Extract a default value from a zod definition, falling back to the provided value.
+*
+* @private
+* @param def - The zod definition to inspect.
+* @param fallback - Value to return when no default is defined.
+* @returns The resolved default value.
+*/
+function resolveDefaultValue(def, fallback) {
+	if (def.defaultValue !== void 0) return def.defaultValue;
+	return fallback;
+}
+/**
+* Unwrap a ZodOptional type, recursing into the inner type.
+*
+* @private
+* @param options - The unwrap options containing def, current type, and default value.
+* @returns Unwrapped type information.
+*/
+function unwrapOptional(options) {
+	const { def, current, defaultValue } = options;
+	if (def.innerType) return unwrapZodTypeRecursive({
+		current: def.innerType,
+		defaultValue,
+		isOptional: true
+	});
+	return {
+		defaultValue,
+		inner: current,
+		isOptional: true
+	};
+}
+/**
+* Unwrap a ZodDefault type, resolving its default value and recursing.
+*
+* @private
+* @param options - The unwrap options containing def, current type, and default value.
+* @returns Unwrapped type information with the resolved default.
+*/
+function unwrapDefault(options) {
+	const { def, current, defaultValue } = options;
+	const newDefault = resolveDefaultValue(def, defaultValue);
+	if (def.innerType) return unwrapZodTypeRecursive({
+		current: def.innerType,
+		defaultValue: newDefault,
+		isOptional: true
+	});
+	return {
+		defaultValue: newDefault,
+		inner: current,
+		isOptional: true
+	};
+}
+/**
+* Recursively unwrap optional and default wrappers from a zod type.
+*
+* @private
+* @param options - The recursive unwrap options containing current type, optionality flag, and default value.
+* @returns The fully unwrapped type information.
+*/
+function unwrapZodTypeRecursive(options) {
+	const { current, isOptional, defaultValue } = options;
+	const def = current._def;
+	if (def.type === "optional") return unwrapOptional({
+		current,
+		def,
+		defaultValue
+	});
+	if (def.type === "default") return unwrapDefault({
+		current,
+		def,
+		defaultValue
+	});
+	return {
+		defaultValue,
+		inner: current,
+		isOptional
+	};
+}
+/**
+* Unwrap a zod schema to extract its base type, optionality, and default value.
+*
+* @private
+* @param schema - The zod type to unwrap.
+* @returns The unwrapped type information.
+*/
+function unwrapZodType(schema) {
+	return unwrapZodTypeRecursive({
+		current: schema,
+		defaultValue: void 0,
+		isOptional: false
+	});
+}
+/**
+* Map a zod type name to a yargs option type string.
+*
+* @private
+* @param typeName - The zod type name (e.g. 'string', 'number').
+* @returns The corresponding yargs type.
+*/
+function resolveZodYargsType(typeName) {
+	return match$1(typeName).with("string", () => "string").with("number", () => "number").with("boolean", () => "boolean").with("array", () => "array").otherwise(() => "string");
+}
+/**
+* Build a base yargs option from a zod schema's description and default.
+*
+* @private
+* @param inner - The unwrapped zod schema instance.
+* @param defaultValue - The resolved default value.
+* @returns A partial yargs option object.
+*/
+function buildBaseOption(inner, defaultValue) {
+	const base = {};
+	const { description } = inner;
+	if (description) base.describe = description;
+	if (defaultValue !== void 0) base.default = defaultValue;
+	return base;
+}
+/**
+* Convert a single zod field schema into a complete yargs option definition.
+*
+* @private
+* @param schema - A single zod field type.
+* @returns A complete yargs option object.
+*/
+function getZodTypeOption(schema) {
+	const { inner, isOptional, defaultValue } = unwrapZodType(schema);
+	const innerDef = inner._def;
+	const base = {
+		...buildBaseOption(inner, defaultValue),
+		type: resolveZodYargsType(innerDef.type)
+	};
+	if (!isOptional) return {
+		...base,
+		demandOption: true
+	};
+	return base;
+}
+
+//#endregion
+//#region src/runtime/args/parser.ts
+/**
+* Create an args parser that cleans and validates raw parsed arguments.
+*
+* Captures the argument definition in a closure and returns an ArgsParser
+* whose `parse` method strips yargs-internal keys and validates against
+* a zod schema when one is defined.
+*
+* @param argsDef - The argument definition from the command.
+* @returns An ArgsParser with a parse method.
+*/
+function createArgsParser(argsDef) {
+	return { parse(rawArgs) {
+		return validateArgs(argsDef, cleanParsedArgs(rawArgs));
+	} };
+}
+/**
+* Strip yargs-internal keys (`_`, `$0`) and camelCase-duplicated hyphenated keys
+* from a parsed argv record, returning only user-defined arguments.
+*
+* @private
+* @param argv - Raw parsed argv from yargs.
+* @returns A cleaned record containing only user-defined arguments.
+*/
+function cleanParsedArgs(argv) {
+	return Object.fromEntries(Object.entries(argv).filter(([key]) => key !== "_" && key !== "$0" && !key.includes("-")));
+}
+/**
+* Validate parsed arguments against a zod schema when one is defined.
+*
+* If the command uses yargs-native args (no zod schema), the parsed args are
+* returned as-is. When a zod schema is present, validation is performed and
+* a Result error is returned on failure.
+*
+* @private
+* @param argsDef - The argument definition from the command.
+* @param parsedArgs - The cleaned parsed arguments.
+* @returns A Result containing validated arguments (zod-parsed when applicable).
+*/
+function validateArgs(argsDef, parsedArgs) {
+	if (!argsDef || !isZodSchema(argsDef)) return ok(parsedArgs);
+	const result = argsDef.safeParse(parsedArgs);
+	if (!result.success) return err(/* @__PURE__ */ new Error(`Invalid arguments:\n  ${formatZodIssues(result.error.issues).message}`));
+	return ok(result.data);
+}
+
+//#endregion
+//#region src/runtime/args/register.ts
+/**
+* Register argument definitions on a yargs builder.
+*
+* Accepts either a zod object schema or a record of yargs-native arg definitions
+* and wires them as yargs options on the given builder instance.
+*
+* @param builder - The yargs Argv instance to register options on.
+* @param args - Argument definitions from a Command.
+*/
+function registerCommandArgs(builder, args) {
+	if (!args) return;
+	if (isZodSchema(args)) {
+		const options = zodSchemaToYargsOptions(args);
+		for (const [key, opt] of Object.entries(options)) builder.option(key, opt);
+	} else {
+		const argsDef = args;
+		for (const [key, def] of Object.entries(argsDef)) builder.option(key, yargsArgDefToOption(def));
+	}
+}
+/**
+* Convert a yargs-native arg definition into a yargs option object.
+*
+* @private
+* @param def - The yargs arg definition.
+* @returns A yargs option object.
+*/
+function yargsArgDefToOption(def) {
+	return {
+		alias: def.alias,
+		choices: def.choices,
+		default: def.default,
+		demandOption: def.required ?? false,
+		describe: def.description,
+		type: def.type
+	};
+}
+
+//#endregion
+//#region src/runtime/register.ts
+/**
+* Type guard that checks whether a value is a Command object.
+*
+* @param value - The value to test.
+* @returns True when the value has `[TAG] === 'Command'`.
+*/
+function isCommand(value) {
+	return hasTag(value, "Command");
+}
+/**
+* Register all commands from a CommandMap on a yargs instance.
+*
+* Iterates over the command map, filters for valid Command objects,
+* and recursively registers each command (including subcommands) on
+* the provided yargs Argv instance.
+*
+* @param options - Registration options including the command map, yargs instance, and resolution ref.
+*/
+function registerCommands(options) {
+	const { instance, commands, resolved, parentPath } = options;
+	const commandEntries = Object.entries(commands).filter(([, entry]) => isCommand(entry));
+	for (const [name, entry] of commandEntries) registerResolvedCommand({
+		builder: instance,
+		cmd: entry,
+		instance,
+		name,
+		parentPath,
+		resolved
+	});
+}
+/**
+* Register a single resolved command (and its subcommands) with yargs.
+*
+* Sets up the yargs command handler, wires argument definitions, and
+* recursively registers any nested subcommands. On match, stores the
+* resolved handler and command path in the shared ref.
+*
+* @private
+* @param options - Command registration context.
+*/
+function registerResolvedCommand(options) {
+	const { instance, name, cmd, resolved, parentPath } = options;
+	const description = cmd.description ?? "";
+	instance.command(name, description, (builder) => {
+		registerCommandArgs(builder, cmd.args);
+		if (cmd.commands) {
+			const subCommands = Object.entries(cmd.commands).filter(([, entry]) => isCommand(entry));
+			for (const [subName, subEntry] of subCommands) registerResolvedCommand({
+				builder,
+				cmd: subEntry,
+				instance: builder,
+				name: subName,
+				parentPath: [...parentPath, name],
+				resolved
+			});
+			if (cmd.handler) builder.demandCommand(0);
+			else builder.demandCommand(1, "You must specify a subcommand.");
+		}
+		return builder;
+	}, () => {
+		resolved.ref = {
+			args: cmd.args,
+			commandPath: [...parentPath, name],
+			handler: cmd.handler,
+			middleware: cmd.middleware ?? []
+		};
+	});
+}
+
+//#endregion
+//#region src/runtime/runner.ts
+/**
+* Create a runner that executes root and command middleware chains.
+*
+* Root middleware wraps the command middleware chain, which in turn wraps
+* the command handler — producing a nested onion lifecycle:
+*
+* ```
+* root middleware start →
+*   command middleware start →
+*     handler
+*   command middleware end
+* root middleware end
+* ```
+*
+* @param rootMiddleware - Root-level middleware from `cli({ middleware })`.
+* @returns A Runner with an execute method.
+*/
+function createRunner(rootMiddleware) {
+	return { async execute({ ctx, handler, middleware }) {
+		const commandHandler = async (innerCtx) => {
+			await runMiddlewareChain(middleware, innerCtx, handler);
+		};
+		await runMiddlewareChain(rootMiddleware, ctx, commandHandler);
+	} };
+}
+/**
+* Execute a middleware chain followed by a final handler.
+*
+* Runs each middleware in order, passing `ctx` and a `next` callback.
+* When all middleware have called `next()`, the final handler is invoked.
+* A middleware can short-circuit by not calling `next()`.
+*
+* @private
+* @param middlewares - Ordered array of middleware to execute.
+* @param ctx - The context object threaded through middleware and handler.
+* @param finalHandler - The command handler to invoke after all middleware.
+*/
+async function runMiddlewareChain(middlewares, ctx, finalHandler) {
+	async function executeChain(index) {
+		if (index >= middlewares.length) {
+			await finalHandler(ctx);
+			return;
+		}
+		const mw = middlewares[index];
+		if (mw) await mw.handler(ctx, () => executeChain(index + 1));
+	}
+	await executeChain(0);
+}
+
+//#endregion
+//#region src/runtime/runtime.ts
+/**
+* Create a runtime that orchestrates config loading and middleware execution.
+*
+* Loads config up front, then captures it in a closure alongside a runner.
+* The returned `runtime.execute` method handles arg parsing, context creation,
+* and middleware chain execution for each command invocation.
+*
+* @param options - Runtime configuration including name, version, config, and middleware.
+* @returns An AsyncResult containing the runtime or an error.
+*/
+async function createRuntime(options) {
+	const config = await resolveConfig(options.config, options.name);
+	const runner = createRunner(options.middleware ?? []);
+	return ok({ async execute(command) {
+		const [argsError, validatedArgs] = createArgsParser(command.args).parse(command.rawArgs);
+		if (argsError) return err(argsError);
+		const ctx = createContext({
+			args: validatedArgs,
+			config,
+			meta: {
+				command: command.commandPath,
+				name: options.name,
+				version: options.version
+			}
+		});
+		const finalHandler = command.handler ?? (async () => {});
+		const [execError] = await attemptAsync(() => runner.execute({
+			ctx,
+			handler: finalHandler,
+			middleware: command.middleware
+		}));
+		if (execError) return err(execError);
+		return ok();
+	} });
+}
+/**
+* Load and validate a config file via the config client.
+*
+* Returns the validated config record or an empty object when no config
+* options are provided or when loading fails.
+*
+* @private
+* @param configOptions - Config loading options with schema and optional name override.
+* @param defaultName - Fallback config file name derived from the CLI name.
+* @returns The loaded config record or an empty object.
+*/
+async function resolveConfig(configOptions, defaultName) {
+	if (!configOptions || !configOptions.schema) return {};
+	const [configError, configResult] = await createConfigClient({
+		name: configOptions.name ?? defaultName,
+		schema: configOptions.schema
+	}).load();
+	if (configError || !configResult) return {};
+	return configResult.config;
+}
+
+//#endregion
+//#region src/cli.ts
+const ARGV_SLICE_START = 2;
+/**
+* Bootstrap and run the CLI application.
+*
+* Parses argv, resolves the matched command, loads config, runs the
+* middleware chain, and invokes the command handler.
+*
+* @param options - CLI configuration including name, version, commands, and middleware.
+*/
+async function cli(options) {
+	const logger = createCliLogger();
+	const [uncaughtError, result] = await attemptAsync(async () => {
+		const program = yargs(process.argv.slice(ARGV_SLICE_START)).scriptName(options.name).version(options.version).strict().help().option("cwd", {
+			describe: "Set the working directory",
+			global: true,
+			type: "string"
+		});
+		if (options.description) program.usage(options.description);
+		const resolved = { ref: void 0 };
+		const commands = await resolveCommands(options.commands);
+		if (commands) {
+			registerCommands({
+				commands,
+				instance: program,
+				parentPath: [],
+				resolved
+			});
+			program.demandCommand(1, "You must specify a command.");
+		}
+		const argv = await program.parseAsync();
+		applyCwd(argv);
+		if (!resolved.ref) return;
+		const [runtimeError, runtime] = await createRuntime({
+			config: options.config,
+			middleware: options.middleware,
+			name: options.name,
+			version: options.version
+		});
+		if (runtimeError) return runtimeError;
+		const [executeError] = await runtime.execute({
+			args: resolved.ref.args,
+			commandPath: resolved.ref.commandPath,
+			handler: resolved.ref.handler,
+			middleware: resolved.ref.middleware,
+			rawArgs: argv
+		});
+		return executeError;
+	});
+	if (uncaughtError) {
+		exitOnError(uncaughtError, logger);
+		return;
+	}
+	if (result) exitOnError(result, logger);
+}
+/**
+* Resolve the commands option to a CommandMap.
+*
+* Accepts a directory string (triggers autoload), a static CommandMap,
+* a Promise<CommandMap> (from autoload() called at the call site),
+* or undefined (loads `kidd.config.ts` and autoloads from its `commands` field,
+* falling back to `'./commands'`).
+*
+* @private
+* @param commands - The commands option from CliOptions.
+* @returns A CommandMap or undefined.
+*/
+async function resolveCommands(commands) {
+	if (isString(commands)) return autoload({ dir: commands });
+	if (commands instanceof Promise) return commands;
+	if (isPlainObject(commands)) return commands;
+	return resolveCommandsFromConfig();
+}
+/**
+* Load `kidd.config.ts` and autoload commands from its `commands` field.
+*
+* Falls back to `'./commands'` when the config file is missing, fails to load,
+* or does not specify a `commands` field.
+*
+* @private
+* @returns A CommandMap autoloaded from the configured commands directory.
+*/
+async function resolveCommandsFromConfig() {
+	const DEFAULT_COMMANDS_DIR = "./commands";
+	const [configError, configResult] = await loadConfig();
+	if (configError || !configResult) return autoload({ dir: DEFAULT_COMMANDS_DIR });
+	return autoload({ dir: configResult.config.commands ?? DEFAULT_COMMANDS_DIR });
+}
+/**
+* Change the process working directory when `--cwd` is provided.
+*
+* Resolves the value to an absolute path and calls `process.chdir()` so
+* that all downstream `process.cwd()` calls reflect the override.
+*
+* @private
+* @param argv - The parsed argv record from yargs.
+*/
+function applyCwd(argv) {
+	if (isString(argv.cwd)) process.chdir(resolve(argv.cwd));
+}
+/**
+* Handle a CLI error by logging the message and exiting with the appropriate code.
+*
+* ContextErrors carry a custom exit code; all other errors exit with code 1.
+*
+* @private
+* @param error - The caught error value.
+* @param logger - Logger with an error method for output.
+*/
+function exitOnError(error, logger) {
+	if (isContextError(error)) {
+		logger.error(error.message);
+		process.exit(error.exitCode);
+	} else if (error instanceof Error) {
+		logger.error(error.message);
+		process.exit(DEFAULT_EXIT_CODE);
+	} else {
+		logger.error(String(error));
+		process.exit(DEFAULT_EXIT_CODE);
+	}
+}
+
+//#endregion
+//#region src/command.ts
+/**
+* Define a CLI command with typed args, config, and handler.
+*
+* @param def - Command definition including description, args schema, and handler.
+* @returns A resolved Command object for registration in the command map.
+*/
+function command(def) {
+	return withTag({ ...def }, "Command");
+}
+
+//#endregion
+export { autoload, cli, command, decorateContext, defineConfig, middleware };
+//# sourceMappingURL=index.js.map