@rune-cli/rune 0.0.9 → 0.0.11

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

@@ -117,21 +117,21 @@ interface SchemaFieldBase<TName extends string, TSchema extends StandardSchemaV1
   readonly default?: never;
 }
 interface PrimitiveArgField<TName extends string = string, TType extends PrimitiveFieldType = PrimitiveFieldType> extends PrimitiveFieldBase<TName, TType> {
-  readonly alias?: never;
+  readonly short?: never;
   readonly flag?: never;
 }
 interface SchemaArgField<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1> extends SchemaFieldBase<TName, TSchema> {
-  readonly alias?: never;
+  readonly short?: 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 short?: 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;
+  readonly short?: 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.
@@ -201,6 +201,12 @@ interface CommandContext<TOptions, TArgs> {
 interface DefineCommandInput<TArgsFields extends readonly CommandArgField[] | undefined = undefined, TOptionsFields extends readonly CommandOptionField[] | undefined = undefined> {
   /** One-line summary shown in `--help` output. */
   readonly description?: string | undefined;
+  /**
+   * Alternative names for this command. Each alias is an additional path
+   * segment that routes to this command. Aliases must follow kebab-case
+   * rules (lowercase letters, digits, and internal hyphens).
+   */
+  readonly aliases?: readonly string[] | undefined;
   /**
    * Positional arguments declared in the order they appear on the command line.
    * Required arguments must come before optional ones.
@@ -211,7 +217,7 @@ interface DefineCommandInput<TArgsFields extends readonly CommandArgField[] | un
    */
   readonly args?: TArgsFields;
   /**
-   * Options declared as `--name` flags, with optional single-character aliases.
+   * Options declared as `--name` flags, with optional single-character short forms.
    * Option names must be unique within the command, start with a letter, and
    * contain only letters, numbers, and internal hyphens.
    *
@@ -227,6 +233,7 @@ interface DefineCommandInput<TArgsFields extends readonly CommandArgField[] | un
 }
 interface DefinedCommand<TArgsFields extends readonly CommandArgField[] = readonly [], TOptionsFields extends readonly CommandOptionField[] = readonly []> {
   readonly description?: string | undefined;
+  readonly aliases: readonly string[];
   readonly args: TArgsFields;
   readonly options: TOptionsFields;
   readonly run: (ctx: CommandContext<InferNamedFields<TOptionsFields, true>, InferNamedFields<TArgsFields>>) => void | Promise<void>;
@@ -246,7 +253,7 @@ interface DefinedCommand<TArgsFields extends readonly CommandArgField[] = readon
  *     { name: "name", type: "string", required: true },
  *   ],
  *   options: [
- *     { name: "loud", type: "boolean", alias: "l" },
+ *     { name: "loud", type: "boolean", short: "l" },
  *   ],
  *   run(ctx) {
  *     const greeting = `Hello, ${ctx.args.name}!`;
@@ -285,6 +292,40 @@ 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;
+  /**
+   * Alternative names for this command group. Each alias is an additional path
+   * segment that routes to this group. Aliases must follow kebab-case rules
+   * (lowercase letters, digits, and internal hyphens).
+   */
+  readonly aliases?: readonly string[] | undefined;
+}
+/** The normalized group object returned by `defineGroup`. */
+interface DefinedGroup {
+  readonly description: string;
+  readonly aliases: readonly 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 +334,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-C179V2IJ.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-Bpf2xVvb.mjs";
+export { defineCommand, defineGroup };

package/dist/{run-manifest-command-BphalAwU.mjs → run-manifest-command-DepwxrFI.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 parseCommandArgs, r as executeCommand } from "./dist-Bpf2xVvb.mjs";
 import { pathToFileURL } from "node:url";
 //#region src/cli/flags.ts
 function isHelpFlag(token) {
@@ -8,7 +8,7 @@ function isVersionFlag(token) {
 	return token === "--version" || token === "-V";
 }
 //#endregion
-//#region src/manifest/command-loader.ts
+//#region src/manifest/runtime/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}`);
@@ -29,7 +29,23 @@ function describeCommandModuleExport(value) {
 }
 const defaultLoadCommand = (node) => loadCommandFromModule(node.sourceFilePath);
 //#endregion
-//#region src/manifest/damerau-levenshtein.ts
+//#region src/manifest/manifest-map.ts
+function commandManifestPathToKey(pathSegments) {
+	return pathSegments.join(" ");
+}
+function createCommandManifestNodeMap(manifest) {
+	const entries = [];
+	for (const node of manifest.nodes) {
+		entries.push([commandManifestPathToKey(node.pathSegments), node]);
+		if (node.aliases.length > 0 && node.pathSegments.length > 0) {
+			const parentSegments = node.pathSegments.slice(0, -1);
+			for (const alias of node.aliases) entries.push([commandManifestPathToKey([...parentSegments, alias]), node]);
+		}
+	}
+	return Object.fromEntries(entries);
+}
+//#endregion
+//#region src/manifest/runtime/damerau-levenshtein.ts
 function damerauLevenshteinDistance(left, right) {
 	const rows = left.length + 1;
 	const cols = right.length + 1;
@@ -44,15 +60,7 @@ 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
+//#region src/manifest/runtime/resolve-command-route.ts
 function isOptionLikeToken(token) {
 	return token === "--" || token.startsWith("-");
 }
@@ -62,13 +70,35 @@ function getHelpRequested(args) {
 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 getSuggestedChildNames(unknownSegment, candidates) {
+	const scored = candidates.map((candidate) => ({
+		canonicalName: candidate.canonicalName,
+		distance: damerauLevenshteinDistance(unknownSegment, candidate.matchName),
+		threshold: getSuggestionThreshold(candidate.matchName)
+	})).filter(({ distance, threshold }) => distance <= threshold);
+	const bestByCanonical = /* @__PURE__ */ new Map();
+	for (const entry of scored) {
+		const existing = bestByCanonical.get(entry.canonicalName);
+		if (existing === void 0 || entry.distance < existing) bestByCanonical.set(entry.canonicalName, entry.distance);
+	}
+	return [...bestByCanonical.entries()].sort(([nameA, distA], [nameB, distB]) => distA - distB || nameA.localeCompare(nameB)).slice(0, 3).map(([name]) => name);
+}
+function collectSiblingCandidates(currentNode, nodeMap) {
+	const candidates = [];
+	for (const childName of currentNode.childNames) {
+		candidates.push({
+			canonicalName: childName,
+			matchName: childName
+		});
+		const childNode = nodeMap[commandManifestPathToKey([...currentNode.pathSegments, childName])];
+		if (childNode) for (const alias of childNode.aliases) candidates.push({
+			canonicalName: childName,
+			matchName: alias
+		});
+	}
+	return candidates;
 }
-function resolveCommandPath(manifest, rawArgs) {
+function resolveCommandRoute(manifest, rawArgs) {
 	const nodeMap = createCommandManifestNodeMap(manifest);
 	const rootNode = nodeMap[""];
 	if (rootNode === void 0) throw new Error("Manifest root node is missing");
@@ -79,7 +109,7 @@ function resolveCommandPath(manifest, rawArgs) {
 		if (isOptionLikeToken(token)) break;
 		const childNode = nodeMap[commandManifestPathToKey([...currentNode.pathSegments, token])];
 		if (childNode === void 0) {
-			const suggestions = getSuggestedChildNames(token, currentNode.childNames);
+			const suggestions = getSuggestedChildNames(token, collectSiblingCandidates(currentNode, nodeMap));
 			if (currentNode.kind === "group" || suggestions.length > 0) return {
 				kind: "unknown",
 				attemptedPath: [...currentNode.pathSegments, token],
@@ -111,7 +141,7 @@ function resolveCommandPath(manifest, rawArgs) {
 	};
 }
 //#endregion
-//#region src/manifest/render-help.ts
+//#region src/manifest/runtime/render-help.ts
 function formatCommandName(cliName, pathSegments) {
 	return pathSegments.length === 0 ? cliName : `${cliName} ${pathSegments.join(" ")}`;
 }
@@ -126,8 +156,8 @@ function formatArgumentLabel(field) {
 }
 function formatOptionLabel(field) {
 	const longOptionLabel = `--${field.name}${formatTypeHint(field)}`;
-	if (!field.alias) return longOptionLabel;
-	return `-${field.alias}, ${longOptionLabel}`;
+	if (!field.short) return longOptionLabel;
+	return `-${field.short}, ${longOptionLabel}`;
 }
 async function isFieldRequired(field) {
 	if (!isSchemaField(field)) return field.required === true && field.default === void 0;
@@ -148,12 +178,16 @@ function renderGroupHelp(options) {
 	const { manifest, node, cliName, version } = options;
 	const nodeMap = createCommandManifestNodeMap(manifest);
 	const entries = node.childNames.map((childName) => {
+		const childNode = nodeMap[commandManifestPathToKey([...node.pathSegments, childName])];
 		return {
-			label: childName,
-			description: nodeMap[commandManifestPathToKey([...node.pathSegments, childName])]?.description
+			label: `${childName}${childNode && childNode.aliases.length > 0 ? ` (${childNode.aliases.join(", ")})` : ""}`,
+			description: childNode?.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",
@@ -194,7 +228,7 @@ function renderUnknownCommandMessage(route, cliName) {
 	return `${parts.join("\n\n")}\n`;
 }
 //#endregion
-//#region src/manifest/resolve-help.ts
+//#region src/manifest/runtime/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({
@@ -206,7 +240,7 @@ async function renderResolvedHelp(options) {
 	return renderCommandHelp(await (options.loadCommand ?? defaultLoadCommand)(options.route.node), options.route.matchedPath, options.cliName);
 }
 //#endregion
-//#region src/manifest/run-manifest-command.ts
+//#region src/manifest/runtime/run-manifest-command.ts
 function ensureTrailingNewline(text) {
 	return text.endsWith("\n") ? text : `${text}\n`;
 }
@@ -221,7 +255,7 @@ async function runManifestCommand(options) {
 			process.stdout.write(`${options.cliName} v${options.version}\n`);
 			return 0;
 		}
-		const route = resolveCommandPath(options.manifest, options.rawArgs);
+		const route = resolveCommandRoute(options.manifest, options.rawArgs);
 		if (route.kind === "unknown" || route.kind === "group" || route.helpRequested) {
 			const output = await renderResolvedHelp({
 				manifest: options.manifest,
@@ -238,16 +272,16 @@ async function runManifestCommand(options) {
 			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));
+		const commandInput = await parseCommandArgs(command, route.remainingArgs);
+		if (!commandInput.ok) {
+			process.stderr.write(ensureTrailingNewline(commandInput.error.message));
 			return 1;
 		}
 		const result = await executeCommand(command, {
-			options: parsed.value.options,
-			args: parsed.value.args,
+			options: commandInput.value.options,
+			args: commandInput.value.args,
 			cwd: options.cwd,
-			rawArgs: parsed.value.rawArgs
+			rawArgs: commandInput.value.rawArgs
 		});
 		if (result.errorMessage) process.stderr.write(ensureTrailingNewline(result.errorMessage));
 		return result.exitCode;

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-C179V2IJ.mjs";
 
 //#region src/manifest/manifest-types.d.ts
 type CommandManifestPath = readonly string[];
@@ -7,6 +7,7 @@ interface CommandManifestNodeBase {
   readonly pathSegments: CommandManifestPath;
   readonly kind: CommandManifestNodeKind;
   readonly childNames: readonly string[];
+  readonly aliases: readonly string[];
   readonly description?: string | undefined;
 }
 interface CommandManifestCommandNode extends CommandManifestNodeBase {
@@ -22,10 +23,10 @@ interface CommandManifest {
   readonly nodes: readonly CommandManifestNode[];
 }
 //#endregion
-//#region src/manifest/command-loader.d.ts
+//#region src/manifest/runtime/command-loader.d.ts
 type LoadCommandFn = (node: CommandManifestCommandNode) => Promise<DefinedCommand<readonly CommandArgField[], readonly CommandOptionField[]>>;
 //#endregion
-//#region src/manifest/run-manifest-command.d.ts
+//#region src/manifest/runtime/run-manifest-command.d.ts
 interface RunManifestCommandOptions {
   readonly manifest: CommandManifest;
   readonly rawArgs: 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-Bpf2xVvb.mjs";
+import { t as runManifestCommand } from "./run-manifest-command-DepwxrFI.mjs";
 export { runManifestCommand };

package/dist/test.d.mts

@@ -1,6 +1,210 @@
-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
+//#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 short?: never;
+  readonly flag?: never;
+}
+interface SchemaArgField<TName extends string = string, TSchema extends StandardSchemaV1 = StandardSchemaV1> extends SchemaFieldBase<TName, TSchema> {
+  readonly short?: 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 short?: 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 short?: 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 aliases: readonly string[];
+  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
+//#endregion
+//#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;
@@ -8,43 +212,6 @@ interface CommandExecutionResult {
   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>;
+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 { CommandExecutionResult, RunCommandOptions, runCommand };
+export { type CommandExecutionResult, type RunCommandOptions, runCommand };