@rune-cli/rune 0.0.9 → 0.0.10

package/dist/cli.mjs

@@ -1,16 +1,23 @@
 #!/usr/bin/env node
-import "./dist-DuisScgY.mjs";
-import { n as isHelpFlag, r as isVersionFlag, t as runManifestCommand } from "./run-manifest-command-BphalAwU.mjs";
+import "./dist-CSbOseWZ.mjs";
+import { n as isHelpFlag, r as isVersionFlag, t as runManifestCommand } from "./run-manifest-command-CSsdj02B.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.9";
+var version = "0.0.10";
 //#endregion
 //#region src/manifest/generate-manifest.ts
 const COMMAND_ENTRY_FILE = "index.ts";
+const GROUP_META_FILE = "_group.ts";
+const BARE_COMMAND_EXTENSION = ".ts";
+const DECLARATION_FILE_SUFFIXES = [
+	".d.ts",
+	".d.mts",
+	".d.cts"
+];
 function comparePathSegments(left, right) {
 	const length = Math.min(left.length, right.length);
 	for (let index = 0; index < length; index += 1) {
@@ -26,13 +33,22 @@ function getStaticDescriptionValue(expression) {
 	if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) return expression.text;
 }
 function isDefineCommandExpression(expression) {
-	if (ts.isIdentifier(expression)) return expression.text === "defineCommand";
-	if (ts.isPropertyAccessExpression(expression)) return expression.name.text === "defineCommand";
+	return isNamedCallExpression(expression, "defineCommand");
+}
+function isDefineGroupExpression(expression) {
+	return isNamedCallExpression(expression, "defineGroup");
+}
+function isNamedCallExpression(expression, name) {
+	if (ts.isIdentifier(expression)) return expression.text === name;
+	if (ts.isPropertyAccessExpression(expression)) return expression.name.text === name;
 	return false;
 }
+function isDefineCallExpression(expression) {
+	return ts.isCallExpression(expression) && (isDefineCommandExpression(expression.expression) || isDefineGroupExpression(expression.expression));
+}
 function extractDescriptionFromCommandDefinition(expression, knownDescriptions) {
 	if (ts.isIdentifier(expression)) return knownDescriptions.get(expression.text);
-	if (!ts.isCallExpression(expression) || !isDefineCommandExpression(expression.expression)) return;
+	if (!ts.isCallExpression(expression) || !isDefineCallExpression(expression)) return;
 	const [definition] = expression.arguments;
 	if (!definition || !ts.isObjectLiteralExpression(definition)) return;
 	for (const property of definition.properties) {
@@ -56,6 +72,26 @@ async function extractDescriptionFromSourceFile(sourceFilePath) {
 		if (ts.isExportAssignment(statement)) return extractDescriptionFromCommandDefinition(statement.expression, knownDescriptions);
 	}
 }
+async function validateGroupMetaFile(sourceFilePath) {
+	const sourceText = await readFile(sourceFilePath, "utf8");
+	const sourceFile = ts.createSourceFile(sourceFilePath, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+	for (const statement of sourceFile.statements) {
+		if (ts.isVariableStatement(statement)) continue;
+		if (ts.isImportDeclaration(statement)) continue;
+		if (ts.isExportAssignment(statement)) {
+			const expression = ts.isIdentifier(statement.expression) ? findVariableInitializer(sourceFile, statement.expression.text) : statement.expression;
+			if (expression && ts.isCallExpression(expression) && isDefineGroupExpression(expression.expression)) return;
+			throw new Error(`${sourceFilePath}: _group.ts must use "export default defineGroup(...)". Found a default export that is not a defineGroup() call.`);
+		}
+	}
+	throw new Error(`${sourceFilePath}: _group.ts must have a default export using defineGroup().`);
+}
+function findVariableInitializer(sourceFile, name) {
+	for (const statement of sourceFile.statements) {
+		if (!ts.isVariableStatement(statement)) continue;
+		for (const declaration of statement.declarationList.declarations) if (ts.isIdentifier(declaration.name) && declaration.name.text === name && declaration.initializer) return declaration.initializer;
+	}
+}
 async function walkCommandsDirectory(absoluteDirectoryPath, pathSegments, extractDescription) {
 	const entries = await readdir(absoluteDirectoryPath, { withFileTypes: true });
 	const childDirectoryNames = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
@@ -65,11 +101,28 @@ async function walkCommandsDirectory(absoluteDirectoryPath, pathSegments, extrac
 			result: await walkCommandsDirectory(path.join(absoluteDirectoryPath, directoryName), [...pathSegments, directoryName], extractDescription)
 		};
 	}));
+	const bareCommandFiles = entries.filter((entry) => entry.isFile() && entry.name.endsWith(BARE_COMMAND_EXTENSION) && entry.name !== COMMAND_ENTRY_FILE && entry.name !== GROUP_META_FILE && !DECLARATION_FILE_SUFFIXES.some((suffix) => entry.name.endsWith(suffix))).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
+	const childDirectoriesWithNodes = new Set(childResults.filter(({ result }) => result.hasNode).map(({ directoryName }) => directoryName));
+	const bareCommandNodes = await Promise.all(bareCommandFiles.map(async (fileName) => {
+		const commandName = fileName.slice(0, -3);
+		if (childDirectoriesWithNodes.has(commandName)) throw new Error(`Conflicting command definitions: both "${commandName}${BARE_COMMAND_EXTENSION}" and "${commandName}/" exist. A bare command file cannot coexist with a command directory.`);
+		const sourceFilePath = path.join(absoluteDirectoryPath, fileName);
+		return {
+			pathSegments: [...pathSegments, commandName],
+			kind: "command",
+			sourceFilePath,
+			childNames: [],
+			description: await extractDescription(sourceFilePath)
+		};
+	}));
 	const childNodes = childResults.flatMap(({ result }) => result.nodes);
-	const childNames = childResults.filter(({ result }) => result.hasNode).map(({ directoryName }) => directoryName);
+	const childNames = [...childResults.filter(({ result }) => result.hasNode).map(({ directoryName }) => directoryName), ...bareCommandFiles.map((fileName) => fileName.slice(0, -3))].sort((left, right) => left.localeCompare(right));
 	const hasCommandEntry = entries.some((entry) => entry.isFile() && entry.name === COMMAND_ENTRY_FILE);
-	if (!hasCommandEntry && childNames.length === 0) return {
-		nodes: childNodes,
+	const hasGroupMeta = entries.some((entry) => entry.isFile() && entry.name === GROUP_META_FILE);
+	if (hasGroupMeta && hasCommandEntry) throw new Error(`Conflicting definitions: both "${GROUP_META_FILE}" and "${COMMAND_ENTRY_FILE}" exist in the same directory. A directory is either a group (_group.ts) or an executable command (index.ts), not both.`);
+	if (hasGroupMeta && childNames.length === 0) throw new Error(`${path.join(absoluteDirectoryPath, GROUP_META_FILE)}: _group.ts exists but the directory has no subcommands.`);
+	if (!hasCommandEntry && !hasGroupMeta && childNames.length === 0) return {
+		nodes: [...childNodes, ...bareCommandNodes],
 		hasNode: false
 	};
 	let node;
@@ -82,20 +135,31 @@ async function walkCommandsDirectory(absoluteDirectoryPath, pathSegments, extrac
 			childNames,
 			description: await extractDescription(sourceFilePath)
 		};
-	} else node = {
-		pathSegments,
-		kind: "group",
-		childNames
-	};
+	} else {
+		const groupMetaPath = path.join(absoluteDirectoryPath, GROUP_META_FILE);
+		if (hasGroupMeta) await validateGroupMetaFile(groupMetaPath);
+		const description = hasGroupMeta ? await extractDescription(groupMetaPath) : void 0;
+		if (hasGroupMeta && !description) throw new Error(`${groupMetaPath}: _group.ts must export a defineGroup() call with a non-empty "description" string.`);
+		node = {
+			pathSegments,
+			kind: "group",
+			childNames,
+			...description !== void 0 ? { description } : {}
+		};
+	}
 	return {
-		nodes: [node, ...childNodes],
+		nodes: [
+			node,
+			...childNodes,
+			...bareCommandNodes
+		],
 		hasNode: true
 	};
 }
 async function generateCommandManifest(options) {
 	const extractDescription = options.extractDescription ?? extractDescriptionFromSourceFile;
 	const walkResult = await walkCommandsDirectory(options.commandsDirectory, [], extractDescription);
-	if (walkResult.nodes.length === 0) throw new Error("No commands found in src/commands/. Create a command file like src/commands/hello/index.ts");
+	if (walkResult.nodes.length === 0) throw new Error("No commands found in src/commands/. Create a command file like src/commands/hello.ts or src/commands/hello/index.ts");
 	return { nodes: [...walkResult.nodes].sort((left, right) => comparePathSegments(left.pathSegments, right.pathSegments)) };
 }
 function serializeCommandManifest(manifest) {

package/dist/{dist-DuisScgY.mjs → dist-CSbOseWZ.mjs}

@@ -1,4 +1,4 @@
-import { format, parseArgs } from "node:util";
+import { parseArgs } from "node:util";
 //#region ../core/dist/index.mjs
 function isSchemaField(field) {
 	return "schema" in field && field.schema !== void 0;
@@ -124,6 +124,31 @@ function defineCommand(input) {
 function isDefinedCommand(value) {
 	return typeof value === "object" && value !== null && value[DEFINED_COMMAND_BRAND] === true;
 }
+const DEFINED_GROUP_BRAND = Symbol.for("@rune-cli/defined-group");
+/**
+* Defines metadata for a command group (a directory that only groups
+* subcommands without being executable itself).
+*
+* Place the default export of this function in a `_group.ts` file inside a
+* command directory.
+*
+* @example
+* ```ts
+* // src/commands/project/_group.ts
+* export default defineGroup({
+*   description: "Manage projects",
+* });
+* ```
+*/
+function defineGroup(input) {
+	if (typeof input.description !== "string" || input.description.length === 0) throw new Error("defineGroup() requires a non-empty \"description\" string.");
+	const group = { description: input.description };
+	Object.defineProperty(group, DEFINED_GROUP_BRAND, {
+		value: true,
+		enumerable: false
+	});
+	return group;
+}
 function formatExecutionError(error) {
 	if (error instanceof Error) return error.message === "" ? "" : error.message || error.name || "Unknown error";
 	if (typeof error === "string") return error;
@@ -148,62 +173,6 @@ async function executeCommand(command, input = {}) {
 		} : { exitCode: 1 };
 	}
 }
-async function captureProcessOutput(action) {
-	const stdoutChunks = [];
-	const stderrChunks = [];
-	const originalStdoutWrite = process.stdout.write.bind(process.stdout);
-	const originalStderrWrite = process.stderr.write.bind(process.stderr);
-	const originalConsoleMethods = {
-		log: console.log,
-		info: console.info,
-		debug: console.debug,
-		warn: console.warn,
-		error: console.error
-	};
-	const captureChunk = (chunks, chunk, encoding) => {
-		if (typeof chunk === "string") {
-			chunks.push(chunk);
-			return;
-		}
-		chunks.push(Buffer.from(chunk).toString(encoding));
-	};
-	const captureConsole = (chunks, args) => {
-		chunks.push(`${format(...args)}\n`);
-	};
-	const createWriteCapture = (chunks) => ((chunk, encoding, cb) => {
-		captureChunk(chunks, chunk, typeof encoding === "string" ? encoding : void 0);
-		if (typeof encoding === "function") encoding(null);
-		else cb?.(null);
-		return true;
-	});
-	process.stdout.write = createWriteCapture(stdoutChunks);
-	process.stderr.write = createWriteCapture(stderrChunks);
-	for (const method of [
-		"log",
-		"info",
-		"debug"
-	]) console[method] = (...args) => captureConsole(stdoutChunks, args);
-	for (const method of ["warn", "error"]) console[method] = (...args) => captureConsole(stderrChunks, args);
-	try {
-		return {
-			ok: true,
-			value: await action(),
-			stdout: stdoutChunks.join(""),
-			stderr: stderrChunks.join("")
-		};
-	} catch (error) {
-		return {
-			ok: false,
-			error,
-			stdout: stdoutChunks.join(""),
-			stderr: stderrChunks.join("")
-		};
-	} finally {
-		process.stdout.write = originalStdoutWrite;
-		process.stderr.write = originalStderrWrite;
-		Object.assign(console, originalConsoleMethods);
-	}
-}
 function formatTypeHint(field) {
 	return isSchemaField(field) ? "" : ` <${field.type}>`;
 }
@@ -442,4 +411,4 @@ async function parseCommand(command, rawArgs) {
 	};
 }
 //#endregion
-export { isSchemaField as a, isDefinedCommand as i, defineCommand as n, parseCommand as o, executeCommand as r, captureProcessOutput as t };
+export { isSchemaField as a, isDefinedCommand as i, defineGroup as n, parseCommand as o, executeCommand as r, defineCommand as t };

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

@@ -285,6 +285,33 @@ interface DefinedCommand<TArgsFields extends readonly CommandArgField[] = readon
  */
 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/define-group.d.ts
+/** The group definition object accepted by {@link defineGroup}. */
+interface DefineGroupInput {
+  /** One-line summary shown in `--help` output. */
+  readonly description: string;
+}
+/** The normalized group object returned by `defineGroup`. */
+interface DefinedGroup {
+  readonly description: string;
+}
+/**
+ * Defines metadata for a command group (a directory that only groups
+ * subcommands without being executable itself).
+ *
+ * Place the default export of this function in a `_group.ts` file inside a
+ * command directory.
+ *
+ * @example
+ * ```ts
+ * // src/commands/project/_group.ts
+ * export default defineGroup({
+ *   description: "Manage projects",
+ * });
+ * ```
+ */
+declare function defineGroup(input: DefineGroupInput): DefinedGroup;
+//#endregion
 //#region src/execute-command.d.ts
 interface ExecuteCommandInput<TOptions, TArgs> {
   readonly options?: TOptions | undefined;
@@ -293,4 +320,4 @@ interface ExecuteCommandInput<TOptions, TArgs> {
   readonly rawArgs?: readonly string[] | undefined;
 }
 //#endregion
-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 };
+export { DefinedCommand as a, InferExecutionFields as c, PrimitiveOptionField as d, SchemaArgField as f, defineGroup as h, DefineGroupInput as i, PrimitiveArgField as l, defineCommand as m, CommandContext as n, DefinedGroup as o, SchemaOptionField as p, CommandOptionField as r, ExecuteCommandInput as s, CommandArgField as t, PrimitiveFieldType as u };

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-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 };
+import { a as DefinedCommand, c as InferExecutionFields, d as PrimitiveOptionField, f as SchemaArgField, h as defineGroup, i as DefineGroupInput, l as PrimitiveArgField, m as defineCommand, n as CommandContext, o as DefinedGroup, p as SchemaOptionField, r as CommandOptionField, s as ExecuteCommandInput, t as CommandArgField, u as PrimitiveFieldType } from "./index-CHUchkja.mjs";
+export { type CommandArgField, type CommandContext, type CommandOptionField, type DefineGroupInput, type DefinedCommand, type DefinedGroup, type ExecuteCommandInput, type InferExecutionFields, type PrimitiveArgField, type PrimitiveFieldType, type PrimitiveOptionField, type SchemaArgField, type SchemaOptionField, defineCommand, defineGroup };

package/dist/index.mjs

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

package/dist/{run-manifest-command-BphalAwU.mjs → run-manifest-command-CSsdj02B.mjs}

@@ -1,4 +1,4 @@
-import { a as isSchemaField, i as isDefinedCommand, o as parseCommand, r as executeCommand } from "./dist-DuisScgY.mjs";
+import { a as isSchemaField, i as isDefinedCommand, o as parseCommand, r as executeCommand } from "./dist-CSbOseWZ.mjs";
 import { pathToFileURL } from "node:url";
 //#region src/cli/flags.ts
 function isHelpFlag(token) {
@@ -153,7 +153,10 @@ function renderGroupHelp(options) {
 			description: nodeMap[commandManifestPathToKey([...node.pathSegments, childName])]?.description
 		};
 	});
-	const parts = [`Usage: ${formatCommandName(cliName, node.pathSegments)} <command>`];
+	const commandName = formatCommandName(cliName, node.pathSegments);
+	const parts = [];
+	if (node.description) parts.push(node.description);
+	parts.push(`Usage: ${commandName} <command>`);
 	if (entries.length > 0) parts.push(`Subcommands:\n${formatSectionEntries(entries)}`);
 	const optionEntries = [{
 		label: "-h, --help",

package/dist/runtime.d.mts

@@ -1,4 +1,4 @@
-import { i as DefinedCommand, r as CommandOptionField, t as CommandArgField } from "./index-BWxfSwrT.mjs";
+import { a as DefinedCommand, r as CommandOptionField, t as CommandArgField } from "./index-CHUchkja.mjs";
 
 //#region src/manifest/manifest-types.d.ts
 type CommandManifestPath = readonly string[];

package/dist/runtime.mjs

@@ -1,3 +1,3 @@
-import "./dist-DuisScgY.mjs";
-import { t as runManifestCommand } from "./run-manifest-command-BphalAwU.mjs";
+import "./dist-CSbOseWZ.mjs";
+import { t as runManifestCommand } from "./run-manifest-command-CSsdj02B.mjs";
 export { runManifestCommand };

package/dist/test.d.mts

@@ -1,50 +1,267 @@
-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;
+//#region ../test-utils/dist/index.d.mts
+//#endregion
+//#region ../core/dist/index.d.mts
+//#region ../../node_modules/.pnpm/@standard-schema+spec@1.1.0/node_modules/@standard-schema/spec/dist/index.d.ts
+/** The Standard Typed interface. This is a base type extended by other specs. */
+interface StandardTypedV1<Input = unknown, Output = Input> {
+  /** The Standard properties. */
+  readonly "~standard": StandardTypedV1.Props<Input, Output>;
+}
+declare namespace StandardTypedV1 {
+  /** The Standard Typed properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The Standard Typed types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Typed. */
+  type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+  /** Infers the output type of a Standard Typed. */
+  type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined;
+  }
+  interface Options {
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard types interface. */
+  interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+  /** Infers the input type of a Standard. */
+  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+  /** Infers the output type of a Standard. */
+  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+/** The Standard JSON Schema interface. */
+//#endregion
+//#region src/command-types.d.ts
+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`.
+   *
+   * 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;
+}
+interface PrimitiveFieldBase<TName extends string, TType extends PrimitiveFieldType> extends NamedField<TName> {
+  /** Primitive type that Rune parses the raw CLI token into (`"string"`, `"number"`, or `"boolean"`). */
+  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`, 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`. */
+  readonly default?: PrimitiveFieldValue<TType> | undefined;
+  readonly schema?: never;
+}
+interface SchemaFieldBase<TName extends string, TSchema extends StandardSchemaV1 = StandardSchemaV1> extends NamedField<TName> {
+  /**
+   * A Standard Schema object (e.g. `z.string()`, `v.number()`) used to
+   * validate and transform the raw CLI token. Required/optional and default
+   * semantics are derived from the schema itself.
+   */
+  readonly schema: TSchema;
+  readonly type?: never;
+  readonly required?: never;
+  readonly default?: never;
+}
+interface PrimitiveArgField<TName extends string = string, TType extends PrimitiveFieldType = PrimitiveFieldType> extends PrimitiveFieldBase<TName, TType> {
+  readonly alias?: never;
+  readonly flag?: never;
+}
+interface SchemaArgField<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1> extends SchemaFieldBase<TName, TSchema> {
+  readonly alias?: never;
+  readonly flag?: never;
+}
+interface PrimitiveOptionField<TName extends string = string, TType extends PrimitiveFieldType = PrimitiveFieldType> extends PrimitiveFieldBase<TName, TType> {
+  /** Single-character shorthand (e.g. `"v"` for `--verbose` → `-v`). */
+  readonly alias?: string | undefined;
+  readonly flag?: never;
+}
+interface SchemaOptionField<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1> extends SchemaFieldBase<TName, TSchema> {
+  /** Single-character shorthand (e.g. `"v"` for `--verbose` → `-v`). */
+  readonly alias?: string | undefined;
+  /**
+   * When `true`, the option is parsed as a boolean flag (no value expected).
+   * The schema receives `true` when the flag is present, `undefined` when absent.
+   */
+  readonly flag?: true | undefined;
 }
+type CommandArgField = PrimitiveArgField | SchemaArgField;
+type CommandOptionField = PrimitiveOptionField | SchemaOptionField;
+type FieldName<TField> = TField extends {
+  readonly name: infer TName extends string;
+} ? TName : never;
+type InferSchemaOutput<TSchema> = TSchema extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<TSchema> : never;
+type InferSchemaInput<TSchema> = TSchema extends StandardSchemaV1 ? StandardSchemaV1.InferInput<TSchema> : never;
+type IsOptionalSchemaOutput<TValue> = undefined extends TValue ? true : false;
+type FieldValue<TField> = TField extends {
+  readonly schema: infer TSchema;
+} ? Exclude<InferSchemaOutput<TSchema>, undefined> : TField extends {
+  readonly type: infer TType extends PrimitiveFieldType;
+} ? PrimitiveFieldValue<TType> : never;
+type FieldInputValue<TField> = TField extends {
+  readonly schema: infer TSchema;
+} ? InferSchemaInput<TSchema> : TField extends {
+  readonly type: infer TType extends PrimitiveFieldType;
+} ? PrimitiveFieldValue<TType> : never;
+type HasDefaultValue<TField> = TField extends {
+  readonly default: infer TDefault;
+} ? [TDefault] extends [undefined] ? false : true : false;
+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 : TBooleanAlwaysPresent extends true ? TField extends {
+  readonly type: "boolean";
+} ? true : TField extends {
+  readonly required: true;
+} ? true : false : TField extends {
+  readonly required: true;
+} ? true : false;
+type Simplify<TValue> = { [TKey in keyof TValue]: TValue[TKey] };
+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> {
+  /** Parsed and validated positional argument values keyed by field name. */
+  readonly args: TArgs;
+  /** Parsed and validated option values keyed by field name. */
+  readonly options: TOptions;
+  /** Working directory the CLI was invoked from. */
+  readonly cwd: string;
+  /**
+   * Unparsed argv tokens passed to this command, before Rune splits them
+   * into `args` and `options`. Useful for forwarding to child processes.
+   */
+  readonly rawArgs: readonly string[];
+}
+/** The command definition object accepted by {@link defineCommand}. */
+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, true>, InferNamedFields<TArgsFields>>) => void | Promise<void>;
+} //#endregion
+//#region src/define-command.d.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.
+ * Defines a CLI command with a description, positional arguments, options,
+ * and a function to execute when the command is invoked.
  *
- * @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.
+ * The command module's default export should be the return value of this function.
  *
  * @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 }],
+ * export default defineCommand({
+ *   description: "Greet someone",
+ *   args: [
+ *     { name: "name", type: "string", required: true },
+ *   ],
+ *   options: [
+ *     { name: "loud", type: "boolean", alias: "l" },
+ *   ],
  *   run(ctx) {
- *     console.log(`Hello, ${ctx.options.name}!`);
+ *     const greeting = `Hello, ${ctx.args.name}!`;
+ *     console.log(ctx.options.loud ? greeting.toUpperCase() : greeting);
  *   },
  * });
+ * ```
  *
- * test("hello command", async () => {
- *   const result = await runCommand(hello, {
- *     options: { name: "Rune" },
- *   });
+ * Required positional arguments must precede optional ones. This ordering is
+ * enforced at the type level for concrete schema types and at runtime for
+ * primitive fields:
  *
- *   expect(result.exitCode).toBe(0);
- *   expect(result.stdout).toBe("Hello, Rune!\n");
+ * ```ts
+ * // Type error — required arg after optional arg
+ * defineCommand({
+ *   args: [
+ *     { name: "source", type: "string" },
+ *     { name: "target", type: "string", required: true },
+ *   ],
+ *   run() {},
+ * });
+ *
+ * // Type error — required primitive arg after optional schema arg
+ * defineCommand({
+ *   args: [
+ *     { name: "mode", schema: z.string().optional() },
+ *     { name: "target", type: "string", required: true },
+ *   ],
+ *   run() {},
  * });
  * ```
+ *
+ * When a schema type is widened to plain `StandardSchemaV1` (e.g. stored in
+ * a variable without a concrete type), optionality information is lost and
+ * the ordering check is skipped for that field.
  */
-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 { CommandExecutionResult, RunCommandOptions, runCommand };
+//#region src/execute-command.d.ts
+interface ExecuteCommandInput<TOptions, TArgs> {
+  readonly options?: TOptions | undefined;
+  readonly args?: TArgs | undefined;
+  readonly cwd?: string | undefined;
+  readonly rawArgs?: readonly string[] | undefined;
+} //#endregion
+//#region src/run-command.d.ts
+type RunCommandOptions<TOptions, TArgs> = ExecuteCommandInput<TOptions, TArgs>;
+interface CommandExecutionResult {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly errorMessage?: string | undefined;
+}
+declare function runCommand<TArgsFields extends readonly CommandArgField[], TOptionsFields extends readonly CommandOptionField[]>(command: DefinedCommand<TArgsFields, TOptionsFields>, options?: RunCommandOptions<InferExecutionFields<TOptionsFields>, InferExecutionFields<TArgsFields>>): Promise<CommandExecutionResult>; //#endregion
+//#endregion
+export { type CommandExecutionResult, type RunCommandOptions, runCommand };

package/dist/test.mjs

@@ -1,42 +1,88 @@
-import { r as executeCommand, t as captureProcessOutput } from "./dist-DuisScgY.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");
-* });
-* ```
-*/
+import { format } from "node:util";
+//#region ../test-utils/dist/index.mjs
+async function captureProcessOutput(action) {
+	const stdoutChunks = [];
+	const stderrChunks = [];
+	const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+	const originalStderrWrite = process.stderr.write.bind(process.stderr);
+	const originalConsoleMethods = {
+		log: console.log,
+		info: console.info,
+		debug: console.debug,
+		warn: console.warn,
+		error: console.error
+	};
+	const captureChunk = (chunks, chunk, encoding) => {
+		if (typeof chunk === "string") {
+			chunks.push(chunk);
+			return;
+		}
+		chunks.push(Buffer.from(chunk).toString(encoding));
+	};
+	const captureConsole = (chunks, args) => {
+		chunks.push(`${format(...args)}\n`);
+	};
+	const createWriteCapture = (chunks) => ((chunk, encoding, cb) => {
+		captureChunk(chunks, chunk, typeof encoding === "string" ? encoding : void 0);
+		if (typeof encoding === "function") encoding(null);
+		else cb?.(null);
+		return true;
+	});
+	process.stdout.write = createWriteCapture(stdoutChunks);
+	process.stderr.write = createWriteCapture(stderrChunks);
+	for (const method of [
+		"log",
+		"info",
+		"debug"
+	]) console[method] = (...args) => captureConsole(stdoutChunks, args);
+	for (const method of ["warn", "error"]) console[method] = (...args) => captureConsole(stderrChunks, args);
+	try {
+		return {
+			ok: true,
+			value: await action(),
+			stdout: stdoutChunks.join(""),
+			stderr: stderrChunks.join("")
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error,
+			stdout: stdoutChunks.join(""),
+			stderr: stderrChunks.join("")
+		};
+	} finally {
+		process.stdout.write = originalStdoutWrite;
+		process.stderr.write = originalStderrWrite;
+		Object.assign(console, originalConsoleMethods);
+	}
+}
+function isSchemaField(field) {
+	return "schema" in field && field.schema !== void 0;
+}
+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 runCommand(command, options = {}) {
 	const captured = await captureProcessOutput(() => executeCommand(command, options));
 	if (!captured.ok) throw captured.error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-cli/rune",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Rune is a CLI framework built around the concept of file-based command routing.",
   "homepage": "https://github.com/morinokami/rune#readme",
   "bugs": {
@@ -46,7 +46,8 @@
     "@typescript/native-preview": "7.0.0-dev.20260322.1",
     "typescript": "5.9.3",
     "vite-plus": "v0.1.13",
-    "@rune-cli/core": "0.0.0"
+    "@rune-cli/core": "0.0.0",
+    "@rune-cli/test-utils": "0.0.0"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"