@kidd-cli/core 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,17 +1,20 @@
+import "./tally-ioa20iGw.js";
 import { createCliLogger } from "./lib/logger.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 { n as decorateContext, t as middleware } from "./middleware-BewRXb2G.js";
+import "./project-CoWHMVc8.js";
+import { t as createConfigClient } from "./config-BiEi8RG2.js";
 import { basename, extname, join, resolve } from "node:path";
 import { loadConfig } from "@kidd-cli/config/loader";
 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 pc from "picocolors";
+import { match as match$1 } from "ts-pattern";
 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
 /**
@@ -75,40 +78,26 @@ function createContextErrorData(message, options) {
 	}, "ContextError");
 }
 //#endregion
-//#region src/context/output.ts
+//#region src/context/format.ts
 /**
-* Create the structured output methods for a context.
+* Create the pure string formatter methods for a context.
 *
 * @private
-* @param stream - The writable stream to write output to.
-* @returns An Output instance backed by the given stream.
+* @returns A Format instance with json and table formatters.
 */
-function createContextOutput(stream) {
-	return {
-		markdown(content) {
-			stream.write(`${content}\n`);
-		},
-		raw(content) {
-			stream.write(content);
+function createContextFormat() {
+	return Object.freeze({
+		json(data) {
+			const [, json] = jsonStringify(data, { pretty: true });
+			return `${json}\n`;
 		},
-		table(rows, options) {
-			if (options && options.json) {
-				const [, json] = jsonStringify(rows, { pretty: true });
-				stream.write(`${json}\n`);
-				return;
-			}
-			if (rows.length === 0) return;
+		table(rows) {
+			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`);
+			if (!firstRow) return "";
+			return formatTable(rows, Object.keys(firstRow));
 		}
-	};
+	});
 }
 /**
 * Format an unknown value as a string for table cell display.
@@ -167,16 +156,16 @@ function computeColumnWidths(rows, keys) {
 	});
 }
 /**
-* Write a formatted table (header, separator, rows) to a writable stream.
+* Format a table (header, separator, rows) as a string.
 *
 * @private
-* @param stream - The writable stream.
 * @param rows - The data rows.
 * @param keys - The column keys.
+* @returns The formatted table string.
 */
-function writeTableToStream(stream, rows, keys) {
+function formatTable(rows, keys) {
 	const widths = computeColumnWidths(rows, keys);
-	const content = [
+	return `${[
 		createTableHeader({
 			keys,
 			widths
@@ -187,8 +176,7 @@ function writeTableToStream(stream, rows, keys) {
 			row,
 			widths
 		}))
-	].join("\n");
-	stream.write(`${content}\n`);
+	].join("\n")}\n`;
 }
 //#endregion
 //#region src/context/prompts.ts
@@ -269,7 +257,7 @@ function createMemoryStore() {
 /**
 * Create the {@link Context} object threaded through middleware and command handlers.
 *
-* Assembles logger, spinner, output, store, prompts, and meta from
+* Assembles logger, spinner, format, 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.
 *
@@ -279,7 +267,7 @@ function createMemoryStore() {
 function createContext(options) {
 	const ctxLogger = options.logger ?? createCliLogger();
 	const ctxSpinner = clack.spinner();
-	const ctxOutput = createContextOutput(options.output ?? process.stdout);
+	const ctxFormat = createContextFormat();
 	const ctxStore = createMemoryStore();
 	const ctxPrompts = createContextPrompts();
 	const ctxMeta = {
@@ -289,13 +277,14 @@ function createContext(options) {
 	};
 	return {
 		args: options.args,
+		colors: Object.freeze({ ...pc }),
 		config: options.config,
 		fail(message, failOptions) {
 			throw createContextError(message, failOptions);
 		},
+		format: ctxFormat,
 		logger: ctxLogger,
 		meta: ctxMeta,
-		output: ctxOutput,
 		prompts: ctxPrompts,
 		spinner: ctxSpinner,
 		store: ctxStore
@@ -317,17 +306,7 @@ const INDEX_NAME = "index";
 */
 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);
+	return buildCommandMapFromEntries(dir, await readdir(dir, { withFileTypes: true }));
 }
 /**
 * Resolve the target directory from autoload options.
@@ -354,7 +333,7 @@ function resolveDir(options) {
 async function buildDirCommand(dir) {
 	const name = basename(dir);
 	const dirEntries = await readdir(dir, { withFileTypes: true });
-	const subCommands = await buildSubCommands(dir, dirEntries);
+	const subCommands = await buildCommandMapFromEntries(dir, dirEntries);
 	const indexFile = findIndexInEntries(dirEntries);
 	if (indexFile) {
 		const parentCommand = await importCommand(join(dir, indexFile.name));
@@ -367,14 +346,17 @@ async function buildDirCommand(dir) {
 	return [name, withTag({ commands: subCommands }, "Command")];
 }
 /**
-* Build subcommands from already-read directory entries, avoiding a redundant readdir call.
+* Build a CommandMap from pre-read directory entries.
+*
+* Shared by both `autoload` and `buildDirCommand` to avoid duplicating
+* the file/dir fan-out and result-filtering logic.
 *
 * @private
-* @param dir - Absolute path to the directory.
-* @param entries - Pre-read directory entries.
+* @param dir - Absolute path to the directory the entries belong to.
+* @param entries - Pre-read directory entries for that directory.
 * @returns A CommandMap built from the entries.
 */
-async function buildSubCommands(dir, entries) {
+async function buildCommandMapFromEntries(dir, entries) {
 	const fileEntries = entries.filter(isCommandFile);
 	const dirEntries = entries.filter(isCommandDir);
 	const fileResults = await Promise.all(fileEntries.map(async (entry) => {
@@ -460,6 +442,46 @@ function isCommandDir(entry) {
 	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
 /**
 * Type guard that checks whether a value is a zod object schema.
@@ -700,6 +722,44 @@ function yargsArgDefToOption(def) {
 	};
 }
 //#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
 /**
 * Type guard that checks whether a value is a Command object.
@@ -714,22 +774,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 { instance, commands, resolved, parentPath, order, errorRef } = options;
 	const commandEntries = Object.entries(commands).filter((pair) => isCommand(pair[1]));
-	for (const [name, entry] of commandEntries) registerResolvedCommand({
+	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.
@@ -742,20 +816,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((pair) => isCommand(pair[1]));
-			for (const [subName, subEntry] of subCommands) registerResolvedCommand({
+			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.");
 		}
@@ -890,31 +978,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({
@@ -932,23 +1035,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.
@@ -962,8 +1106,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.
@@ -978,6 +1122,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.
@@ -1001,21 +1186,6 @@ function exitOnError(error, logger) {
 	process.exit(info.exitCode);
 }
 //#endregion
-//#region src/command.ts
-/**
-* 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.
-*
-* @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 withTag({ ...def }, "Command");
-}
-//#endregion
 //#region src/compose.ts
 /**
 * Middleware combinator that merges multiple middleware into one.