@rune-cli/rune 0.0.10 → 0.0.11

package/dist/cli.mjs

@@ -1,83 +1,111 @@
 #!/usr/bin/env node
-import "./dist-CSbOseWZ.mjs";
-import { n as isHelpFlag, r as isVersionFlag, t as runManifestCommand } from "./run-manifest-command-CSsdj02B.mjs";
+import "./dist-Bpf2xVvb.mjs";
+import { n as isHelpFlag, r as isVersionFlag, t as runManifestCommand } from "./run-manifest-command-DepwxrFI.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.10";
+var version = "0.0.11";
 //#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) {
-		const comparison = left[index].localeCompare(right[index]);
-		if (comparison !== 0) return comparison;
-	}
-	return left.length - right.length;
-}
+//#region src/manifest/generate/extract-description.ts
 function getPropertyNameText(name) {
 	if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
 }
-function getStaticDescriptionValue(expression) {
+function getStaticStringValue(expression) {
 	if (ts.isStringLiteral(expression) || ts.isNoSubstitutionTemplateLiteral(expression)) return expression.text;
 }
+function getStaticStringArrayValue(expression) {
+	if (!ts.isArrayLiteralExpression(expression)) return;
+	const values = [];
+	for (const element of expression.elements) {
+		const value = getStaticStringValue(element);
+		if (value === void 0) return;
+		values.push(value);
+	}
+	return values;
+}
+function resolveExpression(expression, sourceFile) {
+	if (ts.isIdentifier(expression)) return findVariableInitializer(sourceFile, expression.text) ?? expression;
+	return expression;
+}
 function isDefineCommandExpression(expression) {
 	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);
+function extractMetadataFromCommandDefinition(expression, sourceFile, knownMetadata) {
+	if (ts.isIdentifier(expression)) return knownMetadata.get(expression.text);
 	if (!ts.isCallExpression(expression) || !isDefineCallExpression(expression)) return;
 	const [definition] = expression.arguments;
 	if (!definition || !ts.isObjectLiteralExpression(definition)) return;
+	let description;
+	let aliases = [];
 	for (const property of definition.properties) {
+		if (ts.isShorthandPropertyAssignment(property)) {
+			const propertyName = property.name.text;
+			const resolved = resolveExpression(property.name, sourceFile);
+			if (propertyName === "description") description = getStaticStringValue(resolved);
+			else if (propertyName === "aliases") {
+				const extracted = getStaticStringArrayValue(resolved);
+				if (extracted === void 0) throw new Error("Could not statically analyze aliases. Aliases must be an inline array of string literals (e.g. aliases: [\"d\"]).");
+				aliases = extracted;
+			}
+			continue;
+		}
 		if (!ts.isPropertyAssignment(property)) continue;
-		if (getPropertyNameText(property.name) !== "description") continue;
-		return getStaticDescriptionValue(property.initializer);
+		const propertyName = getPropertyNameText(property.name);
+		const resolved = resolveExpression(property.initializer, sourceFile);
+		if (propertyName === "description") description = getStaticStringValue(resolved);
+		else if (propertyName === "aliases") {
+			const extracted = getStaticStringArrayValue(resolved);
+			if (extracted === void 0) throw new Error("Could not statically analyze aliases. Aliases must be an inline array of string literals (e.g. aliases: [\"d\"]).");
+			aliases = extracted;
+		}
 	}
+	return {
+		description,
+		aliases
+	};
+}
+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;
+	}
+}
+function isNamedCallExpression(expression, name) {
+	if (ts.isIdentifier(expression)) return expression.text === name;
+	if (ts.isPropertyAccessExpression(expression)) return expression.name.text === name;
+	return false;
 }
-async function extractDescriptionFromSourceFile(sourceFilePath) {
+async function extractMetadataFromSourceFile(sourceFilePath) {
 	const sourceText = await readFile(sourceFilePath, "utf8");
 	const sourceFile = ts.createSourceFile(sourceFilePath, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-	const knownDescriptions = /* @__PURE__ */ new Map();
+	const knownMetadata = /* @__PURE__ */ new Map();
 	for (const statement of sourceFile.statements) {
 		if (ts.isVariableStatement(statement)) {
 			for (const declaration of statement.declarationList.declarations) {
 				if (!ts.isIdentifier(declaration.name) || !declaration.initializer) continue;
-				knownDescriptions.set(declaration.name.text, extractDescriptionFromCommandDefinition(declaration.initializer, knownDescriptions));
+				knownMetadata.set(declaration.name.text, extractMetadataFromCommandDefinition(declaration.initializer, sourceFile, knownMetadata));
 			}
 			continue;
 		}
-		if (ts.isExportAssignment(statement)) return extractDescriptionFromCommandDefinition(statement.expression, knownDescriptions);
+		if (ts.isExportAssignment(statement)) return extractMetadataFromCommandDefinition(statement.expression, sourceFile, knownMetadata);
 	}
 }
+//#endregion
+//#region src/manifest/generate/validate-group-meta.ts
 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.isVariableStatement(statement) || 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;
@@ -86,19 +114,45 @@ async function validateGroupMetaFile(sourceFilePath) {
 	}
 	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;
+//#endregion
+//#region src/manifest/generate/walk-commands-directory.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) {
+		const comparison = left[index].localeCompare(right[index]);
+		if (comparison !== 0) return comparison;
+	}
+	return left.length - right.length;
+}
+function validateSiblingAliases(siblings) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const sibling of siblings) {
+		const existing = seen.get(sibling.name);
+		if (existing !== void 0) throw new Error(`Command name conflict: "${sibling.name}" is already used by "${existing}".`);
+		seen.set(sibling.name, sibling.name);
+		for (const alias of sibling.aliases) {
+			if (alias === sibling.name) throw new Error(`Command alias "${alias}" for "${sibling.name}" is the same as its canonical name.`);
+			const conflicting = seen.get(alias);
+			if (conflicting !== void 0) throw new Error(`Command alias conflict: alias "${alias}" for "${sibling.name}" conflicts with "${conflicting}".`);
+			seen.set(alias, sibling.name);
+		}
 	}
 }
-async function walkCommandsDirectory(absoluteDirectoryPath, pathSegments, extractDescription) {
+async function walkCommandsDirectory(absoluteDirectoryPath, pathSegments, extractMetadata) {
 	const entries = await readdir(absoluteDirectoryPath, { withFileTypes: true });
 	const childDirectoryNames = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
 	const childResults = await Promise.all(childDirectoryNames.map(async (directoryName) => {
 		return {
 			directoryName,
-			result: await walkCommandsDirectory(path.join(absoluteDirectoryPath, directoryName), [...pathSegments, directoryName], extractDescription)
+			result: await walkCommandsDirectory(path.join(absoluteDirectoryPath, directoryName), [...pathSegments, directoryName], extractMetadata)
 		};
 	}));
 	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));
@@ -107,58 +161,86 @@ async function walkCommandsDirectory(absoluteDirectoryPath, pathSegments, extrac
 		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);
+		const metadata = await extractMetadata(sourceFilePath);
 		return {
 			pathSegments: [...pathSegments, commandName],
 			kind: "command",
 			sourceFilePath,
 			childNames: [],
-			description: await extractDescription(sourceFilePath)
+			aliases: metadata?.aliases ?? [],
+			description: metadata?.description
 		};
 	}));
-	const childNodes = childResults.flatMap(({ result }) => result.nodes);
+	const descendantNodes = childResults.flatMap(({ result }) => result.nodes);
 	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);
 	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],
+		nodes: [...descendantNodes, ...bareCommandNodes],
 		hasNode: false
 	};
 	let node;
 	if (hasCommandEntry) {
 		const sourceFilePath = path.join(absoluteDirectoryPath, COMMAND_ENTRY_FILE);
+		const metadata = await extractMetadata(sourceFilePath);
+		const aliases = metadata?.aliases ?? [];
+		if (aliases.length > 0 && pathSegments.length === 0) throw new Error("Aliases on the root command are not supported. The root command has no parent to resolve aliases against.");
 		node = {
 			pathSegments,
 			kind: "command",
 			sourceFilePath,
 			childNames,
-			description: await extractDescription(sourceFilePath)
+			aliases,
+			description: metadata?.description
 		};
 	} 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.`);
+		const metadata = hasGroupMeta ? await extractMetadata(groupMetaPath) : void 0;
+		if (hasGroupMeta && !metadata?.description) throw new Error(`${groupMetaPath}: _group.ts must export a defineGroup() call with a non-empty "description" string.`);
+		const aliases = metadata?.aliases ?? [];
+		if (aliases.length > 0 && pathSegments.length === 0) throw new Error("Aliases on the root group are not supported. The root group has no parent to resolve aliases against.");
 		node = {
 			pathSegments,
 			kind: "group",
 			childNames,
-			...description !== void 0 ? { description } : {}
+			aliases,
+			...metadata?.description !== void 0 ? { description: metadata.description } : {}
 		};
 	}
+	const siblingEntries = [];
+	for (const childResult of childResults) {
+		if (!childResult.result.hasNode) continue;
+		const childNode = childResult.result.nodes.find((n) => n.pathSegments.length === pathSegments.length + 1 && n.pathSegments[pathSegments.length] === childResult.directoryName);
+		siblingEntries.push({
+			name: childResult.directoryName,
+			aliases: childNode?.aliases ?? []
+		});
+	}
+	for (const bareNode of bareCommandNodes) {
+		const name = bareNode.pathSegments[bareNode.pathSegments.length - 1];
+		siblingEntries.push({
+			name,
+			aliases: bareNode.aliases
+		});
+	}
+	validateSiblingAliases(siblingEntries);
 	return {
 		nodes: [
 			node,
-			...childNodes,
+			...descendantNodes,
 			...bareCommandNodes
 		],
 		hasNode: true
 	};
 }
+//#endregion
+//#region src/manifest/generate/generate-manifest.ts
 async function generateCommandManifest(options) {
-	const extractDescription = options.extractDescription ?? extractDescriptionFromSourceFile;
-	const walkResult = await walkCommandsDirectory(options.commandsDirectory, [], extractDescription);
+	const extractMetadata = options.extractMetadata ?? extractMetadataFromSourceFile;
+	const walkResult = await walkCommandsDirectory(options.commandsDirectory, [], extractMetadata);
 	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)) };
 }
@@ -183,19 +265,20 @@ function resolveCommandsDirectory(projectRoot) {
 function resolveDistDirectory(projectRoot) {
 	return path.join(projectRoot, DIST_DIRECTORY_NAME);
 }
+function resolveCliNameFromPackageJson(packageJson) {
+	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 (packageJson.name && packageJson.name.length > 0) return packageJson.name.split("/").at(-1) ?? packageJson.name;
+}
 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) name = binNames[0];
-		}
-		if (!name && packageJson.name && packageJson.name.length > 0) name = packageJson.name.split("/").at(-1) ?? packageJson.name;
 		return {
-			name: name ?? path.basename(projectRoot),
+			name: resolveCliNameFromPackageJson(packageJson) ?? path.basename(projectRoot),
 			version: packageJson.version
 		};
 	} catch (error) {
@@ -542,6 +625,19 @@ function tryParseProjectOption(argv, index) {
 function getRuneVersion() {
 	return version;
 }
+function renderRuneCliHelp() {
+	return `\
+Usage: rune <command>
+
+Commands:
+  build  Build a Rune project into a distributable CLI
+  dev    Run a Rune project in development mode
+
+Options:
+  -h, --help     Show this help message
+  -V, --version  Show the version number
+`;
+}
 function parseDevArgs(argv) {
 	const commandArgs = [];
 	let projectPath;
@@ -610,18 +706,22 @@ function parseBuildArgs(argv) {
 		projectPath
 	};
 }
-function renderRuneCliHelp() {
-	return `\
-Usage: rune <command>
-
-Commands:
-  build  Build a Rune project into a distributable CLI
-  dev    Run a Rune project in development mode
-
-Options:
-  -h, --help     Show this help message
-  -V, --version  Show the version number
-`;
+async function runDevSubcommand(options, restArgs) {
+	const parsedDevArgs = parseDevArgs(restArgs);
+	if (!parsedDevArgs.ok) return writeEarlyExit(parsedDevArgs);
+	return runDevCommand({
+		rawArgs: parsedDevArgs.commandArgs,
+		projectPath: parsedDevArgs.projectPath,
+		cwd: options.cwd
+	});
+}
+async function runBuildSubcommand(options, restArgs) {
+	const parsedBuildArgs = parseBuildArgs(restArgs);
+	if (!parsedBuildArgs.ok) return writeEarlyExit(parsedBuildArgs);
+	return runBuildCommand({
+		projectPath: parsedBuildArgs.projectPath,
+		cwd: options.cwd
+	});
 }
 async function runRuneCli(options) {
 	const [subcommand, ...restArgs] = options.argv;
@@ -633,23 +733,8 @@ async function runRuneCli(options) {
 		await writeStdout(`rune v${getRuneVersion()}\n`);
 		return 0;
 	}
-	if (subcommand === "dev") {
-		const parsedDevArgs = parseDevArgs(restArgs);
-		if (!parsedDevArgs.ok) return writeEarlyExit(parsedDevArgs);
-		return runDevCommand({
-			rawArgs: parsedDevArgs.commandArgs,
-			projectPath: parsedDevArgs.projectPath,
-			cwd: options.cwd
-		});
-	}
-	if (subcommand === "build") {
-		const parsedBuildArgs = parseBuildArgs(restArgs);
-		if (!parsedBuildArgs.ok) return writeEarlyExit(parsedBuildArgs);
-		return runBuildCommand({
-			projectPath: parsedBuildArgs.projectPath,
-			cwd: options.cwd
-		});
-	}
+	if (subcommand === "dev") return runDevSubcommand(options, restArgs);
+	if (subcommand === "build") return runBuildSubcommand(options, restArgs);
 	await writeStderrLine(`Unknown command: ${subcommand}. Available commands: build, dev`);
 	return 1;
 }

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

@@ -5,7 +5,8 @@ function isSchemaField(field) {
 }
 const DEFINED_COMMAND_BRAND = Symbol.for("@rune-cli/defined-command");
 const OPTION_NAME_RE = /^[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*$/;
-const ALIAS_RE = /^[a-zA-Z]$/;
+const OPTION_SHORT_RE = /^[a-zA-Z]$/;
+const COMMAND_ALIAS_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function validateFieldShape(fields, kind) {
 	for (const field of fields) {
 		const raw = field;
@@ -23,13 +24,21 @@ function validateUniqueFieldNames(fields, kind) {
 function validateOptionNames(options) {
 	for (const field of options) if (!OPTION_NAME_RE.test(field.name)) throw new Error(`Invalid option name "${field.name}". Option names must start with a letter and contain only letters, numbers, and internal hyphens.`);
 }
-function validateOptionAliases(options) {
+function validateOptionShortNames(options) {
 	const seen = /* @__PURE__ */ new Set();
 	for (const field of options) {
-		if (field.alias === void 0) continue;
-		if (!ALIAS_RE.test(field.alias)) throw new Error(`Invalid alias "${field.alias}" for option "${field.name}". Alias must be a single letter.`);
-		if (seen.has(field.alias)) throw new Error(`Duplicate alias "${field.alias}" for option "${field.name}".`);
-		seen.add(field.alias);
+		if (field.short === void 0) continue;
+		if (!OPTION_SHORT_RE.test(field.short)) throw new Error(`Invalid short name "${field.short}" for option "${field.name}". Short name must be a single letter.`);
+		if (seen.has(field.short)) throw new Error(`Duplicate short name "${field.short}" for option "${field.name}".`);
+		seen.add(field.short);
+	}
+}
+function validateCommandAliases(aliases) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const alias of aliases) {
+		if (!COMMAND_ALIAS_RE.test(alias)) throw new Error(`Invalid command alias "${alias}". Aliases must be lowercase kebab-case (letters, digits, and internal hyphens).`);
+		if (seen.has(alias)) throw new Error(`Duplicate command alias "${alias}".`);
+		seen.add(alias);
 	}
 }
 function isOptionalArg(field) {
@@ -59,7 +68,7 @@ function validateArgOrdering(args) {
 *     { 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}!`;
@@ -98,6 +107,7 @@ function validateArgOrdering(args) {
 */
 function defineCommand(input) {
 	if (typeof input.run !== "function") throw new Error("defineCommand() requires a \"run\" function.");
+	if (input.aliases) validateCommandAliases(input.aliases);
 	if (input.args) {
 		validateFieldShape(input.args, "argument");
 		validateUniqueFieldNames(input.args, "argument");
@@ -107,10 +117,11 @@ function defineCommand(input) {
 		validateFieldShape(input.options, "option");
 		validateUniqueFieldNames(input.options, "option");
 		validateOptionNames(input.options);
-		validateOptionAliases(input.options);
+		validateOptionShortNames(input.options);
 	}
 	const command = {
 		description: input.description,
+		aliases: input.aliases ?? [],
 		args: input.args ?? [],
 		options: input.options ?? [],
 		run: input.run
@@ -142,7 +153,11 @@ const DEFINED_GROUP_BRAND = Symbol.for("@rune-cli/defined-group");
 */
 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 };
+	if (input.aliases) validateCommandAliases(input.aliases);
+	const group = {
+		description: input.description,
+		aliases: input.aliases ?? []
+	};
 	Object.defineProperty(group, DEFINED_GROUP_BRAND, {
 		value: true,
 		enumerable: false
@@ -154,12 +169,15 @@ function formatExecutionError(error) {
 	if (typeof error === "string") return error;
 	return "Unknown error";
 }
+function createExecutionOptions(command, input) {
+	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;
+	return options;
+}
 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,
+			options: createExecutionOptions(command, input),
 			args: input.args ?? {},
 			cwd: input.cwd ?? process.cwd(),
 			rawArgs: input.rawArgs ?? []
@@ -346,9 +364,9 @@ function getOptionParseType(field) {
 }
 function buildParseArgsOptions(options) {
 	const config = {};
-	for (const field of options) config[field.name] = field.alias ? {
+	for (const field of options) config[field.name] = field.short ? {
 		type: getOptionParseType(field),
-		short: field.alias
+		short: field.short
 	} : { type: getOptionParseType(field) };
 	return config;
 }
@@ -364,7 +382,7 @@ function detectDuplicateOption(options, tokens) {
 		}
 	}
 }
-async function parseCommand(command, rawArgs) {
+async function parseCommandArgs(command, rawArgs) {
 	let parsed;
 	try {
 		parsed = parseArgs({
@@ -411,4 +429,4 @@ async function parseCommand(command, rawArgs) {
 	};
 }
 //#endregion
-export { isSchemaField as a, isDefinedCommand as i, defineGroup as n, parseCommand as o, executeCommand as r, defineCommand as t };
+export { isSchemaField as a, isDefinedCommand as i, defineGroup as n, parseCommandArgs as o, executeCommand as r, defineCommand as t };

package/dist/{index-CHUchkja.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}!`;
@@ -290,10 +297,17 @@ declare function defineCommand<const TArgsFields extends readonly CommandArgFiel
 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

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-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";
+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 defineGroup, t as defineCommand } from "./dist-CSbOseWZ.mjs";
+import { n as defineGroup, t as defineCommand } from "./dist-Bpf2xVvb.mjs";
 export { defineCommand, defineGroup };

package/dist/{run-manifest-command-CSsdj02B.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-CSbOseWZ.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,9 +178,10 @@ 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 commandName = formatCommandName(cliName, node.pathSegments);
@@ -197,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({
@@ -209,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`;
 }
@@ -224,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,
@@ -241,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 { a as DefinedCommand, r as CommandOptionField, t as CommandArgField } from "./index-CHUchkja.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-CSbOseWZ.mjs";
-import { t as runManifestCommand } from "./run-manifest-command-CSsdj02B.mjs";
+import "./dist-Bpf2xVvb.mjs";
+import { t as runManifestCommand } from "./run-manifest-command-DepwxrFI.mjs";
 export { runManifestCommand };

package/dist/test.d.mts

@@ -119,21 +119,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.
@@ -190,62 +190,12 @@ interface CommandContext<TOptions, TArgs> {
 /** 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
-/**
- * Defines a CLI command with a description, positional arguments, options,
- * and a function to execute when the command is invoked.
- *
- * The command module's default export should be the return value of this function.
- *
- * @example
- * ```ts
- * export default defineCommand({
- *   description: "Greet someone",
- *   args: [
- *     { name: "name", type: "string", required: true },
- *   ],
- *   options: [
- *     { name: "loud", type: "boolean", alias: "l" },
- *   ],
- *   run(ctx) {
- *     const greeting = `Hello, ${ctx.args.name}!`;
- *     console.log(ctx.options.loud ? greeting.toUpperCase() : greeting);
- *   },
- * });
- * ```
- *
- * 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:
- *
- * ```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.
- */
 //#endregion
 //#region src/execute-command.d.ts
 interface ExecuteCommandInput<TOptions, TArgs> {

package/dist/test.mjs

@@ -64,12 +64,15 @@ function formatExecutionError(error) {
 	if (typeof error === "string") return error;
 	return "Unknown error";
 }
+function createExecutionOptions(command, input) {
+	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;
+	return options;
+}
 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,
+			options: createExecutionOptions(command, input),
 			args: input.args ?? {},
 			cwd: input.cwd ?? process.cwd(),
 			rawArgs: input.rawArgs ?? []

package/package.json

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