@vercube/cli 0.0.48 → 1.0.0-beta.2

package/README.md

@@ -12,7 +12,7 @@
 ![GitHub License](<https://img.shields.io/github/license/vercube/vercube?style=for-the-badge&logo=gitbook&logoColor=rgba(255%2C%20255%2C%20255%2C%200.6)&labelColor=%23000&color=%232f2f2f>)
 ![Codecov](<https://img.shields.io/codecov/c/github/vercube/vercube?style=for-the-badge&logo=vitest&logoColor=rgba(255%2C%20255%2C%20255%2C%200.6)&labelColor=%23000&color=%232f2f2f>)
 
-**Dev server, production builds, all from the command line. `vercube dev` to start, `vercube build` when you're ready to ship.**
+**Dev server, production builds, custom commands - all from the command line. `vercube dev` to start, `vercube build` when you're ready to ship.**
 
 [Website](https://vercube.dev) • [Documentation](https://vercube.dev/docs/getting-started)
 
@@ -22,6 +22,10 @@
 
 - **Dev server** - hot-reload out of the box
 - **Production build** - optimized bundles ready for deployment
+- **Project scaffolding** - `vercube init` to create a new project from the starter template
+- **Endpoint testing** - `vercube fetch /path` to test endpoints without a running server
+- **Custom commands** - define your own commands with `@Command`, `@Arg`, `@Flag` decorators
+- **Dependency injection** - commands integrate with `@vercube/di` for service injection
 - **Config loading** - reads `vercube.config.ts` automatically
 
 ## 📦 Installation
@@ -30,6 +34,26 @@
 pnpm add @vercube/cli
 ```
 
+### Custom commands
+
+Import from `@vercube/cli/toolkit` and register in `vercube.config.ts`:
+
+```ts
+import { BaseCommand, Command, Flag } from '@vercube/cli/toolkit';
+
+@Command({ name: 'deploy', description: 'Deploy to production' })
+export class DeployCommand extends BaseCommand {
+  @Flag({ name: 'env', description: 'Target environment', default: 'staging' })
+  public env: string;
+
+  public override async run(): Promise<void> {
+    console.log(`Deploying to ${this.env}...`);
+  }
+}
+```
+
+See the [Custom CLI Command](https://vercube.dev/docs/advanced/custom-cli-command) docs for the full API.
+
 ## 📜 License
 
 [MIT](https://github.com/vercube/vercube/blob/main/LICENSE)

package/dist/Flag-qtOTYeqz.mjs

@@ -0,0 +1,136 @@
+//#region src/BaseCommand.ts
+/**
+* Base class for all CLI commands.
+*
+* Extend this class and decorate with `@Command` to register a command.
+* Dependencies can be injected via `@Inject` from `@vercube/di`.
+*
+* @example
+* ```ts
+* @Command({ name: 'deploy', description: 'Deploy application' })
+* export class DeployCommand extends BaseCommand {
+*   @Inject(MyService)
+*   private readonly gMyService!: MyService;
+*
+*   public override async run(): Promise<void> {
+*     await this.gMyService.deploy();
+*   }
+* }
+* ```
+*/
+var BaseCommand = class {
+	/**
+	* CLI DI container, injected by CommandRegistry before `run()`.
+	* Prefer `@Inject` decorators over accessing this directly.
+	*/
+	container;
+};
+//#endregion
+//#region src/Decorators/Arg.ts
+const COMMAND_ARGS_KEY = "__commandArgs";
+/**
+* Property decorator for positional CLI arguments.
+* The value is injected from parsed CLI input before `run()` is called.
+*
+* @param options - argument configuration
+* @returns property decorator
+*
+* @example
+* ```ts
+* @Arg({ name: 'query', description: 'Phrase to search for' })
+* public query: string;
+* ```
+*/
+function Arg(options) {
+	return (target, propertyKey) => {
+		if (!target["__commandArgs"]) target[COMMAND_ARGS_KEY] = [];
+		const def = {
+			kind: "positional",
+			property: propertyKey,
+			name: options.name,
+			description: options.description,
+			required: options.required
+		};
+		target[COMMAND_ARGS_KEY].push(def);
+		Object.defineProperty(target, propertyKey, {
+			configurable: true,
+			enumerable: true,
+			writable: true,
+			value: void 0
+		});
+	};
+}
+//#endregion
+//#region src/Decorators/Command.ts
+const COMMAND_META_KEY = "__commandMeta";
+/**
+* Class decorator that marks a class as a CLI command.
+* Stores command metadata on the prototype so `CommandRegistry` can discover it.
+*
+* @param meta - command configuration (name, description, optional subcommands)
+* @returns class decorator
+*
+* @example
+* ```ts
+* @Command({ name: 'build', description: 'Build the project' })
+* export class BuildCommand extends BaseCommand { ... }
+* ```
+*/
+function Command(meta) {
+	return (target) => {
+		target.prototype[COMMAND_META_KEY] = meta;
+	};
+}
+//#endregion
+//#region src/Decorators/Flag.ts
+/**
+* Property decorator for named CLI flags (`--name value`).
+* The value type is inferred from `default` when `type` is not set.
+* The parsed value is injected before `run()` is called.
+*
+* @param options - flag configuration
+* @returns property decorator
+*
+* @example
+* ```ts
+* @Flag({ name: 'limit', description: 'Max results', default: 10 })
+* public limit: number;
+*
+* @Flag({ name: 'json', description: 'Output as JSON', default: false })
+* public json: boolean;
+* ```
+*/
+function Flag(options) {
+	return (target, propertyKey) => {
+		if (!target["__commandArgs"]) target[COMMAND_ARGS_KEY] = [];
+		const def = {
+			kind: "flag",
+			property: propertyKey,
+			name: options.name,
+			description: options.description,
+			default: options.default,
+			required: options.required,
+			valueType: options.type ?? inferType(options.default)
+		};
+		target[COMMAND_ARGS_KEY].push(def);
+		Object.defineProperty(target, propertyKey, {
+			configurable: true,
+			enumerable: true,
+			writable: true,
+			value: options.default
+		});
+	};
+}
+/**
+* Infers the citty arg type from a default value.
+*
+* @param value - default value to inspect
+* @returns corresponding citty arg type string
+*/
+function inferType(value) {
+	if (typeof value === "boolean") return "boolean";
+	if (typeof value === "number") return "number";
+	return "string";
+}
+//#endregion
+export { COMMAND_ARGS_KEY as a, Arg as i, COMMAND_META_KEY as n, BaseCommand as o, Command as r, Flag as t };

package/dist/index.mjs

@@ -1,19 +1,530 @@
 #!/usr/bin/env node
+import { i as Arg, n as COMMAND_META_KEY, o as BaseCommand, r as Command, t as Flag } from "./Flag-qtOTYeqz.mjs";
+import { createRequire } from "node:module";
 import { defineCommand, runMain } from "citty";
+import { Container } from "@vercube/di";
+import { BaseLogger, Logger } from "@vercube/logger";
+import { dirname, resolve } from "node:path";
+import { loadVercubeConfig } from "@vercube/core";
+import { createJiti } from "jiti";
+import { build, createDevServer, createVercube, watch } from "@vercube/devkit";
+import { cliFetch } from "srvx/cli";
+import { existsSync } from "node:fs";
+import { consola } from "consola";
+import { colors } from "consola/utils";
+import { downloadTemplate, startShell } from "giget";
+import { installDependencies } from "nypm";
+import { relative, resolve as resolve$1 } from "pathe";
+import { hasTTY } from "std-env";
+import { x } from "tinyexec";
+//#region package.json
+var version = "1.0.0-beta.2";
+//#endregion
+//#region src/Utils/CommandUtils.ts
+/**
+* Reads `@Command` metadata from a class prototype.
+*
+* @param CommandClass - command class constructor to inspect
+* @returns command metadata stored by the `@Command` decorator
+* @throws if the class is not decorated with `@Command`
+*/
+function getCommandMeta(CommandClass) {
+	const meta = CommandClass.prototype[COMMAND_META_KEY];
+	if (!meta) throw new Error(`[CommandRegistry] Class "${CommandClass.name}" is missing the @Command decorator.`);
+	return meta;
+}
+/**
+* Reads all `@Arg` / `@Flag` definitions from a class prototype.
+*
+* @param CommandClass - command class constructor to inspect
+* @returns array of arg/flag definitions, or `[]` if none exist
+*/
+function getArgDefs(CommandClass) {
+	return CommandClass.prototype["__commandArgs"] ?? [];
+}
+/**
+* Converts `ArgDef` entries into a citty-compatible args record.
+*
+* @param defs - arg/flag definitions to convert
+* @returns record of citty argument descriptors keyed by name
+*/
+function buildCittyArgs(defs) {
+	const args = {};
+	for (const def of defs) if (def.kind === "positional") args[def.name] = {
+		type: "positional",
+		description: def.description,
+		required: def.required
+	};
+	else args[def.name] = {
+		type: def.valueType === "boolean" ? "boolean" : "string",
+		description: def.description,
+		default: def.valueType === "number" ? String(def.default ?? "") : def.default,
+		required: def.required
+	};
+	return args;
+}
+/**
+* Injects parsed citty arg values into command instance properties
+* using the mappings defined by `@Arg` / `@Flag` decorators.
+* Handles `number` coercion for flags with `valueType: 'number'`.
+*
+* @param instance - command instance to inject into
+* @param parsedArgs - parsed arg values from citty
+* @param defs - arg/flag definitions describing the property mapping
+*/
+function injectArgs(instance, parsedArgs, defs) {
+	for (const def of defs) if (def.name in parsedArgs) {
+		const raw = parsedArgs[def.name];
+		instance[def.property] = def.valueType === "number" && typeof raw === "string" ? Number(raw) : raw;
+	}
+}
+//#endregion
+//#region src/CommandRegistry.ts
+/**
+* Registry that stores command classes and transforms them into citty CommandDefs.
+* Both built-in and user-defined commands are registered here before the CLI runs.
+*/
+var CommandRegistry = class {
+	fCommands = /* @__PURE__ */ new Map();
+	/**
+	* Registers a command class decorated with `@Command`.
+	*
+	* @param CommandClass - class to register
+	* @throws if the class is missing the `@Command` decorator
+	*/
+	register(CommandClass) {
+		const meta = getCommandMeta(CommandClass);
+		this.fCommands.set(meta.name, CommandClass);
+	}
+	/**
+	* Converts a single command class into a citty `CommandDef`.
+	* Recursively processes subcommands defined in `@Command({ subCommands })`.
+	*
+	* @param CommandClass - command class to convert
+	* @param container - CLI DI container used to resolve instances
+	* @returns citty CommandDef ready to pass to `defineCommand` / `runMain`
+	*/
+	toCommandDef(CommandClass, container) {
+		const meta = getCommandMeta(CommandClass);
+		const argDefs = getArgDefs(CommandClass);
+		const subCommands = {};
+		if (meta.subCommands) for (const SubCmd of meta.subCommands) {
+			const subMeta = getCommandMeta(SubCmd);
+			subCommands[subMeta.name] = () => this.toCommandDef(SubCmd, container);
+		}
+		return defineCommand({
+			meta: {
+				name: meta.name,
+				description: meta.description
+			},
+			args: buildCittyArgs(argDefs),
+			subCommands: Object.keys(subCommands).length > 0 ? subCommands : void 0,
+			run: async (ctx) => {
+				const instance = container.resolve(CommandClass);
+				instance.container = container;
+				injectArgs(instance, ctx.args, argDefs);
+				await instance.run();
+			}
+		});
+	}
+	/**
+	* Builds the full citty subcommands map from all registered commands.
+	*
+	* @param container - CLI DI container used when executing commands
+	* @returns record mapping command names to lazy `CommandDef` factories
+	*/
+	buildCittyTree(container) {
+		const tree = {};
+		for (const CommandClass of this.fCommands.values()) {
+			const meta = getCommandMeta(CommandClass);
+			tree[meta.name] = () => this.toCommandDef(CommandClass, container);
+		}
+		return tree;
+	}
+};
+//#endregion
+//#region src/CliContainer.ts
+/**
+* Creates and configures a dedicated DI container for the CLI.
+* Separate from the application runtime container.
+* Pre-configured with an evlog-backed Logger.
+*
+* @returns configured CLI container
+*/
+function createCliContainer() {
+	const container = new Container({ context: "cli" });
+	container.bind(Logger, BaseLogger);
+	container.get(Logger).configure({ logLevel: "info" });
+	container.bind(CommandRegistry);
+	container.flushQueue();
+	return container;
+}
+//#endregion
+//#region src/CommandLoader.ts
+/** @internal */
+const _require = createRequire(import.meta.url);
+/**
+* Babel (used by jiti) emits `_initializerWarningHelper` for decorated properties
+* without an explicit initializer - a function that always throws.
+* Our decorators (`@Arg`, `@Flag`, `@Inject`) already define the property via
+* `Object.defineProperty`, so the guard is unnecessary. We patch it out with a no-op.
+*
+* @see https://github.com/babel/babel/issues/12672
+*/
+const INIT_WARNING_HELPER_RE = /function _initializerWarningHelper\b[^{]*\{[^}]*\}/g;
+/**
+* jiti's bundled Babel transform, resolved via jiti's package.json because
+* `jiti/dist/babel.cjs` is not listed in the package exports map.
+*/
+const babelTransform = _require(resolve(dirname(_require.resolve("jiti/package.json")), "dist/babel.cjs"));
+/**
+* Custom jiti instance with a patched Babel transform that replaces
+* `_initializerWarningHelper` with a no-op so user command classes
+* don't need `!` or explicit default values on decorated properties.
+*/
+const jiti = createJiti(import.meta.url, {
+	fsCache: false,
+	moduleCache: false,
+	transform(opts) {
+		return { code: babelTransform(opts).code.replace(INIT_WARNING_HELPER_RE, "function _initializerWarningHelper(){return void 0}") };
+	}
+});
+/**
+* Loads user-defined command classes from `vercube.config.ts` in the given directory.
+* Delegates file loading to the patched jiti instance so decorated properties
+* work without `!` or explicit initializers.
+*
+* Returns an empty array when:
+* - `vercube.config.ts` does not exist in `cwd`
+* - the config file has no `cli.commands` and no plugin registered commands
+*
+* @param cwd - directory to look for `vercube.config.ts` in (typically `process.cwd()`)
+* @returns array of command class constructors, or `[]` if none found
+*/
+async function loadUserCommands(cwd) {
+	try {
+		return (await loadVercubeConfig(void 0, {
+			cwd,
+			import: (id) => jiti.import(id)
+		})).cli?.commands ?? [];
+	} catch {
+		return [];
+	}
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.134.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/Commands/Build.ts
+let BuildCommand = class BuildCommand extends BaseCommand {
+	/** Custom entry file path. Uses default from vercube.config.ts when omitted. */
+	entry;
+	/**
+	* @returns resolves when the build is done
+	*/
+	async run() {
+		await build(await createVercube({ build: { entry: this.entry } }));
+	}
+};
+__decorate([Flag({
+	name: "entry",
+	description: "Entry file",
+	type: "string"
+})], BuildCommand.prototype, "entry", void 0);
+BuildCommand = __decorate([Command({
+	name: "build",
+	description: "Build the project"
+})], BuildCommand);
+//#endregion
+//#region src/Commands/Dev.ts
+let DevCommand = class DevCommand extends BaseCommand {
+	/**
+	* @returns resolves when the watcher is ready
+	*/
+	async run() {
+		const app = await createVercube();
+		createDevServer(app);
+		await watch(app);
+	}
+};
+DevCommand = __decorate([Command({
+	name: "dev",
+	description: "Start development server"
+})], DevCommand);
+//#endregion
+//#region src/Commands/Fetch.ts
+let FetchCommand = class FetchCommand extends BaseCommand {
+	/** Target URL path, e.g. `/api/users`. */
+	url;
+	/** Entry file relative to the output directory. */
+	entry;
+	/** HTTP method. */
+	method;
+	/** Request headers as `"Name: Value, Name: Value"`. */
+	headers;
+	/** Request body. `@-` reads from stdin, `@filename` reads from a file. */
+	data;
+	/** Print request and response headers alongside the body. */
+	verbose;
+	/**
+	* @returns resolves when the response has been printed
+	*/
+	async run() {
+		const app = await createVercube({ build: { dts: false } });
+		await build(app);
+		await cliFetch({
+			verbose: this.verbose,
+			dir: app.config.build?.output?.dir ?? "dist",
+			entry: this.entry,
+			url: this.url,
+			method: this.method,
+			header: this.headers?.split(",") ?? [],
+			data: this.data
+		});
+	}
+};
+__decorate([Arg({
+	name: "url",
+	description: "URL to fetch"
+})], FetchCommand.prototype, "url", void 0);
+__decorate([Flag({
+	name: "entry",
+	description: "Entry point for the application",
+	default: "index.mjs"
+})], FetchCommand.prototype, "entry", void 0);
+__decorate([Flag({
+	name: "method",
+	description: "HTTP method",
+	default: "GET"
+})], FetchCommand.prototype, "method", void 0);
+__decorate([Flag({
+	name: "headers",
+	description: "Add header (format: \"Name: Value, ...\")",
+	type: "string"
+})], FetchCommand.prototype, "headers", void 0);
+__decorate([Flag({
+	name: "data",
+	description: "Request body (use @- for stdin, @file for file)",
+	type: "string"
+})], FetchCommand.prototype, "data", void 0);
+__decorate([Flag({
+	name: "verbose",
+	description: "Show request and response headers",
+	default: false
+})], FetchCommand.prototype, "verbose", void 0);
+FetchCommand = __decorate([Command({
+	name: "fetch",
+	description: "Fetch a request from the application"
+})], FetchCommand);
+//#endregion
+//#region src/Utils/Logo.ts
+const startColor = {
+	r: 149,
+	g: 100,
+	b: 245
+};
+const endColor = {
+	r: 111,
+	g: 114,
+	b: 245
+};
+const icon = [
+	"                           _          ",
+	"                          | |         ",
+	" __   _____ _ __ ___ _   _| |__   ___ ",
+	" \\ \\ / / _ \\ '__/ __| | | | '_ \\ / _ \\",
+	String.raw`  \ V /  __/ | | (__| |_| | |_) |  __/`,
+	String.raw`   \_/ \___|_|  \___|\__,_|_.__/ \___|`,
+	"                                      ",
+	"                                      "
+];
+function interpolateColor(startColor, endColor, factor) {
+	return `\u001B[38;2;${Math.round(startColor.r + factor * (endColor.r - startColor.r))};${Math.round(startColor.g + factor * (endColor.g - startColor.g))};${Math.round(startColor.b + factor * (endColor.b - startColor.b))}m`;
+}
+function applyGradient(icon, startColor, endColor) {
+	const totalLines = icon.length;
+	return icon.map((line, index) => {
+		return interpolateColor(startColor, endColor, index / (totalLines - 1)) + line;
+	}).join("\n");
+}
+const vercubeIcon = applyGradient(icon, startColor, endColor);
+//#endregion
+//#region src/Commands/Init.ts
+const logger = consola.withTag(colors.whiteBright(colors.bold(colors.bgGreenBright(" vercube "))));
+const DEFAULT_REGISTRY = "https://raw.githubusercontent.com/vercube/starter/main/templates";
+const DEFAULT_TEMPLATE_NAME = "vercube";
+const packageManagerOptions = Object.keys({
+	npm: void 0,
+	pnpm: void 0,
+	yarn: void 0,
+	bun: void 0,
+	deno: void 0,
+	aube: void 0
+});
+let InitCommand = class InitCommand extends BaseCommand {
+	/** Target directory. Prompted interactively when omitted. */
+	dir;
+	/** Overwrite existing directory without prompting. */
+	force;
+	/** Set to `false` to skip dependency installation. */
+	install;
+	/** Run `git init` in the new project directory. */
+	gitInit;
+	/** Package manager for dependency installation. */
+	packageManager;
+	/** Open an interactive shell in the project directory after scaffolding. */
+	shell;
+	/**
+	* @returns resolves when scaffolding and setup are complete
+	*/
+	async run() {
+		if (hasTTY) process.stdout.write(`\n${vercubeIcon}\n\n`);
+		consola.info(`Welcome to ${colors.bold("Vercube")}!`);
+		let dir = this.dir ?? "";
+		if (!dir) dir = await logger.prompt("Where would you like to create your project?", {
+			placeholder: "./vercube-app",
+			type: "text",
+			default: "vercube-app",
+			cancel: "reject"
+		}).catch(() => process.exit(1));
+		const cwd = resolve$1(process.cwd());
+		let templateDownloadPath = resolve$1(cwd, dir);
+		logger.info(`Creating a new project in ${colors.cyan(relative(cwd, templateDownloadPath) || templateDownloadPath)}.`);
+		let shouldForce = Boolean(this.force);
+		if (!shouldForce && existsSync(templateDownloadPath)) switch (await logger.prompt(`The directory ${colors.cyan(templateDownloadPath)} already exists. What would you like to do?`, {
+			type: "select",
+			options: [
+				"Override its contents",
+				"Select different directory",
+				"Abort"
+			]
+		})) {
+			case "Override its contents":
+				shouldForce = true;
+				break;
+			case "Select different directory":
+				templateDownloadPath = resolve$1(cwd, await logger.prompt("Please specify a different directory:", {
+					type: "text",
+					cancel: "reject"
+				}).catch(() => process.exit(1)));
+				break;
+			default: process.exit(1);
+		}
+		let template;
+		try {
+			template = await downloadTemplate(DEFAULT_TEMPLATE_NAME, {
+				dir: templateDownloadPath,
+				force: shouldForce,
+				registry: DEFAULT_REGISTRY
+			});
+		} catch (error) {
+			if (process.env.DEBUG) throw error;
+			logger.error(error.toString());
+			process.exit(1);
+		}
+		const packageManagerArg = this.packageManager;
+		const selectedPackageManager = packageManagerOptions.includes(packageManagerArg) ? packageManagerArg : await logger.prompt("Which package manager would you like to use?", {
+			type: "select",
+			options: packageManagerOptions,
+			cancel: "reject"
+		}).catch(() => process.exit(1));
+		if (this.install === false) logger.info("Skipping install dependencies step.");
+		else {
+			logger.start("Installing dependencies...");
+			try {
+				await installDependencies({
+					cwd: template.dir,
+					packageManager: {
+						name: selectedPackageManager,
+						command: selectedPackageManager
+					}
+				});
+			} catch (error) {
+				if (process.env.DEBUG) throw error;
+				logger.error(error.toString());
+				process.exit(1);
+			}
+			logger.success("Installation completed.");
+		}
+		let gitInit = this.gitInit;
+		if (gitInit === void 0) gitInit = await logger.prompt("Initialize git repository?", {
+			type: "confirm",
+			cancel: "reject"
+		}).catch(() => process.exit(1));
+		if (gitInit) {
+			logger.info("Initializing git repository...\n");
+			try {
+				await x("git", ["init", template.dir], {
+					throwOnError: true,
+					nodeOptions: { stdio: "inherit" }
+				});
+			} catch (error) {
+				logger.warn(`Failed to initialize git repository: ${error}`);
+			}
+		}
+		logger.log("\n✨ Vercube project has been created! Next steps:");
+		const relativeTemplateDir = relative(process.cwd(), template.dir) || ".";
+		const runCmd = selectedPackageManager === "deno" ? "task" : "run";
+		const nextSteps = [!this.shell && relativeTemplateDir.length > 1 && `\`cd ${relativeTemplateDir}\``, `Start development server with \`${selectedPackageManager} ${runCmd} dev\``].filter(Boolean);
+		for (const step of nextSteps) logger.log(` › ${step}`);
+		if (this.shell) startShell(template.dir);
+	}
+};
+__decorate([Arg({
+	name: "dir",
+	description: "Project directory"
+})], InitCommand.prototype, "dir", void 0);
+__decorate([Flag({
+	name: "force",
+	description: "Override existing directory",
+	default: false
+})], InitCommand.prototype, "force", void 0);
+__decorate([Flag({
+	name: "install",
+	description: "Install dependencies",
+	default: true
+})], InitCommand.prototype, "install", void 0);
+__decorate([Flag({
+	name: "gitInit",
+	description: "Initialize git repository",
+	default: true
+})], InitCommand.prototype, "gitInit", void 0);
+__decorate([Flag({
+	name: "packageManager",
+	description: "Package manager choice (npm, pnpm, yarn, bun)",
+	default: "pnpm"
+})], InitCommand.prototype, "packageManager", void 0);
+__decorate([Flag({
+	name: "shell",
+	description: "Open shell in project directory",
+	default: false
+})], InitCommand.prototype, "shell", void 0);
+InitCommand = __decorate([Command({
+	name: "init",
+	description: "Initialize a new Vercube app"
+})], InitCommand);
 //#endregion
 //#region src/index.ts
+const container = createCliContainer();
+const registry = container.resolve(CommandRegistry);
+registry.register(BuildCommand);
+registry.register(DevCommand);
+registry.register(InitCommand);
+registry.register(FetchCommand);
+const userCommands = await loadUserCommands(process.cwd());
+for (const UserCommand of userCommands) registry.register(UserCommand);
 runMain(defineCommand({
 	meta: {
-		name: "Vercube",
-		version: "0.0.48",
+		name: "vercube",
+		version,
 		description: "Vercube CLI"
 	},
-	subCommands: {
-		build: () => import("./build-BjzKMqLM.mjs").then(({ buildCommand }) => buildCommand),
-		dev: () => import("./dev-FNtcz-vW.mjs").then(({ devCommand }) => devCommand),
-		init: () => import("./init-BHbW8wC8.mjs").then(({ initCommand }) => initCommand),
-		fetch: () => import("./fetch-UyiACOy-.mjs").then(({ fetchCommand }) => fetchCommand)
-	}
+	subCommands: registry.buildCittyTree(container)
 }));
 //#endregion
 export {};

package/dist/toolkit.d.mts

@@ -0,0 +1,135 @@
+import { Container } from "@vercube/di";
+
+//#region src/BaseCommand.d.ts
+/**
+ * Base class for all CLI commands.
+ *
+ * Extend this class and decorate with `@Command` to register a command.
+ * Dependencies can be injected via `@Inject` from `@vercube/di`.
+ *
+ * @example
+ * ```ts
+ * @Command({ name: 'deploy', description: 'Deploy application' })
+ * export class DeployCommand extends BaseCommand {
+ *   @Inject(MyService)
+ *   private readonly gMyService!: MyService;
+ *
+ *   public override async run(): Promise<void> {
+ *     await this.gMyService.deploy();
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseCommand {
+  /**
+   * CLI DI container, injected by CommandRegistry before `run()`.
+   * Prefer `@Inject` decorators over accessing this directly.
+   */
+  protected container: Container;
+  /**
+   * Execute the command logic. Called after arg/flag injection and DI resolution.
+   * @returns promise that resolves when the command is done
+   */
+  abstract run(): Promise<void>;
+}
+//#endregion
+//#region src/Types/CliTypes.d.ts
+declare namespace CliTypes {
+  /**
+   * Metadata stored by the `@Command` decorator on a class prototype.
+   */
+  interface CommandMeta {
+    /** Command name used on the CLI (`vercube <name>`). */
+    name: string;
+    /** Short description shown in `--help`. */
+    description: string;
+    /** Optional child command classes. */
+    subCommands?: (new () => unknown)[];
+  }
+  /**
+   * Single arg/flag definition stored by `@Arg` / `@Flag` decorators.
+   */
+  interface ArgDef {
+    /** Whether this is a positional arg or a named flag. */
+    kind: 'positional' | 'flag';
+    /** Property name on the command class instance. */
+    property: string;
+    /** Name used in the CLI (citty arg key). */
+    name: string;
+    /** Short description shown in `--help`. */
+    description?: string;
+    /** Default value. */
+    default?: unknown;
+    /** Whether the arg/flag is required. */
+    required?: boolean;
+    /** For flags: the value type used by citty. */
+    valueType?: 'string' | 'boolean' | 'number';
+  }
+}
+//#endregion
+//#region src/Decorators/Command.d.ts
+/**
+ * Class decorator that marks a class as a CLI command.
+ * Stores command metadata on the prototype so `CommandRegistry` can discover it.
+ *
+ * @param meta - command configuration (name, description, optional subcommands)
+ * @returns class decorator
+ *
+ * @example
+ * ```ts
+ * @Command({ name: 'build', description: 'Build the project' })
+ * export class BuildCommand extends BaseCommand { ... }
+ * ```
+ */
+declare function Command(meta: CliTypes.CommandMeta): Function;
+//#endregion
+//#region src/Decorators/Arg.d.ts
+interface ArgOptions {
+  name: string;
+  description?: string;
+  required?: boolean;
+}
+/**
+ * Property decorator for positional CLI arguments.
+ * The value is injected from parsed CLI input before `run()` is called.
+ *
+ * @param options - argument configuration
+ * @returns property decorator
+ *
+ * @example
+ * ```ts
+ * @Arg({ name: 'query', description: 'Phrase to search for' })
+ * public query: string;
+ * ```
+ */
+declare function Arg(options: ArgOptions): Function;
+//#endregion
+//#region src/Decorators/Flag.d.ts
+interface FlagOptions {
+  name: string;
+  description?: string;
+  default?: unknown;
+  required?: boolean;
+  /** Explicit citty value type. Inferred from `default` when omitted. */
+  type?: 'string' | 'boolean' | 'number';
+}
+/**
+ * Property decorator for named CLI flags (`--name value`).
+ * The value type is inferred from `default` when `type` is not set.
+ * The parsed value is injected before `run()` is called.
+ *
+ * @param options - flag configuration
+ * @returns property decorator
+ *
+ * @example
+ * ```ts
+ * @Flag({ name: 'limit', description: 'Max results', default: 10 })
+ * public limit: number;
+ *
+ * @Flag({ name: 'json', description: 'Output as JSON', default: false })
+ * public json: boolean;
+ * ```
+ */
+declare function Flag(options: FlagOptions): Function;
+//#endregion
+export { Arg, BaseCommand, type CliTypes, Command, Flag };

package/dist/toolkit.mjs

@@ -0,0 +1,2 @@
+import { i as Arg, o as BaseCommand, r as Command, t as Flag } from "./Flag-qtOTYeqz.mjs";
+export { Arg, BaseCommand, Command, Flag };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercube/cli",
-  "version": "0.0.48",
+  "version": "1.0.0-beta.2",
   "description": "CLI module for Vercube framework",
   "repository": {
     "type": "git",
@@ -14,6 +14,7 @@
   "module": "./dist/index.mjs",
   "exports": {
     ".": "./dist/index.mjs",
+    "./toolkit": "./dist/toolkit.mjs",
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.mts",
@@ -25,21 +26,25 @@
     "vercube": "./dist/index.mjs"
   },
   "dependencies": {
+    "c12": "4.0.0-beta.5",
     "citty": "0.2.2",
     "consola": "3.4.2",
-    "giget": "3.2.0",
-    "nypm": "0.6.6",
+    "giget": "3.3.0",
+    "jiti": "2.7.0",
+    "nypm": "0.6.7",
     "pathe": "2.0.3",
     "srvx": "0.11.16",
     "std-env": "4.1.0",
-    "tinyexec": "1.2.2",
-    "@vercube/logger": "0.0.48",
-    "@vercube/devkit": "0.0.48"
+    "tinyexec": "1.2.4",
+    "@vercube/core": "1.0.0-beta.2",
+    "@vercube/di": "1.0.0-beta.2",
+    "@vercube/logger": "1.0.0-beta.2",
+    "@vercube/devkit": "1.0.0-beta.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsdown --config ../../tsdown.config.ts --config-loader=unrun"
+    "build": "tsdown --config tsdown.config.ts --config-loader=unrun"
   }
 }

package/dist/build-BjzKMqLM.mjs

@@ -1,19 +0,0 @@
-import { defineCommand } from "citty";
-import { build, createVercube } from "@vercube/devkit";
-//#region src/commands/build.ts
-const buildCommand = defineCommand({
-	meta: {
-		name: "build",
-		description: "Build the project"
-	},
-	args: { entry: {
-		type: "string",
-		description: "Entry file",
-		default: void 0
-	} },
-	run: async (ctx) => {
-		await build(await createVercube({ build: { entry: ctx?.args?.entry ?? void 0 } }));
-	}
-});
-//#endregion
-export { buildCommand };

package/dist/dev-FNtcz-vW.mjs

@@ -1,16 +0,0 @@
-import { defineCommand } from "citty";
-import { createDevServer, createVercube, watch } from "@vercube/devkit";
-//#region src/commands/dev.ts
-const devCommand = defineCommand({
-	meta: {
-		name: "dev",
-		description: "Start development server"
-	},
-	async run() {
-		const app = await createVercube();
-		createDevServer(app);
-		await watch(app);
-	}
-});
-//#endregion
-export { devCommand };

package/dist/fetch-UyiACOy-.mjs

@@ -1,60 +0,0 @@
-import { defineCommand } from "citty";
-import { build, createVercube } from "@vercube/devkit";
-import { cliFetch } from "srvx/cli";
-//#region src/commands/fetch.ts
-const fetchCommand = defineCommand({
-	meta: {
-		name: "fetch",
-		description: "Fetch a request from the application"
-	},
-	args: {
-		url: {
-			type: "positional",
-			description: "URL to fetch",
-			default: "/"
-		},
-		entry: {
-			type: "string",
-			description: "Entry point for the application",
-			default: "index.mjs"
-		},
-		method: {
-			type: "string",
-			description: "HTTP method (default: GET, or POST if body is provided)",
-			default: "GET",
-			alias: "X",
-			valueHint: "GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS"
-		},
-		headers: {
-			type: "string",
-			description: "Add header (format: \"Name: Value, Name: Value, ...\")",
-			alias: "H"
-		},
-		data: {
-			type: "string",
-			description: "Request body (use @- for stdin, @file for file)",
-			alias: "d"
-		},
-		verbose: {
-			type: "boolean",
-			description: "Show request and response headers",
-			alias: "v",
-			default: false
-		}
-	},
-	async run(ctx) {
-		const app = await createVercube({ build: { dts: false } });
-		await build(app);
-		await cliFetch({
-			verbose: ctx.args.verbose,
-			dir: app.config.build?.output?.dir ?? "dist",
-			entry: ctx.args.entry,
-			url: ctx.args.url,
-			method: ctx.args.method,
-			header: ctx.args.headers?.split(",") ?? [],
-			data: ctx.args.data
-		});
-	}
-});
-//#endregion
-export { fetchCommand };

package/dist/init-BHbW8wC8.mjs

@@ -1,181 +0,0 @@
-import { defineCommand } from "citty";
-import { existsSync } from "node:fs";
-import { consola } from "consola";
-import { colors } from "consola/utils";
-import { downloadTemplate, startShell } from "giget";
-import { installDependencies } from "nypm";
-import { relative, resolve } from "pathe";
-import { hasTTY } from "std-env";
-import { x } from "tinyexec";
-//#region src/utils/logo.ts
-const startColor = {
-	r: 149,
-	g: 100,
-	b: 245
-};
-const endColor = {
-	r: 111,
-	g: 114,
-	b: 245
-};
-const icon = [
-	"                           _          ",
-	"                          | |         ",
-	" __   _____ _ __ ___ _   _| |__   ___ ",
-	" \\ \\ / / _ \\ '__/ __| | | | '_ \\ / _ \\",
-	String.raw`  \ V /  __/ | | (__| |_| | |_) |  __/`,
-	String.raw`   \_/ \___|_|  \___|\__,_|_.__/ \___|`,
-	"                                      ",
-	"                                      "
-];
-function interpolateColor(startColor, endColor, factor) {
-	return `\u001B[38;2;${Math.round(startColor.r + factor * (endColor.r - startColor.r))};${Math.round(startColor.g + factor * (endColor.g - startColor.g))};${Math.round(startColor.b + factor * (endColor.b - startColor.b))}m`;
-}
-function applyGradient(icon, startColor, endColor) {
-	const totalLines = icon.length;
-	return icon.map((line, index) => {
-		return interpolateColor(startColor, endColor, index / (totalLines - 1)) + line;
-	}).join("\n");
-}
-const vercubeIcon = applyGradient(icon, startColor, endColor);
-//#endregion
-//#region src/commands/init.ts
-const logger = consola.withTag(colors.whiteBright(colors.bold(colors.bgGreenBright(" vercube "))));
-const DEFAULT_REGISTRY = "https://raw.githubusercontent.com/vercube/starter/main/templates";
-const DEFAULT_TEMPLATE_NAME = "vercube";
-const packageManagerOptions = Object.keys({
-	npm: void 0,
-	pnpm: void 0,
-	yarn: void 0,
-	bun: void 0,
-	deno: void 0
-});
-const initCommand = defineCommand({
-	meta: {
-		name: "init",
-		description: "Initialize a new Vercube app"
-	},
-	args: {
-		dir: {
-			type: "positional",
-			description: "Project directory",
-			default: ""
-		},
-		force: {
-			type: "boolean",
-			alias: "f",
-			description: "Override existing directory"
-		},
-		install: {
-			type: "boolean",
-			default: true,
-			description: "Skip installing dependencies"
-		},
-		gitInit: {
-			type: "boolean",
-			description: "Initialize git repository",
-			default: true
-		},
-		packageManager: {
-			type: "string",
-			description: "Package manager choice (npm, pnpm, yarn, bun)",
-			default: "pnpm"
-		}
-	},
-	async run(ctx) {
-		if (hasTTY) process.stdout.write(`\n${vercubeIcon}\n\n`);
-		consola.info(`Welcome to ${colors.bold("Vercube")}!`);
-		let dir = ctx.args.dir;
-		if (ctx.args.dir === "") dir = await logger.prompt("Where would you like to create your project?", {
-			placeholder: "./vercube-app",
-			type: "text",
-			default: "vercube-app",
-			cancel: "reject"
-		}).catch(() => process.exit(1));
-		const cwd = resolve(process.cwd());
-		let templateDownloadPath = resolve(cwd, dir);
-		logger.info(`Creating a new project in ${colors.cyan(relative(cwd, templateDownloadPath) || templateDownloadPath)}.`);
-		let shouldForce = Boolean(ctx.args.force);
-		if (!shouldForce && existsSync(templateDownloadPath)) switch (await logger.prompt(`The directory ${colors.cyan(templateDownloadPath)} already exists. What would you like to do?`, {
-			type: "select",
-			options: [
-				"Override its contents",
-				"Select different directory",
-				"Abort"
-			]
-		})) {
-			case "Override its contents":
-				shouldForce = true;
-				break;
-			case "Select different directory":
-				templateDownloadPath = resolve(cwd, await logger.prompt("Please specify a different directory:", {
-					type: "text",
-					cancel: "reject"
-				}).catch(() => process.exit(1)));
-				break;
-			default: process.exit(1);
-		}
-		let template;
-		try {
-			template = await downloadTemplate(DEFAULT_TEMPLATE_NAME, {
-				dir: templateDownloadPath,
-				force: shouldForce,
-				offline: Boolean(ctx.args.offline),
-				preferOffline: Boolean(ctx.args.preferOffline),
-				registry: DEFAULT_REGISTRY
-			});
-		} catch (error) {
-			if (process.env.DEBUG) throw error;
-			logger.error(error.toString());
-			process.exit(1);
-		}
-		const packageManagerArg = ctx.args.packageManager;
-		const selectedPackageManager = packageManagerOptions.includes(packageManagerArg) ? packageManagerArg : await logger.prompt("Which package manager would you like to use?", {
-			type: "select",
-			options: packageManagerOptions,
-			cancel: "reject"
-		}).catch(() => process.exit(1));
-		if (ctx.args.install === false) logger.info("Skipping install dependencies step.");
-		else {
-			logger.start("Installing dependencies...");
-			try {
-				await installDependencies({
-					cwd: template.dir,
-					packageManager: {
-						name: selectedPackageManager,
-						command: selectedPackageManager
-					}
-				});
-			} catch (error) {
-				if (process.env.DEBUG) throw error;
-				logger.error(error.toString());
-				process.exit(1);
-			}
-			logger.success("Installation completed.");
-		}
-		let gitInit = ctx.args.gitInit;
-		if (gitInit === void 0) gitInit = await logger.prompt("Initialize git repository?", {
-			type: "confirm",
-			cancel: "reject"
-		}).catch(() => process.exit(1));
-		if (ctx.args.gitInit) {
-			logger.info("Initializing git repository...\n");
-			try {
-				await x("git", ["init", template.dir], {
-					throwOnError: true,
-					nodeOptions: { stdio: "inherit" }
-				});
-			} catch (error) {
-				logger.warn(`Failed to initialize git repository: ${error}`);
-			}
-		}
-		logger.log("\n✨ Vercube project has been created! Next steps:");
-		const relativeTemplateDir = relative(process.cwd(), template.dir) || ".";
-		const runCmd = selectedPackageManager === "deno" ? "task" : "run";
-		const nextSteps = [!ctx.args.shell && relativeTemplateDir.length > 1 && `\`cd ${relativeTemplateDir}\``, `Start development server with \`${selectedPackageManager} ${runCmd} dev\``].filter(Boolean);
-		for (const step of nextSteps) logger.log(` › ${step}`);
-		if (ctx.args.shell) startShell(template.dir);
-	}
-});
-//#endregion
-export { initCommand };