@rune-cli/rune 0.0.5 → 0.0.7

package/dist/cli.mjs

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
-import { i as successResult, n as runManifestCommand, r as failureResult, t as writeCommandExecutionResult } from "./write-result-qylmqXvG.mjs";
+import "./dist-FWLEc-op.mjs";
+import { n as isHelpFlag, r as isVersionFlag, t as runManifestCommand } from "./run-manifest-command-BmeVwPA5.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.5";
+var version = "0.0.7";
 //#endregion
 //#region src/manifest/generate-manifest.ts
 const COMMAND_ENTRY_FILE = "index.ts";
@@ -116,20 +117,25 @@ function resolveCommandsDirectory(projectRoot) {
 function resolveDistDirectory(projectRoot) {
 	return path.join(projectRoot, DIST_DIRECTORY_NAME);
 }
-async function readProjectCliName(projectRoot) {
+async function readProjectCliInfo(projectRoot) {
 	const packageJsonPath = path.join(projectRoot, "package.json");
 	try {
 		const packageJsonContents = await readFile(packageJsonPath, "utf8");
 		const packageJson = JSON.parse(packageJsonContents);
+		let name;
 		if (packageJson.bin && typeof packageJson.bin === "object") {
 			const binNames = Object.keys(packageJson.bin).sort((left, right) => left.localeCompare(right));
-			if (binNames.length > 0) return binNames[0];
+			if (binNames.length > 0) name = binNames[0];
 		}
-		if (packageJson.name && packageJson.name.length > 0) return packageJson.name.split("/").at(-1) ?? packageJson.name;
+		if (!name && packageJson.name && packageJson.name.length > 0) name = packageJson.name.split("/").at(-1) ?? packageJson.name;
+		return {
+			name: name ?? path.basename(projectRoot),
+			version: packageJson.version
+		};
 	} catch (error) {
 		if (error.code !== "ENOENT") throw error;
 	}
-	return path.basename(projectRoot);
+	return { name: path.basename(projectRoot) };
 }
 async function assertCommandsDirectoryExists(commandsDirectory) {
 	if (!(await stat(commandsDirectory).catch((error) => {
@@ -138,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";
@@ -200,13 +232,14 @@ async function copyBuiltAssets(sourceDirectory, distDirectory) {
 		await cp(sourceEntryPath, distEntryPath);
 	}));
 }
-function renderBuiltCliEntry(cliName, runtimeImportPath) {
+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)};
 const distDirectoryUrl = new URL("./", import.meta.url);
 const manifestPath = fileURLToPath(new URL("./${BUILD_MANIFEST_FILENAME}", distDirectoryUrl));
 const manifestContents = await readFile(manifestPath, "utf8");
@@ -222,14 +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) {
@@ -292,12 +324,12 @@ async function buildCommandEntries(projectRoot, sourceDirectory, distDirectory,
 		write: true
 	});
 }
-async function buildCliEntry(projectRoot, distDirectory, cliName) {
+async function buildCliEntry(projectRoot, distDirectory, cliName, version) {
 	const runtimeHelperEntryPath = await resolveRuntimeHelperEntryPath();
 	await build({
 		absWorkingDir: projectRoot,
 		stdin: {
-			contents: renderBuiltCliEntry(cliName, `./${path.basename(runtimeHelperEntryPath)}`),
+			contents: renderBuiltCliEntry(cliName, version, `./${path.basename(runtimeHelperEntryPath)}`),
 			loader: "ts",
 			resolveDir: path.dirname(runtimeHelperEntryPath),
 			sourcefile: "rune-built-cli-entry.ts"
@@ -341,7 +373,7 @@ async function runBuildCommand(options) {
 		await assertCommandsDirectoryExists(commandsDirectory);
 		const sourceManifest = await generateCommandManifest({ commandsDirectory });
 		const builtManifest = createBuiltManifest(sourceManifest, sourceDirectory);
-		const cliName = await readProjectCliName(projectRoot);
+		const cliInfo = await readProjectCliInfo(projectRoot);
 		await rm(distDirectory, {
 			recursive: true,
 			force: true
@@ -349,13 +381,18 @@ async function runBuildCommand(options) {
 		await writeBuiltRuntimeFiles(distDirectory, builtManifest);
 		await Promise.all([
 			buildCommandEntries(projectRoot, sourceDirectory, distDirectory, sourceManifest),
-			buildCliEntry(projectRoot, distDirectory, cliName),
+			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
@@ -386,6 +423,11 @@ Examples:
 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])) {
+			await writeStdout(`${cliInfo.name} v${cliInfo.version}\n`);
+			return 0;
+		}
 		const commandsDirectory = resolveCommandsDirectory(projectRoot);
 		await assertCommandsDirectoryExists(commandsDirectory);
 		const manifest = await generateCommandManifest({ commandsDirectory });
@@ -393,36 +435,44 @@ async function runDevCommand(options) {
 		return runManifestCommand({
 			manifest,
 			rawArgs: options.rawArgs,
-			cliName: await readProjectCliName(projectRoot),
+			cliName: cliInfo.name,
+			version: cliInfo.version,
 			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
 		};
 	}
 }
-function isHelpFlag(token) {
-	return token === "--help" || token === "-h";
-}
-function isVersionFlag(token) {
-	return token === "--version" || token === "-V";
-}
 function getRuneVersion() {
 	return version;
 }
@@ -434,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
 	};
@@ -461,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 `\
@@ -488,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,
@@ -501,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-FWLEc-op.mjs}

@@ -3,7 +3,7 @@ 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");
 function isOptionalArg(field) {
 	if (isSchemaField(field)) return;
 	return field.required !== true || field.default !== void 0;
@@ -70,18 +70,43 @@ function validateArgOrdering(args) {
 */
 function defineCommand(input) {
 	if (input.args) validateArgOrdering(input.args);
-	return {
+	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 {
+		await command.run({
+			options: input.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 +144,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 +163,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;
@@ -397,4 +400,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-B6XsJ6ON.d.mts}

@@ -269,7 +269,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 +278,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-B6XsJ6ON.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-FWLEc-op.mjs";
 export { defineCommand };

package/dist/{write-result-qylmqXvG.mjs → run-manifest-command-BmeVwPA5.mjs}

@@ -1,110 +1,33 @@
-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-FWLEc-op.mjs";
 import { pathToFileURL } from "node:url";
-//#region src/cli/result.ts
-function successResult(stdout) {
-	return {
-		exitCode: 0,
-		stdout,
-		stderr: ""
-	};
-}
-function failureResult(stderr) {
-	return {
-		exitCode: 1,
-		stdout: "",
-		stderr: stderr.endsWith("\n") ? stderr : `${stderr}\n`
-	};
-}
-//#endregion
-//#region src/manifest/manifest-map.ts
-function commandManifestPathToKey(pathSegments) {
-	return pathSegments.join(" ");
+//#region src/cli/flags.ts
+function isHelpFlag(token) {
+	return token === "--help" || token === "-h";
 }
-function createCommandManifestNodeMap(manifest) {
-	return Object.fromEntries(manifest.nodes.map((node) => [commandManifestPathToKey(node.pathSegments), node]));
+function isVersionFlag(token) {
+	return token === "--version" || token === "-V";
 }
 //#endregion
-//#region src/manifest/render-help.ts
+//#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;
 }
-const defaultLoadCommand = (node) => loadCommandFromModule(node.sourceFilePath);
-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 formatArgumentLabel(field) {
-	return `${field.name}${formatFieldTypeHint(field)}`;
-}
-function formatOptionLabel(field) {
-	const longOptionLabel = `--${field.name}${formatFieldTypeHint(field)}`;
-	if (!field.alias) return longOptionLabel;
-	return `-${field.alias}, ${longOptionLabel}`;
-}
-async function isFieldRequired(field) {
-	if (!isSchemaField(field)) return field.required === true && field.default === void 0;
-	return !("value" in await field.schema["~standard"].validate(void 0));
-}
-async function formatUsageArguments(fields) {
-	const usageParts = [];
-	for (const field of fields) {
-		const required = await isFieldRequired(field);
-		usageParts.push(required ? `<${field.name}>` : `[${field.name}]`);
-	}
-	return usageParts.join(" ");
-}
-function getOptionUsageSuffix(fields) {
-	return fields.length === 0 ? "" : "[options]";
-}
-function renderGroupHelp(manifest, node, cliName) {
-	const nodeMap = createCommandManifestNodeMap(manifest);
-	const entries = node.childNames.map((childName) => {
-		return {
-			label: childName,
-			description: nodeMap[commandManifestPathToKey([...node.pathSegments, childName])]?.description
-		};
-	});
-	const parts = [`Usage: ${formatCommandName(cliName, node.pathSegments)} <command>`];
-	if (entries.length > 0) parts.push(`Subcommands:\n${formatSectionEntries(entries)}`);
-	return `${parts.join("\n\n")}\n`;
-}
-async function renderCommandHelp(command, pathSegments, cliName) {
-	const usageArguments = await formatUsageArguments(command.args);
-	const optionUsageSuffix = getOptionUsageSuffix(command.options);
-	const parts = [`Usage: ${[
-		formatCommandName(cliName, pathSegments),
-		usageArguments,
-		optionUsageSuffix
-	].filter((part) => part.length > 0).join(" ")}`];
-	if (command.description) parts.push(`Description:\n  ${command.description}`);
-	if (command.args.length > 0) parts.push(`Arguments:\n${formatSectionEntries(command.args.map((field) => ({
-		label: formatArgumentLabel(field),
-		description: field.description
-	})))}`);
-	const optionEntries = [...command.options.map((field) => ({
-		label: formatOptionLabel(field),
-		description: field.description
-	})), {
-		label: "-h, --help",
-		description: "Show help"
-	}];
-	parts.push(`Options:\n${formatSectionEntries(optionEntries)}`);
-	return `${parts.join("\n\n")}\n`;
-}
-function renderUnknownCommandMessage(route, cliName) {
-	const parts = [`Unknown command: ${formatCommandName(cliName, route.attemptedPath)}`];
-	if (route.suggestions.length > 0) parts.push(`Did you mean?\n${route.suggestions.map((name) => `  ${name}`).join("\n")}`);
-	return `${parts.join("\n\n")}\n`;
-}
-async function renderResolvedHelp(options) {
-	if (options.route.kind === "unknown") return renderUnknownCommandMessage(options.route, options.cliName);
-	if (options.route.kind === "group") return renderGroupHelp(options.manifest, options.route.node, options.cliName);
-	return renderCommandHelp(await (options.loadCommand ?? defaultLoadCommand)(options.route.node), options.route.matchedPath, options.cliName);
+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) {
@@ -121,12 +44,20 @@ function damerauLevenshteinDistance(left, right) {
 	return matrix[left.length][right.length];
 }
 //#endregion
+//#region src/manifest/manifest-map.ts
+function commandManifestPathToKey(pathSegments) {
+	return pathSegments.join(" ");
+}
+function createCommandManifestNodeMap(manifest) {
+	return Object.fromEntries(manifest.nodes.map((node) => [commandManifestPathToKey(node.pathSegments), node]));
+}
+//#endregion
 //#region src/manifest/resolve-command-path.ts
 function isOptionLikeToken(token) {
 	return token === "--" || token.startsWith("-");
 }
 function getHelpRequested(args) {
-	return args.includes("--help") || args.includes("-h");
+	return args.some(isHelpFlag);
 }
 function getSuggestionThreshold(candidate) {
 	return Math.max(2, Math.floor(candidate.length / 3));
@@ -180,46 +111,150 @@ function resolveCommandPath(manifest, rawArgs) {
 	};
 }
 //#endregion
-//#region src/manifest/run-manifest-command.ts
-async function runManifestCommand(options) {
-	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,
-			loadCommand: options.loadCommand
-		});
-		return route.kind === "unknown" ? failureResult(output) : successResult(output);
+//#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}${formatTypeHint(field)}`;
+}
+function formatOptionLabel(field) {
+	const longOptionLabel = `--${field.name}${formatTypeHint(field)}`;
+	if (!field.alias) return longOptionLabel;
+	return `-${field.alias}, ${longOptionLabel}`;
+}
+async function isFieldRequired(field) {
+	if (!isSchemaField(field)) return field.required === true && field.default === void 0;
+	return !("value" in await field.schema["~standard"].validate(void 0));
+}
+async function formatUsageArguments(fields) {
+	const usageParts = [];
+	for (const field of fields) {
+		const required = await isFieldRequired(field);
+		usageParts.push(required ? `<${field.name}>` : `[${field.name}]`);
 	}
-	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
+	return usageParts.join(" ");
+}
+function getOptionUsageSuffix(fields) {
+	return fields.length === 0 ? "" : "[options]";
+}
+function renderGroupHelp(options) {
+	const { manifest, node, cliName, version } = options;
+	const nodeMap = createCommandManifestNodeMap(manifest);
+	const entries = node.childNames.map((childName) => {
+		return {
+			label: childName,
+			description: nodeMap[commandManifestPathToKey([...node.pathSegments, childName])]?.description
+		};
 	});
+	const parts = [`Usage: ${formatCommandName(cliName, node.pathSegments)} <command>`];
+	if (entries.length > 0) parts.push(`Subcommands:\n${formatSectionEntries(entries)}`);
+	const optionEntries = [{
+		label: "-h, --help",
+		description: "Show help"
+	}, ...node.pathSegments.length === 0 && version ? [{
+		label: "-V, --version",
+		description: "Show the version number"
+	}] : []];
+	parts.push(`Options:\n${formatSectionEntries(optionEntries)}`);
+	return `${parts.join("\n\n")}\n`;
+}
+async function renderCommandHelp(command, pathSegments, cliName) {
+	const usageArguments = await formatUsageArguments(command.args);
+	const optionUsageSuffix = getOptionUsageSuffix(command.options);
+	const parts = [`Usage: ${[
+		formatCommandName(cliName, pathSegments),
+		usageArguments,
+		optionUsageSuffix
+	].filter((part) => part.length > 0).join(" ")}`];
+	if (command.description) parts.push(`Description:\n  ${command.description}`);
+	if (command.args.length > 0) parts.push(`Arguments:\n${formatSectionEntries(command.args.map((field) => ({
+		label: formatArgumentLabel(field),
+		description: field.description
+	})))}`);
+	const optionEntries = [...command.options.map((field) => ({
+		label: formatOptionLabel(field),
+		description: field.description
+	})), {
+		label: "-h, --help",
+		description: "Show help"
+	}];
+	parts.push(`Options:\n${formatSectionEntries(optionEntries)}`);
+	return `${parts.join("\n\n")}\n`;
+}
+function renderUnknownCommandMessage(route, cliName) {
+	const parts = [`Unknown command: ${formatCommandName(cliName, route.attemptedPath)}`];
+	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/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();
-		});
+//#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({
+		manifest: options.manifest,
+		node: options.route.node,
+		cliName: options.cliName,
+		version: options.version
 	});
+	return renderCommandHelp(await (options.loadCommand ?? defaultLoadCommand)(options.route.node), options.route.matchedPath, options.cliName);
 }
-async function writeCommandExecutionResult(result) {
-	await writeStream(process.stdout, result.stdout);
-	await writeStream(process.stderr, result.stderr);
-	process.exitCode = result.exitCode;
+//#endregion
+//#region src/manifest/run-manifest-command.ts
+function ensureTrailingNewline(text) {
+	return text.endsWith("\n") ? text : `${text}\n`;
+}
+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";
+}
+async function runManifestCommand(options) {
+	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;
+			}
+			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
+		});
+		if (result.errorMessage) process.stderr.write(ensureTrailingNewline(result.errorMessage));
+		return result.exitCode;
+	} catch (error) {
+		process.stderr.write(ensureTrailingNewline(formatRuntimeError(error)));
+		return 1;
+	}
 }
 //#endregion
-export { successResult as i, runManifestCommand as n, 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-B6XsJ6ON.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
@@ -30,12 +30,10 @@ interface RunManifestCommandOptions {
   readonly manifest: CommandManifest;
   readonly rawArgs: readonly string[];
   readonly cliName: string;
+  readonly version?: string | undefined;
   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-qylmqXvG.mjs";
-export { runManifestCommand, writeCommandExecutionResult };
+import "./dist-FWLEc-op.mjs";
+import { t as runManifestCommand } from "./run-manifest-command-BmeVwPA5.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-B6XsJ6ON.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-FWLEc-op.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.5",
+  "version": "0.0.7",
   "description": "Rune is a CLI framework built around the concept of file-based command routing.",
   "homepage": "https://github.com/morinokami/rune#readme",
   "bugs": {
@@ -43,7 +43,7 @@
   },
   "devDependencies": {
     "@types/node": "24.12.0",
-    "@typescript/native-preview": "7.0.0-dev.20260317.1",
+    "@typescript/native-preview": "7.0.0-dev.20260322.1",
     "typescript": "5.9.3",
     "vite-plus": "v0.1.13",
     "@rune-cli/core": "0.0.0"