@rune-cli/rune 0.0.6 → 0.0.8

package/dist/cli.mjs

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
-import { a as isHelpFlag, i as successResult, n as runManifestCommand, o as isVersionFlag, r as failureResult, t as writeCommandExecutionResult } from "./write-result-DOrdlrbw.mjs";
+import "./dist-uz53Uv1e.mjs";
+import { n as isHelpFlag, r as isVersionFlag, t as runManifestCommand } from "./run-manifest-command-Dq_lBv-H.mjs";
 import { fileURLToPath } from "node:url";
 import { build } from "esbuild";
 import { cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import ts from "typescript";
 //#region package.json
-var version = "0.0.6";
+var version = "0.0.8";
 //#endregion
 //#region src/manifest/generate-manifest.ts
 const COMMAND_ENTRY_FILE = "index.ts";
@@ -143,6 +144,32 @@ async function assertCommandsDirectoryExists(commandsDirectory) {
 	}))?.isDirectory()) throw new Error(`Commands directory not found at ${COMMANDS_DIRECTORY_NAME}. Create it or check the --project <path> option.`);
 }
 //#endregion
+//#region src/cli/write-result.ts
+async function writeStream(stream, contents) {
+	if (contents.length === 0) return;
+	await new Promise((resolve, reject) => {
+		stream.write(contents, (error) => {
+			if (error) {
+				reject(error);
+				return;
+			}
+			resolve();
+		});
+	});
+}
+function ensureTrailingNewline(contents) {
+	return contents.endsWith("\n") ? contents : `${contents}\n`;
+}
+async function writeStdout(contents) {
+	await writeStream(process.stdout, contents);
+}
+async function writeStderr(contents) {
+	await writeStream(process.stderr, contents);
+}
+async function writeStderrLine(contents) {
+	await writeStderr(ensureTrailingNewline(contents));
+}
+//#endregion
 //#region src/cli/build-command.ts
 const BUILD_CLI_FILENAME = "cli.mjs";
 const BUILD_MANIFEST_FILENAME = "manifest.json";
@@ -209,7 +236,7 @@ function renderBuiltCliEntry(cliName, version, runtimeImportPath) {
 	return `import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
-import { runManifestCommand, writeCommandExecutionResult } from ${JSON.stringify(runtimeImportPath)};
+import { runManifestCommand } from ${JSON.stringify(runtimeImportPath)};
 
 const cliName = ${JSON.stringify(cliName)};
 const version = ${JSON.stringify(version)};
@@ -228,15 +255,13 @@ const runtimeManifest = {
       : node,
   ),
 };
-const result = await runManifestCommand({
+process.exitCode = await runManifestCommand({
   manifest: runtimeManifest,
   rawArgs: process.argv.slice(2),
   cliName,
   version,
   cwd: process.cwd(),
 });
-
-await writeCommandExecutionResult(result);
 `;
 }
 function collectCommandEntryPoints(manifest) {
@@ -359,10 +384,15 @@ async function runBuildCommand(options) {
 			buildCliEntry(projectRoot, distDirectory, cliInfo.name, cliInfo.version),
 			copyBuiltAssets(sourceDirectory, distDirectory)
 		]);
-		return successResult(`Built CLI to ${path.join(distDirectory, BUILD_CLI_FILENAME)}\n`);
+		await writeStdout(`Built CLI to ${path.join(distDirectory, BUILD_CLI_FILENAME)}\n`);
+		return 0;
 	} catch (error) {
-		if (isBuildFailure(error)) return failureResult(formatBuildFailure(projectRoot, error));
-		return failureResult(error instanceof Error ? error.message : "Failed to run rune build");
+		if (isBuildFailure(error)) {
+			await writeStderrLine(formatBuildFailure(projectRoot, error));
+			return 1;
+		}
+		await writeStderrLine(error instanceof Error ? error.message : "Failed to run rune build");
+		return 1;
 	}
 }
 //#endregion
@@ -394,7 +424,10 @@ async function runDevCommand(options) {
 	try {
 		const projectRoot = resolveProjectPath(options);
 		const cliInfo = await readProjectCliInfo(projectRoot);
-		if (cliInfo.version && options.rawArgs.length === 1 && isVersionFlag(options.rawArgs[0])) return successResult(`${cliInfo.name} v${cliInfo.version}\n`);
+		if (cliInfo.version && options.rawArgs.length === 1 && isVersionFlag(options.rawArgs[0])) {
+			await writeStdout(`${cliInfo.name} v${cliInfo.version}\n`);
+			return 0;
+		}
 		const commandsDirectory = resolveCommandsDirectory(projectRoot);
 		await assertCommandsDirectoryExists(commandsDirectory);
 		const manifest = await generateCommandManifest({ commandsDirectory });
@@ -407,21 +440,34 @@ async function runDevCommand(options) {
 			cwd: options.cwd
 		});
 	} catch (error) {
-		return failureResult(error instanceof Error ? error.message : "Failed to run rune dev");
+		await writeStderrLine(error instanceof Error ? error.message : "Failed to run rune dev");
+		return 1;
 	}
 }
 //#endregion
 //#region src/cli/rune-cli.ts
+async function writeEarlyExit(exit) {
+	if (exit.stream === "stdout") await writeStdout(exit.output);
+	else await writeStderrLine(exit.output);
+	return exit.exitCode;
+}
 function tryParseProjectOption(argv, index) {
 	const token = argv[index];
 	if (token.startsWith("--project=")) return {
+		ok: true,
 		projectPath: token.slice(10),
 		nextIndex: index + 1
 	};
 	if (token === "--project") {
 		const nextToken = argv[index + 1];
-		if (!nextToken) return failureResult("Missing value for --project. Usage: --project <path>");
+		if (!nextToken) return {
+			ok: false,
+			exitCode: 1,
+			output: "Missing value for --project. Usage: --project <path>",
+			stream: "stderr"
+		};
 		return {
+			ok: true,
 			projectPath: nextToken,
 			nextIndex: index + 2
 		};
@@ -438,25 +484,33 @@ function parseDevArgs(argv) {
 		if (token === "--") {
 			commandArgs.push(...argv.slice(index + 1));
 			return {
+				ok: true,
 				projectPath,
 				commandArgs
 			};
 		}
-		if (isHelpFlag(token)) return successResult(renderRuneDevHelp());
+		if (isHelpFlag(token)) return {
+			ok: false,
+			exitCode: 0,
+			output: renderRuneDevHelp(),
+			stream: "stdout"
+		};
 		const projectResult = tryParseProjectOption(argv, index);
 		if (projectResult) {
-			if ("exitCode" in projectResult) return projectResult;
+			if (!projectResult.ok) return projectResult;
 			projectPath = projectResult.projectPath;
 			index = projectResult.nextIndex - 1;
 			continue;
 		}
 		commandArgs.push(token, ...argv.slice(index + 1));
 		return {
+			ok: true,
 			projectPath,
 			commandArgs
 		};
 	}
 	return {
+		ok: true,
 		projectPath,
 		commandArgs
 	};
@@ -465,17 +519,30 @@ function parseBuildArgs(argv) {
 	let projectPath;
 	for (let index = 0; index < argv.length; index += 1) {
 		const token = argv[index];
-		if (isHelpFlag(token)) return successResult(renderRuneBuildHelp());
+		if (isHelpFlag(token)) return {
+			ok: false,
+			exitCode: 0,
+			output: renderRuneBuildHelp(),
+			stream: "stdout"
+		};
 		const projectResult = tryParseProjectOption(argv, index);
 		if (projectResult) {
-			if ("exitCode" in projectResult) return projectResult;
+			if (!projectResult.ok) return projectResult;
 			projectPath = projectResult.projectPath;
 			index = projectResult.nextIndex - 1;
 			continue;
 		}
-		return failureResult(`Unexpected argument for rune build: ${token}`);
+		return {
+			ok: false,
+			exitCode: 1,
+			output: `Unexpected argument for rune build: ${token}`,
+			stream: "stderr"
+		};
 	}
-	return { projectPath };
+	return {
+		ok: true,
+		projectPath
+	};
 }
 function renderRuneCliHelp() {
 	return `\
@@ -492,11 +559,17 @@ Options:
 }
 async function runRuneCli(options) {
 	const [subcommand, ...restArgs] = options.argv;
-	if (!subcommand || isHelpFlag(subcommand)) return successResult(renderRuneCliHelp());
-	if (isVersionFlag(subcommand)) return successResult(`rune v${getRuneVersion()}\n`);
+	if (!subcommand || isHelpFlag(subcommand)) {
+		await writeStdout(renderRuneCliHelp());
+		return 0;
+	}
+	if (isVersionFlag(subcommand)) {
+		await writeStdout(`rune v${getRuneVersion()}\n`);
+		return 0;
+	}
 	if (subcommand === "dev") {
 		const parsedDevArgs = parseDevArgs(restArgs);
-		if ("exitCode" in parsedDevArgs) return parsedDevArgs;
+		if (!parsedDevArgs.ok) return writeEarlyExit(parsedDevArgs);
 		return runDevCommand({
 			rawArgs: parsedDevArgs.commandArgs,
 			projectPath: parsedDevArgs.projectPath,
@@ -505,19 +578,20 @@ async function runRuneCli(options) {
 	}
 	if (subcommand === "build") {
 		const parsedBuildArgs = parseBuildArgs(restArgs);
-		if ("exitCode" in parsedBuildArgs) return parsedBuildArgs;
+		if (!parsedBuildArgs.ok) return writeEarlyExit(parsedBuildArgs);
 		return runBuildCommand({
 			projectPath: parsedBuildArgs.projectPath,
 			cwd: options.cwd
 		});
 	}
-	return failureResult(`Unknown command: ${subcommand}. Available commands: build, dev`);
+	await writeStderrLine(`Unknown command: ${subcommand}. Available commands: build, dev`);
+	return 1;
 }
 //#endregion
 //#region src/cli.ts
-await writeCommandExecutionResult(await runRuneCli({
+process.exitCode = await runRuneCli({
 	argv: process.argv.slice(2),
 	cwd: process.cwd()
-}));
+});
 //#endregion
 export {};

package/dist/{dist-Bcn0FpHi.mjs → dist-uz53Uv1e.mjs}

@@ -3,7 +3,35 @@ import { format, parseArgs } from "node:util";
 function isSchemaField(field) {
 	return "schema" in field && field.schema !== void 0;
 }
-const EMPTY_FIELDS = [];
+const DEFINED_COMMAND_BRAND = Symbol.for("@rune-cli/defined-command");
+const OPTION_NAME_RE = /^[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*$/;
+const ALIAS_RE = /^[a-zA-Z]$/;
+function validateFieldShape(fields, kind) {
+	for (const field of fields) {
+		const raw = field;
+		if (raw.schema === void 0 && raw.type === void 0) throw new Error(`${kind === "argument" ? "Argument" : "Option"} "${raw.name}" must have either a "type" or "schema" property.`);
+	}
+}
+function validateUniqueFieldNames(fields, kind) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const field of fields) {
+		if (field.name.length === 0) throw new Error(`Invalid ${kind} name "${field.name}". Names must be non-empty.`);
+		if (seen.has(field.name)) throw new Error(`Duplicate ${kind} name "${field.name}".`);
+		seen.add(field.name);
+	}
+}
+function validateOptionNames(options) {
+	for (const field of options) if (!OPTION_NAME_RE.test(field.name)) throw new Error(`Invalid option name "${field.name}". Option names must start with a letter and contain only letters, numbers, and internal hyphens.`);
+}
+function validateOptionAliases(options) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const field of options) {
+		if (field.alias === void 0) continue;
+		if (!ALIAS_RE.test(field.alias)) throw new Error(`Invalid alias "${field.alias}" for option "${field.name}". Alias must be a single letter.`);
+		if (seen.has(field.alias)) throw new Error(`Duplicate alias "${field.alias}" for option "${field.name}".`);
+		seen.add(field.alias);
+	}
+}
 function isOptionalArg(field) {
 	if (isSchemaField(field)) return;
 	return field.required !== true || field.default !== void 0;
@@ -69,19 +97,56 @@ function validateArgOrdering(args) {
 * the ordering check is skipped for that field.
 */
 function defineCommand(input) {
-	if (input.args) validateArgOrdering(input.args);
-	return {
+	if (input.args) {
+		validateFieldShape(input.args, "argument");
+		validateUniqueFieldNames(input.args, "argument");
+		validateArgOrdering(input.args);
+	}
+	if (input.options) {
+		validateFieldShape(input.options, "option");
+		validateUniqueFieldNames(input.options, "option");
+		validateOptionNames(input.options);
+		validateOptionAliases(input.options);
+	}
+	const command = {
 		description: input.description,
-		args: input.args ?? EMPTY_FIELDS,
-		options: input.options ?? EMPTY_FIELDS,
+		args: input.args ?? [],
+		options: input.options ?? [],
 		run: input.run
 	};
+	Object.defineProperty(command, DEFINED_COMMAND_BRAND, {
+		value: true,
+		enumerable: false
+	});
+	return command;
+}
+function isDefinedCommand(value) {
+	return typeof value === "object" && value !== null && value[DEFINED_COMMAND_BRAND] === true;
 }
 function formatExecutionError(error) {
 	if (error instanceof Error) return error.message === "" ? "" : error.message || error.name || "Unknown error";
 	if (typeof error === "string") return error;
 	return "Unknown error";
 }
+async function executeCommand(command, input = {}) {
+	try {
+		const options = { ...input.options };
+		for (const field of command.options) if (options[field.name] === void 0 && !isSchemaField(field) && field.type === "boolean") options[field.name] = false;
+		await command.run({
+			options,
+			args: input.args ?? {},
+			cwd: input.cwd ?? process.cwd(),
+			rawArgs: input.rawArgs ?? []
+		});
+		return { exitCode: 0 };
+	} catch (error) {
+		const message = formatExecutionError(error);
+		return message ? {
+			exitCode: 1,
+			errorMessage: message
+		} : { exitCode: 1 };
+	}
+}
 async function captureProcessOutput(action) {
 	const stdoutChunks = [];
 	const stderrChunks = [];
@@ -119,17 +184,18 @@ async function captureProcessOutput(action) {
 	]) console[method] = (...args) => captureConsole(stdoutChunks, args);
 	for (const method of ["warn", "error"]) console[method] = (...args) => captureConsole(stderrChunks, args);
 	try {
-		const value = await action();
 		return {
+			ok: true,
+			value: await action(),
 			stdout: stdoutChunks.join(""),
-			stderr: stderrChunks.join(""),
-			value
+			stderr: stderrChunks.join("")
 		};
 	} catch (error) {
 		return {
+			ok: false,
+			error,
 			stdout: stdoutChunks.join(""),
-			stderr: stderrChunks.join(""),
-			error
+			stderr: stderrChunks.join("")
 		};
 	} finally {
 		process.stdout.write = originalStdoutWrite;
@@ -137,34 +203,11 @@ async function captureProcessOutput(action) {
 		Object.assign(console, originalConsoleMethods);
 	}
 }
-const EMPTY_ARGS = [];
-async function executeCommand(command, input = {}) {
-	const result = await captureProcessOutput(async () => {
-		await command.run({
-			options: input.options ?? {},
-			args: input.args ?? {},
-			cwd: input.cwd ?? process.cwd(),
-			rawArgs: input.rawArgs ?? EMPTY_ARGS
-		});
-	});
-	if (result.error === void 0) return {
-		exitCode: 0,
-		stdout: result.stdout,
-		stderr: result.stderr
-	};
-	const message = formatExecutionError(result.error);
-	return {
-		exitCode: 1,
-		stdout: result.stdout,
-		stderr: `${result.stderr}${message ? `${message}\n` : ""}`
-	};
-}
-function formatFieldTypeHint(field) {
-	if (isSchemaField(field)) return "";
-	return ` <${field.type}>`;
+function formatTypeHint(field) {
+	return isSchemaField(field) ? "" : ` <${field.type}>`;
 }
 function formatOptionLabel(field) {
-	return `--${field.name}${formatFieldTypeHint(field)}`;
+	return `--${field.name}${formatTypeHint(field)}`;
 }
 function formatArgumentLabel(field) {
 	return field.name;
@@ -386,6 +429,7 @@ async function parseCommand(command, rawArgs) {
 		const result = await resolveMissingField(field, () => missingRequiredOption(field));
 		if (!result.ok) return result;
 		if (result.present) parsedOptions[field.name] = result.value;
+		else if (!isSchemaField(field) && field.type === "boolean") parsedOptions[field.name] = false;
 	}
 	return {
 		ok: true,
@@ -397,4 +441,4 @@ async function parseCommand(command, rawArgs) {
 	};
 }
 //#endregion
-export { parseCommand as a, isSchemaField as i, executeCommand as n, formatFieldTypeHint as r, defineCommand as t };
+export { isSchemaField as a, isDefinedCommand as i, defineCommand as n, parseCommand as o, executeCommand as r, captureProcessOutput as t };

package/dist/{index-BF5_G9J2.d.mts → index-BWxfSwrT.d.mts}

@@ -81,7 +81,13 @@ declare namespace StandardSchemaV1 {
 type PrimitiveFieldType = "string" | "number" | "boolean";
 type PrimitiveFieldValue<TType extends PrimitiveFieldType> = TType extends "string" ? string : TType extends "number" ? number : boolean;
 interface NamedField<TName extends string = string> {
-  /** Identifier used as the key in `ctx.args` / `ctx.options` and as the CLI flag name for options. */
+  /**
+   * Identifier used as the key in `ctx.args` / `ctx.options`.
+   *
+   * For args, any non-empty name is allowed.
+   * For options, names must start with a letter and may contain only letters,
+   * numbers, and internal hyphens (for example: `dry-run`, `dryRun`, `v2`).
+   */
   readonly name: TName;
   /** One-line help text shown in `--help` output. */
   readonly description?: string | undefined;
@@ -91,7 +97,8 @@ interface PrimitiveFieldBase<TName extends string, TType extends PrimitiveFieldT
   readonly type: TType;
   /**
    * When `true`, the field must be provided by the user.
-   * Omitted or `false` makes the field optional (absent fields are `undefined` in `ctx`).
+   * Omitted or `false` makes the field optional. Absent fields are `undefined`
+   * in `ctx`, except primitive boolean options, which default to `false`.
    */
   readonly required?: boolean | undefined;
   /** Value used when the user does not provide this field. Makes the field always present in `ctx`. */
@@ -153,9 +160,13 @@ type FieldInputValue<TField> = TField extends {
 type HasDefaultValue<TField> = TField extends {
   readonly default: infer TDefault;
 } ? [TDefault] extends [undefined] ? false : true : false;
-type IsRequiredField<TField> = TField extends {
+type IsRequiredField<TField, TBooleanAlwaysPresent extends boolean = false> = TField extends {
   readonly schema: infer TSchema;
-} ? IsOptionalSchemaOutput<InferSchemaOutput<TSchema>> extends true ? false : true : HasDefaultValue<TField> extends true ? true : TField extends {
+} ? IsOptionalSchemaOutput<InferSchemaOutput<TSchema>> extends true ? false : true : HasDefaultValue<TField> extends true ? true : TBooleanAlwaysPresent extends true ? TField extends {
+  readonly type: "boolean";
+} ? true : TField extends {
+  readonly required: true;
+} ? true : false : TField extends {
   readonly required: true;
 } ? true : false;
 type IsArgOptional<TField> = TField extends {
@@ -170,7 +181,7 @@ type ValidateArgOrder<TArgs> = TArgs extends readonly CommandArgField[] ? IsVali
   readonly args: never;
 } : unknown : unknown;
 type Simplify<TValue> = { [TKey in keyof TValue]: TValue[TKey] };
-type InferNamedFields<TFields extends readonly NamedField[]> = Simplify<{ [TField in TFields[number] as IsRequiredField<TField> extends true ? FieldName<TField> : never]: FieldValue<TField> } & { [TField in TFields[number] as IsRequiredField<TField> extends true ? never : FieldName<TField>]?: FieldValue<TField> }>;
+type InferNamedFields<TFields extends readonly NamedField[], TBooleanAlwaysPresent extends boolean = false> = Simplify<{ [TField in TFields[number] as IsRequiredField<TField, TBooleanAlwaysPresent> extends true ? FieldName<TField> : never]: FieldValue<TField> } & { [TField in TFields[number] as IsRequiredField<TField, TBooleanAlwaysPresent> extends true ? never : FieldName<TField>]?: FieldValue<TField> }>;
 type InferExecutionFields<TFields extends readonly NamedField[]> = Simplify<{ [TField in TFields[number] as FieldName<TField>]?: FieldInputValue<TField> }>;
 /** Runtime data passed into a command's `run` function. */
 interface CommandContext<TOptions, TArgs> {
@@ -193,6 +204,7 @@ interface DefineCommandInput<TArgsFields extends readonly CommandArgField[] | un
   /**
    * Positional arguments declared in the order they appear on the command line.
    * Required arguments must come before optional ones.
+   * Argument names must be non-empty and unique within the command.
    *
    * Each entry is either a primitive field (`{ name, type }`) or a schema
    * field (`{ name, schema }`).
@@ -200,6 +212,8 @@ interface DefineCommandInput<TArgsFields extends readonly CommandArgField[] | un
   readonly args?: TArgsFields;
   /**
    * Options declared as `--name` flags, with optional single-character aliases.
+   * Option names must be unique within the command, start with a letter, and
+   * contain only letters, numbers, and internal hyphens.
    *
    * Each entry is either a primitive field (`{ name, type }`) or a schema
    * field (`{ name, schema }`).
@@ -209,13 +223,13 @@ interface DefineCommandInput<TArgsFields extends readonly CommandArgField[] | un
    * The function executed when this command is invoked.
    * Receives a {@link CommandContext} with fully parsed `args` and `options`.
    */
-  readonly run: (ctx: CommandContext<InferNamedFields<NormalizeFields<TOptionsFields, CommandOptionField>>, InferNamedFields<NormalizeFields<TArgsFields, CommandArgField>>>) => void | Promise<void>;
+  readonly run: (ctx: CommandContext<InferNamedFields<NormalizeFields<TOptionsFields, CommandOptionField>, true>, InferNamedFields<NormalizeFields<TArgsFields, CommandArgField>>>) => void | Promise<void>;
 }
 interface DefinedCommand<TArgsFields extends readonly CommandArgField[] = readonly [], TOptionsFields extends readonly CommandOptionField[] = readonly []> {
   readonly description?: string | undefined;
   readonly args: TArgsFields;
   readonly options: TOptionsFields;
-  readonly run: (ctx: CommandContext<InferNamedFields<TOptionsFields>, InferNamedFields<TArgsFields>>) => void | Promise<void>;
+  readonly run: (ctx: CommandContext<InferNamedFields<TOptionsFields, true>, InferNamedFields<TArgsFields>>) => void | Promise<void>;
 } //#endregion
 //#region src/define-command.d.ts
 /**
@@ -269,7 +283,8 @@ interface DefinedCommand<TArgsFields extends readonly CommandArgField[] = readon
  * a variable without a concrete type), optionality information is lost and
  * the ordering check is skipped for that field.
  */
-declare function defineCommand<const TArgsFields extends readonly CommandArgField[] | undefined = undefined, const TOptionsFields extends readonly CommandOptionField[] | undefined = undefined>(input: DefineCommandInput<TArgsFields, TOptionsFields> & ValidateArgOrder<TArgsFields>): DefinedCommand<NormalizeFields<TArgsFields, CommandArgField>, NormalizeFields<TOptionsFields, CommandOptionField>>; //#endregion
+declare function defineCommand<const TArgsFields extends readonly CommandArgField[] | undefined = undefined, const TOptionsFields extends readonly CommandOptionField[] | undefined = undefined>(input: DefineCommandInput<TArgsFields, TOptionsFields> & ValidateArgOrder<TArgsFields>): DefinedCommand<NormalizeFields<TArgsFields, CommandArgField>, NormalizeFields<TOptionsFields, CommandOptionField>>;
+//#endregion
 //#region src/execute-command.d.ts
 interface ExecuteCommandInput<TOptions, TArgs> {
   readonly options?: TOptions | undefined;
@@ -277,10 +292,5 @@ interface ExecuteCommandInput<TOptions, TArgs> {
   readonly cwd?: string | undefined;
   readonly rawArgs?: readonly string[] | undefined;
 }
-interface CommandExecutionResult {
-  readonly exitCode: number;
-  readonly stdout: string;
-  readonly stderr: string;
-}
 //#endregion
-export { DefinedCommand as a, PrimitiveArgField as c, SchemaArgField as d, SchemaOptionField as f, CommandOptionField as i, PrimitiveFieldType as l, CommandContext as n, ExecuteCommandInput as o, defineCommand as p, CommandExecutionResult as r, InferExecutionFields as s, CommandArgField as t, PrimitiveOptionField as u };
+export { ExecuteCommandInput as a, PrimitiveFieldType as c, SchemaOptionField as d, defineCommand as f, DefinedCommand as i, PrimitiveOptionField as l, CommandContext as n, InferExecutionFields as o, CommandOptionField as r, PrimitiveArgField as s, CommandArgField as t, SchemaArgField as u };

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { a as DefinedCommand, c as PrimitiveArgField, d as SchemaArgField, f as SchemaOptionField, i as CommandOptionField, l as PrimitiveFieldType, n as CommandContext, o as ExecuteCommandInput, p as defineCommand, r as CommandExecutionResult, s as InferExecutionFields, t as CommandArgField, u as PrimitiveOptionField } from "./index-BF5_G9J2.mjs";
-export { type CommandArgField, type CommandContext, type CommandExecutionResult, type CommandOptionField, type DefinedCommand, type ExecuteCommandInput, type InferExecutionFields, type PrimitiveArgField, type PrimitiveFieldType, type PrimitiveOptionField, type SchemaArgField, type SchemaOptionField, defineCommand };
+import { a as ExecuteCommandInput, c as PrimitiveFieldType, d as SchemaOptionField, f as defineCommand, i as DefinedCommand, l as PrimitiveOptionField, n as CommandContext, o as InferExecutionFields, r as CommandOptionField, s as PrimitiveArgField, t as CommandArgField, u as SchemaArgField } from "./index-BWxfSwrT.mjs";
+export { type CommandArgField, type CommandContext, type CommandOptionField, type DefinedCommand, type ExecuteCommandInput, type InferExecutionFields, type PrimitiveArgField, type PrimitiveFieldType, type PrimitiveOptionField, type SchemaArgField, type SchemaOptionField, defineCommand };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { t as defineCommand } from "./dist-Bcn0FpHi.mjs";
+import { n as defineCommand } from "./dist-uz53Uv1e.mjs";
 export { defineCommand };

package/dist/{write-result-DOrdlrbw.mjs → run-manifest-command-Dq_lBv-H.mjs}

@@ -1,4 +1,4 @@
-import { a as parseCommand, i as isSchemaField, n as executeCommand, r as formatFieldTypeHint } from "./dist-Bcn0FpHi.mjs";
+import { a as isSchemaField, i as isDefinedCommand, o as parseCommand, r as executeCommand } from "./dist-uz53Uv1e.mjs";
 import { pathToFileURL } from "node:url";
 //#region src/cli/flags.ts
 function isHelpFlag(token) {
@@ -8,20 +8,40 @@ function isVersionFlag(token) {
 	return token === "--version" || token === "-V";
 }
 //#endregion
-//#region src/cli/result.ts
-function successResult(stdout) {
-	return {
-		exitCode: 0,
-		stdout,
-		stderr: ""
-	};
+//#region src/manifest/command-loader.ts
+async function loadCommandFromModule(sourceFilePath) {
+	const loadedModule = await import(pathToFileURL(sourceFilePath).href);
+	if (loadedModule.default === void 0) throw new Error(`Command module did not export a default command: ${sourceFilePath}`);
+	if (!isDefinedCommand(loadedModule.default)) throw new Error(`Command module must export a value created with defineCommand(). Got ${describeCommandModuleExport(loadedModule.default)}.`);
+	return loadedModule.default;
 }
-function failureResult(stderr) {
-	return {
-		exitCode: 1,
-		stdout: "",
-		stderr: stderr.endsWith("\n") ? stderr : `${stderr}\n`
-	};
+function describeCommandModuleExport(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	if (typeof value === "object") return "a plain object";
+	if (typeof value === "string") return "a string";
+	if (typeof value === "number") return "a number";
+	if (typeof value === "boolean") return "a boolean";
+	if (typeof value === "bigint") return "a bigint";
+	if (typeof value === "symbol") return "a symbol";
+	if (typeof value === "function") return "a function";
+	return "an unsupported value";
+}
+const defaultLoadCommand = (node) => loadCommandFromModule(node.sourceFilePath);
+//#endregion
+//#region src/manifest/damerau-levenshtein.ts
+function damerauLevenshteinDistance(left, right) {
+	const rows = left.length + 1;
+	const cols = right.length + 1;
+	const matrix = Array.from({ length: rows }, () => Array(cols).fill(0));
+	for (let row = 0; row < rows; row += 1) matrix[row][0] = row;
+	for (let col = 0; col < cols; col += 1) matrix[0][col] = col;
+	for (let row = 1; row < rows; row += 1) for (let col = 1; col < cols; col += 1) {
+		const substitutionCost = left[row - 1] === right[col - 1] ? 0 : 1;
+		matrix[row][col] = Math.min(matrix[row - 1][col] + 1, matrix[row][col - 1] + 1, matrix[row - 1][col - 1] + substitutionCost);
+		if (row > 1 && col > 1 && left[row - 1] === right[col - 2] && left[row - 2] === right[col - 1]) matrix[row][col] = Math.min(matrix[row][col], matrix[row - 2][col - 2] + 1);
+	}
+	return matrix[left.length][right.length];
 }
 //#endregion
 //#region src/manifest/manifest-map.ts
@@ -32,24 +52,80 @@ function createCommandManifestNodeMap(manifest) {
 	return Object.fromEntries(manifest.nodes.map((node) => [commandManifestPathToKey(node.pathSegments), node]));
 }
 //#endregion
-//#region src/manifest/render-help.ts
-async function loadCommandFromModule(sourceFilePath) {
-	const loadedModule = await import(pathToFileURL(sourceFilePath).href);
-	if (loadedModule.default === void 0) throw new Error(`Command module did not export a default command: ${sourceFilePath}`);
-	return loadedModule.default;
+//#region src/manifest/resolve-command-path.ts
+function isOptionLikeToken(token) {
+	return token === "--" || token.startsWith("-");
 }
-const defaultLoadCommand = (node) => loadCommandFromModule(node.sourceFilePath);
+function getHelpRequested(args) {
+	return args.some(isHelpFlag);
+}
+function getSuggestionThreshold(candidate) {
+	return Math.max(2, Math.floor(candidate.length / 3));
+}
+function getSuggestedChildNames(unknownSegment, childNames) {
+	return [...childNames].map((childName) => ({
+		childName,
+		distance: damerauLevenshteinDistance(unknownSegment, childName)
+	})).filter(({ childName, distance }) => distance <= getSuggestionThreshold(childName)).sort((left, right) => left.distance - right.distance || left.childName.localeCompare(right.childName)).slice(0, 3).map(({ childName }) => childName);
+}
+function resolveCommandPath(manifest, rawArgs) {
+	const nodeMap = createCommandManifestNodeMap(manifest);
+	const rootNode = nodeMap[""];
+	if (rootNode === void 0) throw new Error("Manifest root node is missing");
+	let currentNode = rootNode;
+	let tokenIndex = 0;
+	while (tokenIndex < rawArgs.length) {
+		const token = rawArgs[tokenIndex];
+		if (isOptionLikeToken(token)) break;
+		const childNode = nodeMap[commandManifestPathToKey([...currentNode.pathSegments, token])];
+		if (childNode === void 0) {
+			const suggestions = getSuggestedChildNames(token, currentNode.childNames);
+			if (currentNode.kind === "group" || suggestions.length > 0) return {
+				kind: "unknown",
+				attemptedPath: [...currentNode.pathSegments, token],
+				matchedPath: currentNode.pathSegments,
+				unknownSegment: token,
+				availableChildNames: currentNode.childNames,
+				suggestions
+			};
+			break;
+		}
+		currentNode = childNode;
+		tokenIndex += 1;
+	}
+	const remainingArgs = rawArgs.slice(tokenIndex);
+	const helpRequested = getHelpRequested(remainingArgs);
+	if (currentNode.kind === "group") return {
+		kind: "group",
+		node: currentNode,
+		matchedPath: currentNode.pathSegments,
+		remainingArgs,
+		helpRequested
+	};
+	return {
+		kind: "command",
+		node: currentNode,
+		matchedPath: currentNode.pathSegments,
+		remainingArgs,
+		helpRequested
+	};
+}
+//#endregion
+//#region src/manifest/render-help.ts
 function formatCommandName(cliName, pathSegments) {
 	return pathSegments.length === 0 ? cliName : `${cliName} ${pathSegments.join(" ")}`;
 }
 function formatSectionEntries(entries) {
 	return entries.map(({ label, description }) => `  ${label}${description ? `  ${description}` : ""}`).join("\n");
 }
+function formatTypeHint(field) {
+	return isSchemaField(field) ? "" : ` <${field.type}>`;
+}
 function formatArgumentLabel(field) {
-	return `${field.name}${formatFieldTypeHint(field)}`;
+	return `${field.name}${formatTypeHint(field)}`;
 }
 function formatOptionLabel(field) {
-	const longOptionLabel = `--${field.name}${formatFieldTypeHint(field)}`;
+	const longOptionLabel = `--${field.name}${formatTypeHint(field)}`;
 	if (!field.alias) return longOptionLabel;
 	return `-${field.alias}, ${longOptionLabel}`;
 }
@@ -117,6 +193,8 @@ function renderUnknownCommandMessage(route, cliName) {
 	if (route.suggestions.length > 0) parts.push(`Did you mean?\n${route.suggestions.map((name) => `  ${name}`).join("\n")}`);
 	return `${parts.join("\n\n")}\n`;
 }
+//#endregion
+//#region src/manifest/resolve-help.ts
 async function renderResolvedHelp(options) {
 	if (options.route.kind === "unknown") return renderUnknownCommandMessage(options.route, options.cliName);
 	if (options.route.kind === "group") return renderGroupHelp({
@@ -128,122 +206,55 @@ async function renderResolvedHelp(options) {
 	return renderCommandHelp(await (options.loadCommand ?? defaultLoadCommand)(options.route.node), options.route.matchedPath, options.cliName);
 }
 //#endregion
-//#region src/manifest/damerau-levenshtein.ts
-function damerauLevenshteinDistance(left, right) {
-	const rows = left.length + 1;
-	const cols = right.length + 1;
-	const matrix = Array.from({ length: rows }, () => Array(cols).fill(0));
-	for (let row = 0; row < rows; row += 1) matrix[row][0] = row;
-	for (let col = 0; col < cols; col += 1) matrix[0][col] = col;
-	for (let row = 1; row < rows; row += 1) for (let col = 1; col < cols; col += 1) {
-		const substitutionCost = left[row - 1] === right[col - 1] ? 0 : 1;
-		matrix[row][col] = Math.min(matrix[row - 1][col] + 1, matrix[row][col - 1] + 1, matrix[row - 1][col - 1] + substitutionCost);
-		if (row > 1 && col > 1 && left[row - 1] === right[col - 2] && left[row - 2] === right[col - 1]) matrix[row][col] = Math.min(matrix[row][col], matrix[row - 2][col - 2] + 1);
-	}
-	return matrix[left.length][right.length];
-}
-//#endregion
-//#region src/manifest/resolve-command-path.ts
-function isOptionLikeToken(token) {
-	return token === "--" || token.startsWith("-");
-}
-function getHelpRequested(args) {
-	return args.some(isHelpFlag);
-}
-function getSuggestionThreshold(candidate) {
-	return Math.max(2, Math.floor(candidate.length / 3));
-}
-function getSuggestedChildNames(unknownSegment, childNames) {
-	return [...childNames].map((childName) => ({
-		childName,
-		distance: damerauLevenshteinDistance(unknownSegment, childName)
-	})).filter(({ childName, distance }) => distance <= getSuggestionThreshold(childName)).sort((left, right) => left.distance - right.distance || left.childName.localeCompare(right.childName)).slice(0, 3).map(({ childName }) => childName);
+//#region src/manifest/run-manifest-command.ts
+function ensureTrailingNewline(text) {
+	return text.endsWith("\n") ? text : `${text}\n`;
 }
-function resolveCommandPath(manifest, rawArgs) {
-	const nodeMap = createCommandManifestNodeMap(manifest);
-	const rootNode = nodeMap[""];
-	if (rootNode === void 0) throw new Error("Manifest root node is missing");
-	let currentNode = rootNode;
-	let tokenIndex = 0;
-	while (tokenIndex < rawArgs.length) {
-		const token = rawArgs[tokenIndex];
-		if (isOptionLikeToken(token)) break;
-		const childNode = nodeMap[commandManifestPathToKey([...currentNode.pathSegments, token])];
-		if (childNode === void 0) {
-			const suggestions = getSuggestedChildNames(token, currentNode.childNames);
-			if (currentNode.kind === "group" || suggestions.length > 0) return {
-				kind: "unknown",
-				attemptedPath: [...currentNode.pathSegments, token],
-				matchedPath: currentNode.pathSegments,
-				unknownSegment: token,
-				availableChildNames: currentNode.childNames,
-				suggestions
-			};
-			break;
-		}
-		currentNode = childNode;
-		tokenIndex += 1;
-	}
-	const remainingArgs = rawArgs.slice(tokenIndex);
-	const helpRequested = getHelpRequested(remainingArgs);
-	if (currentNode.kind === "group") return {
-		kind: "group",
-		node: currentNode,
-		matchedPath: currentNode.pathSegments,
-		remainingArgs,
-		helpRequested
-	};
-	return {
-		kind: "command",
-		node: currentNode,
-		matchedPath: currentNode.pathSegments,
-		remainingArgs,
-		helpRequested
-	};
+function formatRuntimeError(error) {
+	if (error instanceof Error) return error.message || error.name || "Failed to run command";
+	if (typeof error === "string" && error.length > 0) return error;
+	return "Failed to run command";
 }
-//#endregion
-//#region src/manifest/run-manifest-command.ts
 async function runManifestCommand(options) {
-	if (options.version && options.rawArgs.length === 1 && isVersionFlag(options.rawArgs[0])) return successResult(`${options.cliName} v${options.version}\n`);
-	const route = resolveCommandPath(options.manifest, options.rawArgs);
-	if (route.kind === "unknown" || route.kind === "group" || route.helpRequested) {
-		const output = await renderResolvedHelp({
-			manifest: options.manifest,
-			route,
-			cliName: options.cliName,
-			version: options.version,
-			loadCommand: options.loadCommand
-		});
-		return route.kind === "unknown" ? failureResult(output) : successResult(output);
-	}
-	const command = await (options.loadCommand ?? defaultLoadCommand)(route.node);
-	const parsed = await parseCommand(command, route.remainingArgs);
-	if (!parsed.ok) return failureResult(parsed.error.message);
-	return executeCommand(command, {
-		options: parsed.value.options,
-		args: parsed.value.args,
-		cwd: options.cwd,
-		rawArgs: parsed.value.rawArgs
-	});
-}
-//#endregion
-//#region src/cli/write-result.ts
-async function writeStream(stream, contents) {
-	if (contents.length === 0) return;
-	await new Promise((resolve, reject) => {
-		stream.write(contents, (error) => {
-			if (error) {
-				reject(error);
-				return;
+	try {
+		if (options.version && options.rawArgs.length === 1 && isVersionFlag(options.rawArgs[0])) {
+			process.stdout.write(`${options.cliName} v${options.version}\n`);
+			return 0;
+		}
+		const route = resolveCommandPath(options.manifest, options.rawArgs);
+		if (route.kind === "unknown" || route.kind === "group" || route.helpRequested) {
+			const output = await renderResolvedHelp({
+				manifest: options.manifest,
+				route,
+				cliName: options.cliName,
+				version: options.version,
+				loadCommand: options.loadCommand
+			});
+			if (route.kind === "unknown") {
+				process.stderr.write(ensureTrailingNewline(output));
+				return 1;
 			}
-			resolve();
+			process.stdout.write(output);
+			return 0;
+		}
+		const command = await (options.loadCommand ?? defaultLoadCommand)(route.node);
+		const parsed = await parseCommand(command, route.remainingArgs);
+		if (!parsed.ok) {
+			process.stderr.write(ensureTrailingNewline(parsed.error.message));
+			return 1;
+		}
+		const result = await executeCommand(command, {
+			options: parsed.value.options,
+			args: parsed.value.args,
+			cwd: options.cwd,
+			rawArgs: parsed.value.rawArgs
 		});
-	});
-}
-async function writeCommandExecutionResult(result) {
-	await writeStream(process.stdout, result.stdout);
-	await writeStream(process.stderr, result.stderr);
-	process.exitCode = result.exitCode;
+		if (result.errorMessage) process.stderr.write(ensureTrailingNewline(result.errorMessage));
+		return result.exitCode;
+	} catch (error) {
+		process.stderr.write(ensureTrailingNewline(formatRuntimeError(error)));
+		return 1;
+	}
 }
 //#endregion
-export { isHelpFlag as a, successResult as i, runManifestCommand as n, isVersionFlag as o, failureResult as r, writeCommandExecutionResult as t };
+export { isHelpFlag as n, isVersionFlag as r, runManifestCommand as t };

package/dist/runtime.d.mts

@@ -1,4 +1,4 @@
-import { a as DefinedCommand, i as CommandOptionField, r as CommandExecutionResult, t as CommandArgField } from "./index-BF5_G9J2.mjs";
+import { i as DefinedCommand, r as CommandOptionField, t as CommandArgField } from "./index-BWxfSwrT.mjs";
 
 //#region src/manifest/manifest-types.d.ts
 type CommandManifestPath = readonly string[];
@@ -22,7 +22,7 @@ interface CommandManifest {
   readonly nodes: readonly CommandManifestNode[];
 }
 //#endregion
-//#region src/manifest/render-help.d.ts
+//#region src/manifest/command-loader.d.ts
 type LoadCommandFn = (node: CommandManifestCommandNode) => Promise<DefinedCommand<readonly CommandArgField[], readonly CommandOptionField[]>>;
 //#endregion
 //#region src/manifest/run-manifest-command.d.ts
@@ -34,9 +34,6 @@ interface RunManifestCommandOptions {
   readonly cwd?: string | undefined;
   readonly loadCommand?: LoadCommandFn | undefined;
 }
-declare function runManifestCommand(options: RunManifestCommandOptions): Promise<CommandExecutionResult>;
+declare function runManifestCommand(options: RunManifestCommandOptions): Promise<number>;
 //#endregion
-//#region src/cli/write-result.d.ts
-declare function writeCommandExecutionResult(result: CommandExecutionResult): Promise<void>;
-//#endregion
-export { runManifestCommand, writeCommandExecutionResult };
+export { runManifestCommand };

package/dist/runtime.mjs

@@ -1,2 +1,3 @@
-import { n as runManifestCommand, t as writeCommandExecutionResult } from "./write-result-DOrdlrbw.mjs";
-export { runManifestCommand, writeCommandExecutionResult };
+import "./dist-uz53Uv1e.mjs";
+import { t as runManifestCommand } from "./run-manifest-command-Dq_lBv-H.mjs";
+export { runManifestCommand };

package/dist/test.d.mts

@@ -1,7 +1,50 @@
-import { a as DefinedCommand, i as CommandOptionField, o as ExecuteCommandInput, r as CommandExecutionResult, s as InferExecutionFields, t as CommandArgField } from "./index-BF5_G9J2.mjs";
+import { a as ExecuteCommandInput, i as DefinedCommand, o as InferExecutionFields, r as CommandOptionField, t as CommandArgField } from "./index-BWxfSwrT.mjs";
 
 //#region src/test.d.ts
 type RunCommandOptions<TOptions, TArgs> = ExecuteCommandInput<TOptions, TArgs>;
+interface CommandExecutionResult {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly errorMessage?: string | undefined;
+}
+/**
+ * Runs a command definition directly in-process for testing.
+ *
+ * This helper bypasses Rune's CLI parser and validation layers. Callers
+ * provide already-normalized `options` and `args` values, and the command's
+ * `run` function is executed with those values injected into the context.
+ *
+ * All output written to `process.stdout`, `process.stderr`, and `console` is
+ * captured and returned as strings so tests can assert on them.
+ *
+ * @param command - A command created with {@link defineCommand}.
+ * @param options - Pre-validated options, args, cwd, and rawArgs to inject.
+ * @returns The exit code, captured stdout/stderr, and an optional error message.
+ *
+ * @example
+ * ```ts
+ * import { defineCommand } from "rune";
+ * import { runCommand } from "rune/test";
+ * import { expect, test } from "vitest";
+ *
+ * const hello = defineCommand({
+ *   options: [{ name: "name", type: "string", required: true }],
+ *   run(ctx) {
+ *     console.log(`Hello, ${ctx.options.name}!`);
+ *   },
+ * });
+ *
+ * test("hello command", async () => {
+ *   const result = await runCommand(hello, {
+ *     options: { name: "Rune" },
+ *   });
+ *
+ *   expect(result.exitCode).toBe(0);
+ *   expect(result.stdout).toBe("Hello, Rune!\n");
+ * });
+ * ```
+ */
 declare function runCommand<TArgsFields extends readonly CommandArgField[], TOptionsFields extends readonly CommandOptionField[]>(command: DefinedCommand<TArgsFields, TOptionsFields>, options?: RunCommandOptions<InferExecutionFields<TOptionsFields>, InferExecutionFields<TArgsFields>>): Promise<CommandExecutionResult>;
 //#endregion
-export { RunCommandOptions, runCommand };
+export { CommandExecutionResult, RunCommandOptions, runCommand };

package/dist/test.mjs

@@ -1,7 +1,51 @@
-import { n as executeCommand } from "./dist-Bcn0FpHi.mjs";
+import { r as executeCommand, t as captureProcessOutput } from "./dist-uz53Uv1e.mjs";
 //#region src/test.ts
+/**
+* Runs a command definition directly in-process for testing.
+*
+* This helper bypasses Rune's CLI parser and validation layers. Callers
+* provide already-normalized `options` and `args` values, and the command's
+* `run` function is executed with those values injected into the context.
+*
+* All output written to `process.stdout`, `process.stderr`, and `console` is
+* captured and returned as strings so tests can assert on them.
+*
+* @param command - A command created with {@link defineCommand}.
+* @param options - Pre-validated options, args, cwd, and rawArgs to inject.
+* @returns The exit code, captured stdout/stderr, and an optional error message.
+*
+* @example
+* ```ts
+* import { defineCommand } from "rune";
+* import { runCommand } from "rune/test";
+* import { expect, test } from "vitest";
+*
+* const hello = defineCommand({
+*   options: [{ name: "name", type: "string", required: true }],
+*   run(ctx) {
+*     console.log(`Hello, ${ctx.options.name}!`);
+*   },
+* });
+*
+* test("hello command", async () => {
+*   const result = await runCommand(hello, {
+*     options: { name: "Rune" },
+*   });
+*
+*   expect(result.exitCode).toBe(0);
+*   expect(result.stdout).toBe("Hello, Rune!\n");
+* });
+* ```
+*/
 async function runCommand(command, options = {}) {
-	return executeCommand(command, options);
+	const captured = await captureProcessOutput(() => executeCommand(command, options));
+	if (!captured.ok) throw captured.error;
+	return {
+		exitCode: captured.value.exitCode,
+		stdout: captured.stdout,
+		stderr: captured.stderr,
+		errorMessage: captured.value.errorMessage
+	};
 }
 //#endregion
 export { runCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-cli/rune",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Rune is a CLI framework built around the concept of file-based command routing.",
   "homepage": "https://github.com/morinokami/rune#readme",
   "bugs": {