@kidd-cli/core 0.3.0 → 0.4.0

package/README.md

@@ -28,6 +28,7 @@ await cli({
   name: 'my-app',
   version: '1.0.0',
   commands: { greet },
+  help: { header: 'my-app - a friendly CLI' },
 })
 ```
 
@@ -45,9 +46,7 @@ cli({
   commands: { deploy, migrate },
   middleware: [requireAuth()],
   config: { schema: MyConfigSchema },
-  credentials: {
-    apiKey: { env: 'API_KEY', required: true },
-  },
+  help: { header: 'my-app - deploy and migrate with ease' },
 })
 ```
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { a as CommandDef, c as Middleware, d as Context, i as Command, l as MiddlewareEnv, n as AutoloadOptions, o as CommandMap, r as CliOptions, s as InferVariables, t as ArgsDef, u as MiddlewareFn } from "./types-CTvrsrnD.js";
-import { defineConfig } from "@kidd-cli/config";
+import { a as Command, c as CommandsConfig, d as MiddlewareEnv, f as MiddlewareFn, i as CliOptions, l as InferVariables, n as AutoloadOptions, o as CommandDef, p as Context, r as CliHelpOptions, s as CommandMap, t as ArgsDef, u as Middleware } from "./types-U73X_oQ_.js";
 import { z } from "zod";
+import { defineConfig } from "@kidd-cli/config";
 
 //#region src/cli.d.ts
 /**
@@ -21,6 +21,10 @@ declare function cli<TSchema extends z.ZodType = z.ZodType>(options: CliOptions<
 * 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.
 */
@@ -113,5 +117,5 @@ declare function decorateContext<TKey extends string, TValue>(ctx: Context, key:
 */
 declare function middleware<TEnv extends MiddlewareEnv = MiddlewareEnv>(handler: MiddlewareFn<TEnv>): Middleware<TEnv>;
 //#endregion
-export { type Command, type Context, type MiddlewareEnv, autoload, cli, command, compose, decorateContext, defineConfig, middleware };
+export { type CliHelpOptions, type Command, type CommandsConfig, type Context, type MiddlewareEnv, autoload, cli, command, compose, decorateContext, defineConfig, middleware };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/cli.ts","../src/command.ts","../src/compose.ts","../src/autoloader.ts","../src/context/decorate.ts","../src/middleware.ts"],"mappings":";;;;;;;;AAyBA;;;;;iBAAsB,GAAA,iBAAoB,CAAA,CAAE,OAAA,GAAU,CAAA,CAAE,OAAA,CAAA,CACtD,OAAA,EAAS,UAAA,CAAW,OAAA,IACnB,OAAA;;;;;;;AAFH;;;;;;iBCLgB,OAAA,kBACG,OAAA,GAAU,OAAA,kBACX,MAAA,oBAA0B,MAAA,sDACP,UAAA,CAAW,aAAA,eACnC,UAAA,CAAW,aAAA,IAAA,CACtB,GAAA,EAAK,UAAA,CAAW,QAAA,EAAU,OAAA,EAAS,WAAA,IAAe,OAAA;;;;;;;ADApD;UEXU,WAAA,8BAAyC,UAAA,CAAW,aAAA;EAAA,SACnD,SAAA,EAAW,cAAA,CAAe,WAAA,oCACf,CAAA,GACd,MAAA,oBACA,CAAA;AAAA;;;;;;;;;;;;;;;;;;;iBAsBQ,OAAA,oCAA2C,UAAA,CAAW,aAAA,IAAA,CACpE,WAAA,EAAa,WAAA,GACZ,UAAA,CAAW,WAAA,CAAY,WAAA;;;;;;;AFjB1B;;iBGPsB,QAAA,CAAS,OAAA,GAAU,eAAA,GAAkB,OAAA,CAAQ,UAAA;;;;;;;AHOnE;;;;;;;;;;;;;;;;;;;;;;iBIGgB,eAAA,6BAAA,CACd,GAAA,EAAK,OAAA,EACL,GAAA,EAAK,IAAA,EACL,KAAA,EAAO,MAAA,GACN,OAAA;;;;;;;AJPH;;;;;;;;;;;;;iBKJgB,UAAA,cAAwB,aAAA,GAAgB,aAAA,CAAA,CACtD,OAAA,EAAS,YAAA,CAAa,IAAA,IACrB,UAAA,CAAW,IAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/cli.ts","../src/command.ts","../src/compose.ts","../src/autoloader.ts","../src/context/decorate.ts","../src/middleware.ts"],"mappings":";;;;;;;;AA4BA;;;;;iBAAsB,GAAA,iBAAoB,CAAA,CAAE,OAAA,GAAU,CAAA,CAAE,OAAA,CAAA,CACtD,OAAA,EAAS,UAAA,CAAW,OAAA,IACnB,OAAA;;;;;;;;;;;;;;;;;iBCgBa,OAAA,kBACG,OAAA,GAAU,OAAA,kBACX,MAAA,oBAA0B,MAAA,sDACP,UAAA,CAAW,aAAA,eACnC,UAAA,CAAW,aAAA,IAAA,CACtB,GAAA,EAAK,UAAA,CAAW,QAAA,EAAU,OAAA,EAAS,WAAA,IAAe,OAAA;;;;;;;ADvBpD;UEdU,WAAA,8BAAyC,UAAA,CAAW,aAAA;EAAA,SACnD,SAAA,EAAW,cAAA,CAAe,WAAA,oCACf,CAAA,GACd,MAAA,oBACA,CAAA;AAAA;;;;;;;;;;;;;;;;;;;iBAsBQ,OAAA,oCAA2C,UAAA,CAAW,aAAA,IAAA,CACpE,WAAA,EAAa,WAAA,GACZ,UAAA,CAAW,WAAA,CAAY,WAAA;;;;;;;AFd1B;;iBGVsB,QAAA,CAAS,OAAA,GAAU,eAAA,GAAkB,OAAA,CAAQ,UAAA;;;;;;;AHUnE;;;;;;;;;;;;;;;;;;;;;;iBIAgB,eAAA,6BAAA,CACd,GAAA,EAAK,OAAA,EACL,GAAA,EAAK,IAAA,EACL,KAAA,EAAO,MAAA,GACN,OAAA;;;;;;;AJJH;;;;;;;;;;;;;iBKPgB,UAAA,cAAwB,aAAA,GAAgB,aAAA,CAAA,CACtD,OAAA,EAAS,YAAA,CAAa,IAAA,IACrB,UAAA,CAAW,IAAA"}

package/dist/index.js

@@ -6,6 +6,7 @@ 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 { TAG, hasTag, withTag } from "@kidd-cli/utils/tag";
 import { jsonStringify } from "@kidd-cli/utils/json";
@@ -460,6 +461,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 +741,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 +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 { 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 +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((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 +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({
@@ -932,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.
@@ -962,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.
@@ -978,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.
@@ -1001,21 +1205,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.