alepha 0.14.0 → 0.14.2

package/dist/command/index.js

@@ -2,10 +2,11 @@ import { $atom, $env, $hook, $inject, $module, $use, Alepha, AlephaError, KIND,
 import { stdin, stdout } from "node:process";
 import { createInterface } from "node:readline/promises";
 import { $logger } from "alepha/logger";
+import * as fs from "node:fs/promises";
+import { cp, glob, readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
 import { DateTimeProvider } from "alepha/datetime";
 import { exec } from "node:child_process";
-import * as fs from "node:fs/promises";
-import { cp, glob, rm } from "node:fs/promises";
 
 //#region ../../src/command/helpers/Asker.ts
 var Asker = class {
@@ -60,6 +61,35 @@ var Asker = class {
 	}
 };
 
+//#endregion
+//#region ../../src/command/helpers/EnvUtils.ts
+var EnvUtils = class {
+	log = $logger();
+	/**
+	* Load environment variables from .env files into process.env.
+	* By default, it loads from ".env" and ".env.local".
+	* You can specify additional files to load, e.g. [".env", ".env.production"].
+	*/
+	async loadEnv(root, files = [".env"]) {
+		for (const it of files) for (const file of [it, `${it}.local`]) {
+			const envPath = join(root, file);
+			try {
+				const lines = (await readFile(envPath, "utf8")).split("\n");
+				for (const line of lines) {
+					const [key, ...rest] = line.split("=");
+					if (key) {
+						const value = rest.join("=");
+						process.env[key.trim()] = value.trim();
+					}
+				}
+				this.log.debug(`Loaded environment variables from ${envPath}`);
+			} catch {
+				this.log.debug(`No ${file} file found at ${envPath}, skipping load.`);
+			}
+		}
+	}
+};
+
 //#endregion
 //#region ../../src/command/helpers/PrettyPrint.ts
 var PrettyPrint = class {
@@ -358,6 +388,7 @@ var Runner = class {
 const $command = (options) => createPrimitive(CommandPrimitive, options);
 var CommandPrimitive = class extends Primitive {
 	flags = this.options.flags ?? t.object({});
+	env = this.options.env ?? t.object({});
 	aliases = this.options.aliases ?? [];
 	onInit() {
 		if (this.options.pre || this.options.post) this.options.hide ??= true;
@@ -368,6 +399,24 @@ var CommandPrimitive = class extends Primitive {
 		if (this.options.post) return `post${this.options.post}`;
 		return this.options.name ?? `${this.config.propertyKey}`;
 	}
+	/**
+	* Get the child commands (subcommands) for this command.
+	*/
+	get children() {
+		return this.options.children ?? [];
+	}
+	/**
+	* Check if this command has child commands (is a parent command).
+	*/
+	get hasChildren() {
+		return this.children.length > 0;
+	}
+	/**
+	* Find a child command by name or alias.
+	*/
+	findChild(name) {
+		return this.children.find((child) => child.name === name || child.aliases.includes(name));
+	}
 };
 $command[KIND] = CommandPrimitive;
 
@@ -401,6 +450,7 @@ var CliProvider = class {
 	log = $logger();
 	runner = $inject(Runner);
 	asker = $inject(Asker);
+	envUtils = $inject(EnvUtils);
 	options = $use(cliOptions);
 	get name() {
 		return this.options.name || this.env.CLI_NAME;
@@ -420,8 +470,8 @@ var CliProvider = class {
 		on: "ready",
 		handler: async () => {
 			const argv = [...this.argv];
-			const commandName = argv.find((arg) => !arg.startsWith("-")) ?? "";
-			let command = this.findCommand(commandName);
+			const positionalArgs = argv.filter((arg) => !arg.startsWith("-"));
+			const { command, consumedArgs } = this.resolveCommand(positionalArgs);
 			if (this.parseFlags(argv, Object.entries(this.getAllGlobalFlags()).map(([key, value]) => ({
 				key,
 				...value
@@ -431,49 +481,124 @@ var CliProvider = class {
 			}
 			if (!command) {
 				const rootCommand = this.findCommand("");
-				if (rootCommand?.options.args) command = rootCommand;
-				else {
-					if (commandName !== "") {
-						this.log.error(`Unknown command: '${commandName}'`);
-						this.printHelp();
-					}
+				const commandName = positionalArgs[0] ?? "";
+				if (commandName !== "" && !rootCommand?.options.args) {
+					this.log.error(`Unknown command: '${commandName}'`);
+					this.printHelp();
 					return;
 				}
-			}
-			const commandFlags = this.parseCommandFlags(argv, command.flags);
-			const commandArgs = this.parseCommandArgs(argv, command.options.args, command.name === "", command.flags);
-			await this.alepha.context.run(async () => {
-				this.log.debug(`Executing command '${command.name}'...`, {
-					flags: commandFlags,
-					args: commandArgs
-				});
-				const runner = this.runner;
-				runner.startCommand(this.name, command.name);
-				const args = {
-					flags: commandFlags,
-					args: commandArgs,
-					run: runner.run,
-					ask: this.asker.ask,
-					fs,
-					glob,
-					root: process.cwd()
-				};
-				const preHooks = this.findPreHooks(command.name);
-				for (const hook of preHooks) {
-					this.log.debug(`Executing pre-hook for '${command.name}'...`);
-					await hook.options.handler(args);
-				}
-				await command.options.handler(args);
-				const postHooks = this.findPostHooks(command.name);
-				for (const hook of postHooks) {
-					this.log.debug(`Executing post-hook for '${command.name}'...`);
-					await hook.options.handler(args);
+				if (rootCommand) {
+					await this.executeCommand(rootCommand, argv, true);
+					return;
 				}
-				if (command.options.summary !== false) runner.summary();
-				this.log.debug(`Command '${command.name}' executed successfully.`);
-			});
+				return;
+			}
+			const remainingArgv = this.removeConsumedArgs(argv, consumedArgs);
+			await this.executeCommand(command, remainingArgv, true);
 		}
 	});
+	/**
+	* Execute a command with the given argv.
+	*/
+	async executeCommand(command, argv, isRootCommand) {
+		const root = process.cwd();
+		let modeValue;
+		if (command.options.mode) {
+			modeValue = this.parseModeFlag(argv);
+			if (modeValue === void 0 && typeof command.options.mode === "string") modeValue = command.options.mode;
+			await this.loadModeEnv(root, modeValue);
+		}
+		const commandFlags = this.parseCommandFlags(argv, command.flags);
+		const commandArgs = this.parseCommandArgs(argv, command.options.args, isRootCommand, command.flags);
+		const commandEnv = this.parseCommandEnv(command.env, command.name);
+		await this.alepha.context.run(async () => {
+			this.log.debug(`Executing command '${command.name}'...`, {
+				flags: commandFlags,
+				args: commandArgs,
+				mode: modeValue
+			});
+			const runner = this.runner;
+			runner.startCommand(this.name, command.name);
+			const args = {
+				flags: commandFlags,
+				args: commandArgs,
+				env: commandEnv,
+				run: runner.run,
+				ask: this.asker.ask,
+				fs,
+				glob,
+				root,
+				help: () => this.printHelp(command),
+				mode: modeValue
+			};
+			const preHooks = this.findPreHooks(command.name);
+			for (const hook of preHooks) {
+				this.log.debug(`Executing pre-hook for '${command.name}'...`);
+				await hook.options.handler(args);
+			}
+			await command.options.handler(args);
+			const postHooks = this.findPostHooks(command.name);
+			for (const hook of postHooks) {
+				this.log.debug(`Executing post-hook for '${command.name}'...`);
+				await hook.options.handler(args);
+			}
+			if (command.options.summary !== false) runner.summary();
+			this.log.debug(`Command '${command.name}' executed successfully.`);
+		});
+	}
+	/**
+	* Remove consumed command path arguments from argv.
+	*/
+	removeConsumedArgs(argv, consumedArgs) {
+		const result = [];
+		let consumedIndex = 0;
+		for (const arg of argv) if (arg.startsWith("-")) result.push(arg);
+		else if (consumedIndex < consumedArgs.length && arg === consumedArgs[consumedIndex]) consumedIndex++;
+		else result.push(arg);
+		return result;
+	}
+	/**
+	* Resolve a command from positional arguments.
+	*
+	* Supports:
+	* 1. Space-separated subcommands: `deploy vercel` -> finds deploy command, then vercel child
+	* 2. Colon notation (backwards compat): `deploy:vercel` -> finds command with name "deploy:vercel"
+	* 3. Simple commands: `build` -> finds command with name "build"
+	*/
+	resolveCommand(positionalArgs) {
+		if (positionalArgs.length === 0) return {
+			command: void 0,
+			consumedArgs: []
+		};
+		const firstArg = positionalArgs[0];
+		if (firstArg.includes(":")) {
+			const command = this.findCommand(firstArg);
+			if (command) return {
+				command,
+				consumedArgs: [firstArg]
+			};
+		}
+		let currentCommand = this.findCommand(firstArg);
+		const consumedArgs = [];
+		if (!currentCommand) return {
+			command: void 0,
+			consumedArgs: []
+		};
+		consumedArgs.push(firstArg);
+		for (let i = 1; i < positionalArgs.length; i++) {
+			const arg = positionalArgs[i];
+			if (!currentCommand.hasChildren) break;
+			const childCommand = currentCommand.findChild(arg);
+			if (childCommand) {
+				currentCommand = childCommand;
+				consumedArgs.push(arg);
+			} else break;
+		}
+		return {
+			command: currentCommand,
+			consumedArgs
+		};
+	}
 	get commands() {
 		return this.alepha.primitives($command);
 	}
@@ -493,17 +618,10 @@ var CliProvider = class {
 		return this.commands.filter((cmd) => cmd.name === `post${commandName}`);
 	}
 	/**
-	* Get all global flags including those from the root command (name === "")
+	* Get global flags (help only, root command flags are NOT global).
 	*/
 	getAllGlobalFlags() {
-		const rootCommand = this.commands.find((cmd) => cmd.name === "");
-		const allGlobalFlags = { ...this.globalFlags };
-		if (rootCommand) for (const [key, value] of Object.entries(rootCommand.flags.properties)) allGlobalFlags[key] = {
-			aliases: [key, ...value.aliases ?? (value.alias ? [value.alias] : void 0) ?? []],
-			description: value.description,
-			schema: value
-		};
-		return allGlobalFlags;
+		return { ...this.globalFlags };
 	}
 	parseCommandFlags(argv, schema) {
 		const flagDefs = Object.entries(schema.properties).map(([key, value]) => ({
@@ -524,6 +642,50 @@ var CliProvider = class {
 			throw error;
 		}
 	}
+	parseCommandEnv(schema, commandName) {
+		const result = {};
+		const missing = [];
+		for (const [key, propSchema] of Object.entries(schema.properties)) {
+			const value = process.env[key];
+			if (value !== void 0) result[key] = value;
+			else if (t.schema.isOptional(propSchema)) {
+				if ("default" in propSchema) result[key] = propSchema.default;
+			} else missing.push(key);
+		}
+		if (missing.length > 0) {
+			const vars = missing.join(", ");
+			throw new CommandError(`Missing required environment variable${missing.length > 1 ? "s" : ""}: ${vars}`);
+		}
+		try {
+			return this.alepha.codec.decode(schema, result);
+		} catch (error) {
+			if (error instanceof TypeBoxError) throw new CommandError(`Invalid environment variable: ${error.cause.instancePath || "env"} ${error.cause.message}`);
+			throw error;
+		}
+	}
+	/**
+	* Parse --mode or -m flag from argv.
+	*/
+	parseModeFlag(argv) {
+		for (let i = 0; i < argv.length; i++) {
+			const arg = argv[i];
+			if (arg.startsWith("--mode=") || arg.startsWith("-m=")) return arg.split("=")[1];
+			if (arg === "--mode" || arg === "-m") {
+				const nextArg = argv[i + 1];
+				if (nextArg && !nextArg.startsWith("-")) return nextArg;
+				throw new CommandError("Flag --mode requires a value.");
+			}
+		}
+	}
+	/**
+	* Load environment files based on mode.
+	*/
+	async loadModeEnv(root, mode) {
+		const envFiles = [".env"];
+		if (mode) envFiles.push(`.env.${mode}`);
+		this.log.debug(`Loading env files: ${envFiles.join(", ")}`);
+		await this.envUtils.loadEnv(root, envFiles);
+	}
 	parseFlags(argv, flagDefs) {
 		const result = {};
 		for (let i = 0; i < argv.length; i++) {
@@ -651,42 +813,80 @@ var CliProvider = class {
 		const cliName = this.name || "cli";
 		this.log.info("");
 		if (command?.name) {
-			const argsUsage = this.generateArgsUsage(command.options.args);
-			const usage = `${cliName} ${command.name}${argsUsage}`.trim();
+			const hasChildren = command.hasChildren;
+			const argsUsage = hasChildren ? " <command>" : this.generateArgsUsage(command.options.args);
+			const usage = `${cliName} ${this.getCommandPath(command)}${argsUsage}`.trim();
 			this.log.info(`Usage: \`${usage}\``);
 			if (command.options.description) {
 				this.log.info(``);
 				this.log.info(`\t${command.options.description}`);
 			}
+			if (hasChildren) {
+				this.log.info("");
+				this.log.info("Commands:");
+				const maxSubCmdLength = this.getMaxChildCmdLength(command.children);
+				for (const child of command.children) {
+					if (child.options.hide) continue;
+					const childArgsUsage = this.generateArgsUsage(child.options.args);
+					const fullCmdStr = `${[child.name, ...child.aliases].join(", ")}${childArgsUsage}`;
+					this.log.info(`    ${cliName} ${command.name} ${fullCmdStr.padEnd(maxSubCmdLength)} # ${child.options.description ?? ""}`);
+				}
+			}
 			this.log.info("");
 			this.log.info("Flags:");
-			const flags = [...Object.entries(command.flags.properties).map(([key, value]) => ({
-				key,
-				schema: value,
-				aliases: value.alias ?? [key],
-				description: value.description
-			})), ...Object.entries(this.getAllGlobalFlags()).map(([key, value]) => ({
-				key,
-				...value
-			}))];
+			const flags = [
+				...Object.entries(command.flags.properties).map(([key, value]) => ({
+					key,
+					schema: value,
+					aliases: value.alias ?? [key],
+					description: value.description
+				})),
+				...command.options.mode ? [{
+					key: "mode",
+					aliases: ["m", "mode"],
+					description: typeof command.options.mode === "string" ? `Environment mode - loads .env.{mode} (default: ${command.options.mode})` : "Environment mode (e.g., production, staging) - loads .env.{mode}"
+				}] : [],
+				...Object.entries(this.getAllGlobalFlags()).map(([key, value]) => ({
+					key,
+					...value
+				}))
+			];
 			const maxFlagLength = this.getMaxFlagLength(flags);
 			for (const { aliases, description } of flags) {
 				const flagStr = (Array.isArray(aliases) ? aliases : [aliases]).map((a) => a.length === 1 ? `-${a}` : `--${a}`).join(", ");
 				this.log.info(`    ${flagStr.padEnd(maxFlagLength)} # ${description ?? ""}`);
 			}
+			const envVars = Object.entries(command.env.properties);
+			if (envVars.length > 0) {
+				this.log.info("");
+				this.log.info("Env:");
+				const maxEnvLength = Math.max(...envVars.map(([key]) => key.length));
+				for (const [key, schema] of envVars) {
+					const isOptional = t.schema.isOptional(schema);
+					const description = schema.description ?? "";
+					const optionalStr = isOptional ? " (optional)" : "";
+					this.log.info(`    ${key.padEnd(maxEnvLength)} # ${description}${optionalStr}`);
+				}
+			}
 		} else {
 			this.log.info(this.description || "Available commands:");
 			this.log.info("");
 			this.log.info("Commands:");
-			const maxCmdLength = this.getMaxCmdLength(this.commands);
-			for (const command$1 of this.commands) {
+			const topLevelCommands = this.getTopLevelCommands();
+			const maxCmdLength = this.getMaxCmdLength(topLevelCommands);
+			for (const command$1 of topLevelCommands) {
 				if (command$1.name === "" || command$1.options.hide) continue;
-				const fullCmdStr = `${[command$1.name, ...command$1.aliases].join(", ")}${this.generateArgsUsage(command$1.options.args)}`;
+				const fullCmdStr = `${[command$1.name, ...command$1.aliases].join(", ")}${command$1.hasChildren ? " <command>" : this.generateArgsUsage(command$1.options.args)}`;
 				this.log.info(`    ${cliName} ${fullCmdStr.padEnd(maxCmdLength)} # ${command$1.options.description ?? ""}`);
 			}
 			this.log.info("");
 			this.log.info("Flags:");
-			const globalFlags = Object.values(this.getAllGlobalFlags());
+			const rootCommand = this.commands.find((cmd) => cmd.name === "");
+			const globalFlags = [...rootCommand ? Object.entries(rootCommand.flags.properties).map(([key, value]) => ({
+				key,
+				aliases: [key, ...value.aliases ?? (value.alias ? [value.alias] : void 0) ?? []],
+				description: value.description
+			})) : [], ...Object.values(this.getAllGlobalFlags())];
 			const maxFlagLength = this.getMaxFlagLength(globalFlags);
 			for (const { aliases, description } of globalFlags) {
 				const flagStr = aliases.map((a) => a.length === 1 ? `-${a}` : `--${a}`).join(", ");
@@ -695,9 +895,45 @@ var CliProvider = class {
 		}
 		this.log.info("");
 	}
+	/**
+	* Get the full command path (e.g., "deploy vercel" for a child command).
+	*/
+	getCommandPath(command) {
+		const path = [command.name];
+		let current = command;
+		while (true) {
+			const parent = this.findParentCommand(current);
+			if (!parent) break;
+			path.unshift(parent.name);
+			current = parent;
+		}
+		return path.join(" ");
+	}
+	/**
+	* Find the parent command of a given command.
+	*/
+	findParentCommand(command) {
+		for (const cmd of this.commands) if (cmd.children.includes(command)) return cmd;
+	}
+	/**
+	* Get top-level commands (commands that are not children of other commands).
+	*/
+	getTopLevelCommands() {
+		const allChildren = /* @__PURE__ */ new Set();
+		for (const command of this.commands) for (const child of command.children) allChildren.add(child);
+		return this.commands.filter((cmd) => !allChildren.has(cmd));
+	}
+	/**
+	* Get max length for child command display.
+	*/
+	getMaxChildCmdLength(children) {
+		return Math.max(...children.filter((c) => !c.options.hide).map((c) => {
+			return `${[c.name, ...c.aliases].join(", ")}${this.generateArgsUsage(c.options.args)}`.length;
+		}), 0);
+	}
 	getMaxCmdLength(commands) {
 		return Math.max(...commands.filter((c) => !c.options.hide && c.name !== "").map((c) => {
-			return `${[c.name, ...c.aliases].join(", ")}${this.generateArgsUsage(c.options.args)}`.length;
+			return `${[c.name, ...c.aliases].join(", ")}${c.hasChildren ? " <command>" : this.generateArgsUsage(c.options.args)}`.length;
 		}));
 	}
 	getMaxFlagLength(flags) {
@@ -725,10 +961,11 @@ const AlephaCommand = $module({
 		CliProvider,
 		Runner,
 		Asker,
-		PrettyPrint
+		PrettyPrint,
+		EnvUtils
 	]
 });
 
 //#endregion
-export { $command, AlephaCommand, Asker, CliProvider, CommandError, CommandPrimitive, PrettyPrint, Runner, cliOptions };
+export { $command, AlephaCommand, Asker, CliProvider, CommandError, CommandPrimitive, EnvUtils, PrettyPrint, Runner, cliOptions };
 //# sourceMappingURL=index.js.map