@kidd-cli/core 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,11 +1,12 @@
 import { createCliLogger } from "./lib/logger.js";
-import { n as DEFAULT_EXIT_CODE, t as createConfigClient } from "./config-Db_sjFU-.js";
-import { n as decorateContext, t as middleware } from "./middleware-BFBKNSPQ.js";
-import "./project-DuXgjaa_.js";
+import { n as decorateContext, t as middleware } from "./middleware-BWnPSRWR.js";
+import "./project-D0g84bZY.js";
+import { t as createConfigClient } from "./config-D8e5qxLp.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 { P, attemptAsync, err, isPlainObject, isString, match, ok } from "@kidd-cli/utils/fp";
 import yargs from "yargs";
+import { z } from "zod";
 import * as clack from "@clack/prompts";
 import { TAG, hasTag, withTag } from "@kidd-cli/utils/tag";
 import { jsonStringify } from "@kidd-cli/utils/json";
@@ -13,7 +14,6 @@ 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.
@@ -63,7 +63,7 @@ function isContextError(error) {
 }
 function resolveExitCode(options) {
 	if (options && options.exitCode !== void 0) return options.exitCode;
-	return DEFAULT_EXIT_CODE;
+	return 1;
 }
 function resolveCode(options) {
 	if (options && options.code !== void 0) return options.code;
@@ -75,7 +75,6 @@ function createContextErrorData(message, options) {
 		message
 	}, "ContextError");
 }
-
 //#endregion
 //#region src/context/output.ts
 /**
@@ -192,7 +191,6 @@ function writeTableToStream(stream, rows, keys) {
 	].join("\n");
 	stream.write(`${content}\n`);
 }
-
 //#endregion
 //#region src/context/prompts.ts
 /**
@@ -234,12 +232,11 @@ function unwrapCancelSignal(result) {
 		clack.cancel("Operation cancelled.");
 		throw createContextError("Prompt cancelled by user", {
 			code: "PROMPT_CANCELLED",
-			exitCode: DEFAULT_EXIT_CODE
+			exitCode: 1
 		});
 	}
 	return result;
 }
-
 //#endregion
 //#region src/context/store.ts
 /**
@@ -268,7 +265,6 @@ function createMemoryStore() {
 		}
 	};
 }
-
 //#endregion
 //#region src/context/create-context.ts
 /**
@@ -306,7 +302,6 @@ function createContext(options) {
 		store: ctxStore
 	};
 }
-
 //#endregion
 //#region src/autoloader.ts
 const VALID_EXTENSIONS = new Set([
@@ -426,7 +421,8 @@ async function importCommand(filePath) {
 */
 function isCommandExport(mod) {
 	if (typeof mod !== "object" || mod === null) return false;
-	const def = mod["default"];
+	if (!("default" in mod)) return false;
+	const def = mod.default;
 	if (!isPlainObject(def)) return false;
 	return hasTag(def, "Command");
 }
@@ -464,7 +460,46 @@ function isCommandDir(entry) {
 	if (!entry.isDirectory()) return false;
 	return !entry.name.startsWith("_") && !entry.name.startsWith(".");
 }
-
+//#endregion
+//#region src/command.ts
+/**
+* Check whether a value is a structured {@link CommandsConfig} object.
+*
+* Discriminates from a plain `CommandMap` by checking for the `order` (array)
+* or `path` (string) keys — neither can appear on a valid `CommandMap` whose
+* values are tagged `Command` objects.
+*
+* @param value - The value to test.
+* @returns `true` when `value` is a `CommandsConfig`.
+*/
+function isCommandsConfig(value) {
+	if (typeof value !== "object" || value === null || value instanceof Promise) return false;
+	return "order" in value && Array.isArray(value.order) || "path" in value && typeof value.path === "string";
+}
+/**
+* Define a CLI command with typed args, config, and handler.
+*
+* The `const TMiddleware` generic preserves the middleware tuple as a literal type,
+* enabling TypeScript to extract and intersect `Variables` from each middleware
+* element onto the handler's `ctx` type.
+*
+* When `def.commands` is a structured {@link CommandsConfig}, the factory
+* normalizes it into flat `commands` and `order` fields on the output
+* `Command` object so downstream consumers never need to handle the grouped form.
+*
+* @param def - Command definition including description, args schema, middleware, and handler.
+* @returns A resolved Command object for registration in the command map.
+*/
+function command(def) {
+	return match(def.commands).when(isCommandsConfig, (cfg) => {
+		const { order, commands: innerCommands } = cfg;
+		return withTag({
+			...def,
+			commands: innerCommands,
+			order
+		}, "Command");
+	}).otherwise(() => withTag({ ...def }, "Command"));
+}
 //#endregion
 //#region src/runtime/args/zod.ts
 /**
@@ -624,7 +659,6 @@ function getZodTypeOption(schema) {
 	};
 	return base;
 }
-
 //#endregion
 //#region src/runtime/args/parser.ts
 /**
@@ -671,7 +705,6 @@ function validateArgs(argsDef, 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
 /**
@@ -688,10 +721,7 @@ function registerCommandArgs(builder, args) {
 	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));
-	}
+	} else for (const [key, def] of Object.entries(args)) builder.option(key, yargsArgDefToOption(def));
 }
 /**
 * Convert a yargs-native arg definition into a yargs option object.
@@ -710,7 +740,44 @@ function yargsArgDefToOption(def) {
 		type: def.type
 	};
 }
-
+//#endregion
+//#region src/runtime/sort-commands.ts
+/**
+* Validate that every name in the order array exists in the provided command names.
+*
+* @param params - The order array and available command names to validate against.
+* @returns A Result tuple — `[null, void]` on success or `[Error, null]` on failure.
+*/
+function validateCommandOrder(params) {
+	const { order, commandNames } = params;
+	const seen = /* @__PURE__ */ new Set();
+	const duplicates = order.filter((name) => {
+		if (seen.has(name)) return true;
+		seen.add(name);
+		return false;
+	});
+	if (duplicates.length > 0) return err(`Invalid command order: duplicate command(s) ${[...new Set(duplicates)].map((n) => `"${n}"`).join(", ")}`);
+	const nameSet = new Set(commandNames);
+	const invalid = order.filter((name) => !nameSet.has(name));
+	if (invalid.length > 0) return err(`Invalid command order: unknown command(s) ${invalid.map((n) => `"${n}"`).join(", ")}`);
+	return ok();
+}
+/**
+* Sort command entries with ordered names first (in specified order),
+* remaining names alphabetically.
+*
+* @param params - The command entries and optional order array.
+* @returns Sorted array of `[name, Command]` entries.
+*/
+function sortCommandEntries(params) {
+	const { entries, order } = params;
+	if (!order || order.length === 0) return [...entries].toSorted(([a], [b]) => a.localeCompare(b));
+	const entryMap = new Map(entries);
+	const ordered = order.filter((name) => entryMap.has(name)).map((name) => [name, entryMap.get(name)]);
+	const orderedSet = new Set(order);
+	const remaining = entries.filter(([name]) => !orderedSet.has(name)).toSorted(([a], [b]) => a.localeCompare(b));
+	return [...ordered, ...remaining];
+}
 //#endregion
 //#region src/runtime/register.ts
 /**
@@ -726,22 +793,36 @@ function isCommand(value) {
 * 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.
+* validates the order array, sorts entries, 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({
+	const { instance, commands, resolved, parentPath, order, errorRef } = options;
+	const commandEntries = Object.entries(commands).filter((pair) => isCommand(pair[1]));
+	if (order && order.length > 0) {
+		const [validationError] = validateCommandOrder({
+			commandNames: commandEntries.map(([name]) => name),
+			order
+		});
+		if (validationError && errorRef) {
+			errorRef.error = validationError;
+			return;
+		}
+	}
+	sortCommandEntries({
+		entries: commandEntries,
+		order
+	}).map(([name, entry]) => registerResolvedCommand({
 		builder: instance,
 		cmd: entry,
+		errorRef,
 		instance,
 		name,
 		parentPath,
 		resolved
-	});
+	}));
 }
 /**
 * Register a single resolved command (and its subcommands) with yargs.
@@ -754,20 +835,34 @@ function registerCommands(options) {
 * @param options - Command registration context.
 */
 function registerResolvedCommand(options) {
-	const { instance, name, cmd, resolved, parentPath } = options;
+	const { instance, name, cmd, resolved, parentPath, errorRef } = 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({
+			const subCommands = Object.entries(cmd.commands).filter((pair) => isCommand(pair[1]));
+			if (cmd.order && cmd.order.length > 0) {
+				const [validationError] = validateCommandOrder({
+					commandNames: subCommands.map(([n]) => n),
+					order: cmd.order
+				});
+				if (validationError && errorRef) {
+					errorRef.error = validationError;
+					return builder;
+				}
+			}
+			sortCommandEntries({
+				entries: subCommands,
+				order: cmd.order
+			}).map(([subName, subEntry]) => registerResolvedCommand({
 				builder,
 				cmd: subEntry,
+				errorRef,
 				instance: builder,
 				name: subName,
 				parentPath: [...parentPath, name],
 				resolved
-			});
+			}));
 			if (cmd.handler) builder.demandCommand(0);
 			else builder.demandCommand(1, "You must specify a subcommand.");
 		}
@@ -781,7 +876,6 @@ function registerResolvedCommand(options) {
 		};
 	});
 }
-
 //#endregion
 //#region src/runtime/runner.ts
 /**
@@ -832,7 +926,6 @@ async function runMiddlewareChain(middlewares, ctx, finalHandler) {
 	}
 	await executeChain(0);
 }
-
 //#endregion
 //#region src/runtime/runtime.ts
 /**
@@ -855,7 +948,7 @@ async function createRuntime(options) {
 			args: validatedArgs,
 			config,
 			meta: {
-				command: command.commandPath,
+				command: [...command.commandPath],
 				name: options.name,
 				version: options.version
 			}
@@ -890,7 +983,6 @@ async function resolveConfig(configOptions, defaultName) {
 	if (configError || !configResult) return {};
 	return configResult.config;
 }
-
 //#endregion
 //#region src/cli.ts
 const ARGV_SLICE_START = 2;
@@ -905,31 +997,46 @@ const ARGV_SLICE_START = 2;
 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", {
+		const [versionError, version] = resolveVersion(options.version);
+		if (versionError) return versionError;
+		const program = yargs(process.argv.slice(ARGV_SLICE_START)).scriptName(options.name).version(version).strict().help().option("cwd", {
 			describe: "Set the working directory",
 			global: true,
 			type: "string"
 		});
 		if (options.description) program.usage(options.description);
+		const footer = extractFooter(options.help);
+		if (footer) program.epilogue(footer);
 		const resolved = { ref: void 0 };
-		const commands = await resolveCommands(options.commands);
-		if (commands) {
+		const errorRef = { error: void 0 };
+		const resolvedCmds = await resolveCommands(options.commands);
+		if (resolvedCmds) {
 			registerCommands({
-				commands,
+				commands: resolvedCmds.commands,
+				errorRef,
 				instance: program,
+				order: resolvedCmds.order,
 				parentPath: [],
 				resolved
 			});
-			program.demandCommand(1, "You must specify a command.");
+			if (errorRef.error) return errorRef.error;
 		}
 		const argv = await program.parseAsync();
 		applyCwd(argv);
-		if (!resolved.ref) return;
+		if (!resolved.ref) {
+			showNoCommandHelp({
+				argv,
+				commands: resolvedCmds,
+				help: options.help,
+				program
+			});
+			return;
+		}
 		const [runtimeError, runtime] = await createRuntime({
 			config: options.config,
 			middleware: options.middleware,
 			name: options.name,
-			version: options.version
+			version
 		});
 		if (runtimeError) return runtimeError;
 		const [executeError] = await runtime.execute({
@@ -947,23 +1054,64 @@ async function cli(options) {
 	}
 	if (result) exitOnError(result, logger);
 }
+const VERSION_ERROR = /* @__PURE__ */ new Error("No CLI version available. Either pass `version` to cli() or build with the kidd bundler.");
+const VersionSchema = z.string().trim().min(1);
+/**
+* Resolve the CLI version from an explicit value or the compile-time constant.
+*
+* Resolution order:
+* 1. Explicit version string passed to `cli()`
+* 2. `__KIDD_VERSION__` injected by the kidd bundler at build time
+*
+* Returns an error when neither source provides a non-empty version.
+*
+* @private
+* @param explicit - The version string from `CliOptions.version`, if provided.
+* @returns A Result tuple with the resolved version string or an Error.
+*/
+function resolveVersion(explicit) {
+	if (explicit !== void 0) {
+		const parsed = VersionSchema.safeParse(explicit);
+		if (parsed.success) return ok(parsed.data);
+		return err(VERSION_ERROR);
+	}
+	if (typeof __KIDD_VERSION__ === "string") {
+		const parsed = VersionSchema.safeParse(__KIDD_VERSION__);
+		if (parsed.success) return ok(parsed.data);
+	}
+	return err(VERSION_ERROR);
+}
 /**
-* Resolve the commands option to a CommandMap.
+* Resolve the commands option to a {@link ResolvedCommands}.
 *
 * Accepts a directory string (triggers autoload), a static CommandMap,
-* a Promise<CommandMap> (from autoload() called at the call site),
+* a Promise<CommandMap>, a structured {@link CommandsConfig},
 * 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.
+* @returns Resolved commands with optional order, 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();
+	return match(commands).when(isString, async (dir) => ({ commands: await autoload({ dir }) })).with(P.instanceOf(Promise), async (p) => ({ commands: await p })).when(isCommandsConfig, (cfg) => resolveCommandsConfig(cfg)).when(isPlainObject, (cmds) => ({ commands: cmds })).otherwise(() => resolveCommandsFromConfig());
+}
+/**
+* Resolve a structured {@link CommandsConfig} into flat commands and order.
+*
+* When `path` is provided, autoloads from that directory. Otherwise uses the
+* inline `commands` map (resolved if it is a promise).
+*
+* @private
+* @param config - The structured commands configuration.
+* @returns Resolved commands with optional order.
+*/
+async function resolveCommandsConfig(config) {
+	const { order, path, commands: innerCommands } = config;
+	return {
+		commands: await match(innerCommands).when(() => isString(path), async () => autoload({ dir: path })).with(P.instanceOf(Promise), async (p) => p).when(isPlainObject, (cmds) => cmds).otherwise(() => ({})),
+		order
+	};
 }
 /**
 * Load `kidd.config.ts` and autoload commands from its `commands` field.
@@ -977,8 +1125,8 @@ async function resolveCommands(commands) {
 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 });
+	if (configError || !configResult) return { commands: await autoload({ dir: DEFAULT_COMMANDS_DIR }) };
+	return { commands: await autoload({ dir: configResult.config.commands ?? DEFAULT_COMMANDS_DIR }) };
 }
 /**
 * Change the process working directory when `--cwd` is provided.
@@ -993,6 +1141,47 @@ function applyCwd(argv) {
 	if (isString(argv.cwd)) process.chdir(resolve(argv.cwd));
 }
 /**
+* Show help output when no command was matched.
+*
+* Prints the header (if configured) above the yargs help text. Skipped when
+* `--help` was explicitly passed, since yargs already handles that case.
+*
+* @private
+* @param params - The argv, commands, help options, and yargs program instance.
+*/
+function showNoCommandHelp({ argv, commands, help, program }) {
+	if (!commands) return;
+	if (argv.help) return;
+	const header = extractHeader(help);
+	if (header) {
+		console.log(header);
+		console.log();
+	}
+	program.showHelp("log");
+}
+/**
+* Extract the header string from help options.
+*
+* @private
+* @param help - The help options, possibly undefined.
+* @returns The header string or undefined.
+*/
+function extractHeader(help) {
+	if (!help) return;
+	return help.header;
+}
+/**
+* Extract the footer string from help options.
+*
+* @private
+* @param help - The help options, possibly undefined.
+* @returns The footer string or undefined.
+*/
+function extractFooter(help) {
+	if (!help) return;
+	return help.footer;
+}
+/**
 * 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.
@@ -1002,34 +1191,69 @@ function applyCwd(argv) {
 * @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);
-	}
+	const info = match(error).when(isContextError, (e) => ({
+		exitCode: e.exitCode,
+		message: e.message
+	})).with(P.instanceOf(Error), (e) => ({
+		exitCode: 1,
+		message: e.message
+	})).otherwise((e) => ({
+		exitCode: 1,
+		message: String(e)
+	}));
+	logger.error(info.message);
+	process.exit(info.exitCode);
 }
-
 //#endregion
-//#region src/command.ts
+//#region src/compose.ts
 /**
-* Define a CLI command with typed args, config, and handler.
+* Middleware combinator that merges multiple middleware into one.
 *
-* The `const TMiddleware` generic preserves the middleware tuple as a literal type,
-* enabling TypeScript to extract and intersect `Variables` from each middleware
-* element onto the handler's `ctx` type.
+* @module
+*/
+/**
+* Compose multiple middleware into a single middleware.
 *
-* @param def - Command definition including description, args schema, middleware, and handler.
-* @returns A resolved Command object for registration in the command map.
+* Executes each middleware in order, threading `next()` through the chain.
+* The final `next()` call from the last composed middleware continues to
+* the downstream middleware or command handler.
+*
+* The returned middleware's type merges all `Variables` from the input tuple,
+* so downstream handlers see the combined context.
+*
+* @param middlewares - An ordered tuple of middleware to compose.
+* @returns A single Middleware whose Variables is the intersection of all input Variables.
+*
+* @example
+* ```ts
+* const combined = compose([auth({ strategies: [auth.env()] }), auth.require()])
+* ```
 */
-function command(def) {
-	return withTag({ ...def }, "Command");
+function compose(middlewares) {
+	return middleware((ctx, next) => executeChain(middlewares, 0, ctx, next));
+}
+/**
+* Recursively execute middleware in order, calling next() after the last one.
+*
+* @private
+* @param middlewares - The middleware array.
+* @param index - Current position in the array.
+* @param ctx - The context object.
+* @param next - The downstream next function.
+*/
+async function executeChain(middlewares, index, ctx, next) {
+	if (index >= middlewares.length) {
+		await next();
+		return;
+	}
+	const mw = middlewares[index];
+	if (mw === void 0) {
+		await next();
+		return;
+	}
+	await mw.handler(ctx, () => executeChain(middlewares, index + 1, ctx, next));
 }
-
 //#endregion
-export { autoload, cli, command, decorateContext, defineConfig, middleware };
+export { autoload, cli, command, compose, decorateContext, defineConfig, middleware };
+
 //# sourceMappingURL=index.js.map