@michaelhartmayer/agentctl 1.0.3 → 1.1.3

package/dist/fs-utils.js

@@ -1,4 +1,18 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -6,30 +20,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getGlobalRoot = getGlobalRoot;
 exports.getAntigravityGlobalRoot = getAntigravityGlobalRoot;
 exports.findLocalRoot = findLocalRoot;
-const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
+const utils_1 = require("./logic/utils");
+__exportStar(require("./logic/utils"), exports);
+function getRealContext() {
+    return {
+        platform: process.platform,
+        env: process.env,
+        homedir: process.env.HOME || process.env.USERPROFILE || os_1.default.homedir()
+    };
+}
 function getGlobalRoot() {
-    if (process.platform === 'win32') {
-        return path_1.default.join(process.env.APPDATA || path_1.default.join(os_1.default.homedir(), 'AppData', 'Roaming'), 'agentctl');
-    }
-    return path_1.default.join(os_1.default.homedir(), '.config', 'agentctl');
+    return utils_1.UtilsLogic.getGlobalRoot(getRealContext());
 }
 function getAntigravityGlobalRoot() {
-    return path_1.default.join(os_1.default.homedir(), '.gemini', 'antigravity');
+    return utils_1.UtilsLogic.getAntigravityGlobalRoot(getRealContext());
 }
 function findLocalRoot(cwd = process.cwd()) {
-    let current = path_1.default.resolve(cwd);
-    const root = path_1.default.parse(current).root;
-    // Safety break and root check
-    // Using for(;;) to avoid no-constant-condition
-    for (;;) {
-        if (fs_extra_1.default.existsSync(path_1.default.join(current, '.agentctl'))) {
-            return current;
-        }
-        if (current === root) {
-            return null;
-        }
-        current = path_1.default.dirname(current);
-    }
+    return utils_1.UtilsLogic.findLocalRoot(cwd, fs_extra_1.default.existsSync);
 }

package/dist/index.js

@@ -1,147 +1,31 @@
 #!/usr/bin/env node
 "use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
-const path_1 = __importDefault(require("path"));
-require("fs-extra");
+const chalk_1 = __importDefault(require("chalk"));
 const ctl_1 = require("./ctl");
 const resolve_1 = require("./resolve");
-const child_process_1 = require("child_process");
-const chalk_1 = __importDefault(require("chalk"));
+const effects_1 = require("./effects");
+const index_1 = require("./logic/index");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const pkgPath = path_1.default.join(__dirname, '../package.json');
+const pkg = JSON.parse(fs_1.default.readFileSync(pkgPath, 'utf8'));
 const program = new commander_1.Command();
-// eslint-disable-next-line @typescript-eslint/no-var-requires
-const pkg = require('../package.json');
 program
     .name('agentctl')
     .description('Agent Controller CLI - Unified control plane for humans and agents')
-    .version(pkg.version)
-    .allowUnknownOption()
-    .helpOption(false) // Disable default help to allow pass-through
-    .argument('[command...]', 'Command to run')
-    .action((args, _options, _command) => __awaiter(void 0, void 0, void 0, function* () {
-    // If no args, check for help flag or just show help
-    if (!args || args.length === 0) {
-        // If they passed --help or -h, show help. If no args at all, show help.
-        // Since we ate options, we check raw args or just treat empty args as help.
-        // command.opts() won't have help if we disabled it? 
-        // Actually, if we disable helpOption, --help becomes an unknown option or arg.
-        // Let's check process.argv for -h or --help if args is empty?
-        // "agentctl --help" -> args=[], options might contain help if we didn't disable it?
-        // With helpOption(false), --help is just a flag in argv.
-        // If args is empty and we see help flag, show help.
-        if (process.argv.includes('--help') || process.argv.includes('-h') || process.argv.length <= 2) {
-            program.help();
-            return;
-        }
-    }
-    // If args are present, we try to resolve.
-    // BUT, "agentctl --help" will result in args being empty if it's parsed as option?
-    // Wait, if helpOption(false), then --help is an unknown option.
-    // If allowUnknownOption is true, it might not be in 'args' if it looks like a flag.
-    // Let's rely on resolveCommand. passed args are variadic.
-    // However, "agentctl dev --help" -> args=["dev", "--help"]? 
-    // My repro says yes: [ 'dev-tools', 'gh', '--help' ].
-    // So for "agentctl --help", args might be ["--help"].
-    if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
-        program.help();
-        return;
-    }
-    // Bypass for ctl subcommand if it slipped through (shouldn't if registered)
-    if (args[0] === 'ctl')
-        return;
-    try {
-        // resolveCommand needs to handle flags in args if they are part of the path?
-        // No, flags usually come after. resolveCommand stops at first non-matching path part?
-        // resolveCommand logic: iterates args.
-        // "dev-tools gh --help" -> path "dev-tools gh", remaining "--help"
-        const result = yield (0, resolve_1.resolveCommand)(args);
-        if (!result) {
-            // If not found, and they asked for help, show root help?
-            // Or if they just typed a wrong command.
-            if (args.includes('--help') || args.includes('-h')) {
-                // Try to show help for the partial command? 
-                // For now, just show root list/help or error.
-                // If it's "agentctl dev --help" and "dev" is a group, resolveCommand SHOULD return the group.
-            }
-            console.error(chalk_1.default.red(`Command '${args.join(' ')}' not found.`));
-            console.log(`Run ${chalk_1.default.cyan('agentctl list')} to see available commands.`);
-            process.exit(1);
-        }
-        const { manifest, args: remainingArgs, scope } = result;
-        if (manifest.run) {
-            // ... run logic ...
-            // remainingArgs should contain --help if it was passed.
-            const cmdDir = path_1.default.dirname(result.manifestPath);
-            let runCmd = manifest.run;
-            // Resolve relative path
-            if (runCmd.startsWith('./') || runCmd.startsWith('.\\')) {
-                runCmd = path_1.default.resolve(cmdDir, runCmd);
-            }
-            // Interpolate {{DIR}}
-            runCmd = runCmd.replace(/{{DIR}}/g, cmdDir);
-            const fullCommand = `${runCmd} ${remainingArgs.join(' ')}`;
-            console.log(chalk_1.default.dim(`[${scope}] Running: ${fullCommand}`));
-            const child = (0, child_process_1.spawn)(fullCommand, {
-                cwd: process.cwd(), // Execute in CWD as discussed
-                shell: true,
-                stdio: 'inherit',
-                env: Object.assign(Object.assign({}, process.env), { AGENTCTL_SCOPE: scope })
-            });
-            child.on('exit', (code) => {
-                process.exit(code || 0);
-            });
-        }
-        else {
-            // Group
-            console.log(chalk_1.default.blue(chalk_1.default.bold(`${manifest.name}`)));
-            console.log(manifest.description || 'No description');
-            console.log('\nSubcommands:');
-            const all = yield (0, ctl_1.list)();
-            const prefix = result.cmdPath + ' ';
-            // Filter logic roughly for direct children
-            const depth = result.cmdPath.split(' ').length;
-            const children = all.filter(c => c.path.startsWith(prefix) && c.path !== result.cmdPath);
-            const direct = children.filter(c => c.path.split(' ').length === depth + 1);
-            if (direct.length === 0 && children.length === 0) {
-                console.log(chalk_1.default.dim('  (No subcommands found)'));
-            }
-            for (const child of direct) {
-                console.log(`  ${child.path.split(' ').pop()}\t${chalk_1.default.dim(child.description)}`);
-            }
-        }
-    }
-    catch (e) {
-        if (e instanceof Error) {
-            console.error(chalk_1.default.red(e.message));
-        }
-        else {
-            console.error(chalk_1.default.red('An unknown error occurred'));
-        }
-        process.exit(1);
-    }
-}));
+    .version(pkg.version);
+// --- Subcommand: ctl ---
 const ctl = program.command('ctl')
-    .description('Agent Controller Management - Create, organizing, and managing commands');
-// --- Lifecycle Commands ---
-// We'll stick to flat list but with good descriptions.
-// Helper for consistent error handling
-// Helper for consistent error handling
+    .description('Agent Controller Management - Create, organize, and manage commands');
 const withErrorHandling = (fn) => {
-    return (...args) => __awaiter(void 0, void 0, void 0, function* () {
+    return async (...args) => {
         try {
-            yield fn(...args);
+            await fn(...args);
         }
         catch (e) {
             if (e instanceof Error) {
@@ -152,164 +36,304 @@ const withErrorHandling = (fn) => {
             }
             process.exit(1);
         }
-    });
+    };
 };
 ctl.command('scaffold')
-    .description('Create a new capped command with a script file')
-    .argument('<path...>', 'Command path segments (e.g., "dev start")')
+    .description('Scaffold a new command directory with a manifest and starter script.')
+    .argument('[path...]', 'Hierarchical path for the new command (e.g., "dev start" or "utils/cleanup")')
+    .summary('create a new command')
     .addHelpText('after', `
+Additional Info:
+  This command creates a folder in your local .agentctl directory.
+  Inside, it generates:
+    - manifest.json: Metadata about the command.
+    - command.sh/cmd: A starter script for your logic.
+
 Examples:
-  $ agentctl ctl scaffold dev start
-  $ agentctl ctl scaffold sys backup
+  $ agentctl ctl scaffold build front
+  $ agentctl ctl scaffold utils/backup
 `)
-    .action(withErrorHandling((pathParts) => __awaiter(void 0, void 0, void 0, function* () {
-    yield (0, ctl_1.scaffold)(pathParts);
-})));
+    .action(withErrorHandling(async (pathParts, opts, command) => {
+    if (!pathParts || pathParts.length === 0) {
+        command.help();
+        return;
+    }
+    await (0, ctl_1.scaffold)(pathParts);
+}));
 ctl.command('alias')
-    .description('Create a new capped command that runs an inline shell command')
-    .argument('<args...>', 'Name parts followed by target (e.g., "tools" "gh" "gh")')
-    .action(withErrorHandling((args) => __awaiter(void 0, void 0, void 0, function* () {
-    if (args.length < 2) {
-        console.error('Usage: ctl alias <name...> <target>');
-        process.exit(1);
+    .description('Create a command that executes a raw shell string.')
+    .argument('[args...]', 'Hierarchical path segments followed by the shell command target')
+    .summary('create a shell alias')
+    .addHelpText('after', `
+Examples:
+  $ agentctl ctl alias dev logs "docker compose logs -f"
+  $ agentctl ctl alias list-files "ls -la"
+`)
+    .action(withErrorHandling(async (args, opts, command) => {
+    if (!args || args.length < 2) {
+        command.help();
+        return;
     }
     const target = args.pop();
     const name = args;
-    yield (0, ctl_1.alias)(name, target);
-})))
-    .addHelpText('after', `
-Examples:
-  $ agentctl ctl alias tools gh "gh"
-  $ agentctl ctl alias dev build "npm run build"
-`);
+    await (0, ctl_1.alias)(name, target);
+}));
 ctl.command('group')
-    .description('Create a new command group (namespace)')
-    .argument('<path...>', 'Group path (e.g., "dev")')
+    .description('Create a command group (namespace) to organize subcommands.')
+    .argument('[path...]', 'Hierarchical path for the group (e.g., "dev" or "cloud/aws")')
+    .summary('create a namespace group')
     .addHelpText('after', `
+Additional Info:
+  Groups allow you to categorize commands. Running a group command without
+  subcommands will list all direct subcommands within that group.
+
 Examples:
   $ agentctl ctl group dev
-  $ agentctl ctl group tools
+  $ agentctl ctl group data/pipelines
 `)
-    .action(withErrorHandling((parts) => __awaiter(void 0, void 0, void 0, function* () {
-    yield (0, ctl_1.group)(parts);
-})));
+    .action(withErrorHandling(async (parts, opts, command) => {
+    if (!parts || parts.length === 0) {
+        command.help();
+        return;
+    }
+    await (0, ctl_1.group)(parts);
+}));
 ctl.command('rm')
-    .description('Remove a command or group permanently')
-    .argument('<path...>', 'Command path to remove')
-    .option('--global', 'Remove from global scope')
+    .description('Permanently remove a command or group.')
+    .argument('[path...]', 'Command path to remove')
+    .option('-g, --global', 'Remove from global scope instead of local')
+    .summary('delete a command')
     .addHelpText('after', `
 Examples:
   $ agentctl ctl rm dev start
-  $ agentctl ctl rm tools --global
+  $ agentctl ctl rm utils --global
 `)
-    .action(withErrorHandling((parts, opts) => __awaiter(void 0, void 0, void 0, function* () {
-    yield (0, ctl_1.rm)(parts, { global: opts.global });
-})));
+    .action(withErrorHandling(async (parts, opts, command) => {
+    if (!parts || parts.length === 0) {
+        command.help();
+        return;
+    }
+    await (0, ctl_1.rm)(parts, { global: opts.global });
+}));
 ctl.command('mv')
-    .description('Move a command or group to a new path')
-    .argument('<src>', 'Source path (quoted string or single token)')
-    .argument('<dest>', 'Destination path')
-    .option('--global', 'Move command in global scope')
+    .description('Move or rename a command/group within its current scope.')
+    .argument('[src]', 'Current path (space-separated or quoted)')
+    .argument('[dest]', 'New path (space-separated or quoted)')
+    .option('-g, --global', 'Operate in global scope')
+    .summary('rename/move a command')
     .addHelpText('after', `
 Examples:
-  $ agentctl ctl mv "dev start" "dev boot"
-  $ agentctl ctl mv tools/gh tools/github --global
+  $ agentctl ctl mv "dev start" "dev begin"
+  $ agentctl ctl mv utils scripts --global
 `)
-    .action(withErrorHandling((src, dest, opts) => __awaiter(void 0, void 0, void 0, function* () {
-    yield (0, ctl_1.mv)(src.split(' '), dest.split(' '), { global: opts.global });
-})));
-// --- Introspection ---
+    .action(withErrorHandling(async (src, dest, opts, command) => {
+    if (!src || !dest) {
+        command.help();
+        return;
+    }
+    await (0, ctl_1.mv)(src.split(' '), dest.split(' '), { global: opts.global });
+}));
 ctl.command('list')
-    .description('List all available commands across local and global scopes')
-    .action(withErrorHandling(() => __awaiter(void 0, void 0, void 0, function* () {
-    const items = yield (0, ctl_1.list)();
-    console.log('TYPE      SCOPE     COMMAND             DESCRIPTION');
+    .description('List all available commands across local and global scopes.')
+    .summary('list all commands')
+    .addHelpText('after', `
+Output Columns:
+  TYPE      - scaffold, alias, or group
+  SCOPE     - local (project-specific) or global (user-wide)
+  COMMAND   - The path used to invoke the command
+  DESCRIPTION - Brief text from the command's manifest
+`)
+    .action(withErrorHandling(async () => {
+    const items = await (0, ctl_1.list)();
+    console.log(chalk_1.default.bold('TYPE      SCOPE     COMMAND             DESCRIPTION'));
     for (const item of items) {
-        console.log(`${item.type.padEnd(9)} ${item.scope.padEnd(9)} ${item.path.padEnd(19)} ${item.description}`);
+        const typePipe = item.type.padEnd(9);
+        const scopePipe = item.scope === 'local' ? chalk_1.default.cyan(item.scope.padEnd(9)) : chalk_1.default.magenta(item.scope.padEnd(9));
+        console.log(`${typePipe} ${scopePipe} ${chalk_1.default.yellow(item.path.padEnd(19))} ${item.description}`);
     }
-})));
+}));
 ctl.command('inspect')
-    .description('Inspect the internal manifest and details of a command')
-    .argument('<path...>', 'Command path to inspect')
-    .action(withErrorHandling((parts) => __awaiter(void 0, void 0, void 0, function* () {
-    const info = yield (0, ctl_1.inspect)(parts);
+    .description('Show the internal manifest and file system path of a command.')
+    .argument('[path...]', 'Command path to inspect')
+    .summary('inspect command details')
+    .addHelpText('after', `
+Examples:
+  $ agentctl ctl inspect dev start
+`)
+    .action(withErrorHandling(async (parts, opts, command) => {
+    if (!parts || parts.length === 0) {
+        command.help();
+        return;
+    }
+    const info = await (0, ctl_1.inspect)(parts);
     if (info) {
         console.log(JSON.stringify(info, null, 2));
     }
     else {
-        console.error('Command not found');
+        console.error(chalk_1.default.red('Command not found'));
         process.exit(1);
     }
-})));
-// --- Scoping ---
+}));
 ctl.command('global')
-    .description('Push a local command to the global scope')
-    .argument('<path...>', 'Local command path')
-    .option('--move', 'Move instead of copy')
-    .option('--copy', 'Copy (default)')
+    .description('Promote a local command to the global scope.')
+    .argument('[path...]', 'Local command path to promote')
+    .option('-m, --move', 'Move the command (delete local after copying)')
+    .option('-c, --copy', 'Copy the command (keep local version, default)')
+    .summary('make a command global')
     .addHelpText('after', `
+Additional Info:
+  Global commands are stored in your home directory and are available in any project.
+
 Examples:
-  $ agentctl ctl global sys --move
-  $ agentctl ctl global tools --copy
+  $ agentctl ctl global utils/cleanup
+  $ agentctl ctl global dev/deploy --move
 `)
-    .action(withErrorHandling((parts, opts) => __awaiter(void 0, void 0, void 0, function* () {
-    yield (0, ctl_1.pushGlobal)(parts, { move: opts.move, copy: opts.copy || !opts.move });
-})));
+    .action(withErrorHandling(async (parts, opts, command) => {
+    if (!parts || parts.length === 0) {
+        command.help();
+        return;
+    }
+    await (0, ctl_1.pushGlobal)(parts, { move: opts.move, copy: opts.copy || !opts.move });
+}));
 ctl.command('local')
-    .description('Pull a global command to the local scope')
-    .argument('<path...>', 'Global command path')
-    .option('--move', 'Move instead of copy')
-    .option('--copy', 'Copy (default)')
+    .description('Pull a global command into the current local project.')
+    .argument('[path...]', 'Global command path to pull')
+    .option('-m, --move', 'Move the command (delete global after pulling)')
+    .option('-c, --copy', 'Copy the command (keep global version, default)')
+    .summary('make a command local')
     .addHelpText('after', `
 Examples:
-  $ agentctl ctl local tools --copy
+  $ agentctl ctl local utils/shared
+  $ agentctl ctl local snippets/js --move
 `)
-    .action(withErrorHandling((parts, opts) => __awaiter(void 0, void 0, void 0, function* () {
-    yield (0, ctl_1.pullLocal)(parts, { move: opts.move, copy: opts.copy || !opts.move });
-})));
-// --- Agent Integration ---
-// We attach this to the root `ctl` as options or a sub-command? 
-// Original code had it as options on `ctl`. We can make it a command for better help.
-// But sticking to options maintains compatibility. We'll improve the option help.
-ctl.option('--install-skill <agent>', 'Install skill for agent (cursor, antigravity, agentsmd, gemini)')
-    .option('--global', 'Install skill globally (for supported agents)')
+    .action(withErrorHandling(async (parts, opts, command) => {
+    if (!parts || parts.length === 0) {
+        command.help();
+        return;
+    }
+    await (0, ctl_1.pullLocal)(parts, { move: opts.move, copy: opts.copy || !opts.move });
+}));
+ctl.command('install-skill')
+    .description('Configure a supported AI agent (like Cursor or Gemini) to natively use Agentctl.')
+    .argument('[agent]', 'Agent name (cursor, antigravity, agentsmd, gemini)')
+    .option('-g, --global', 'Install globally for the agent (if supported)')
+    .summary('configure AI agent integration')
     .addHelpText('after', `
+Supported Agents:
+  - cursor      (Installs to .cursor/skills)
+  - antigravity (Installs to .agent/skills or ~/.gemini/antigravity)
+  - agentsmd    (Installs to .agents/skills)
+  - gemini      (Installs to .gemini/skills or ~/.gemini/skills)
+
 Examples:
-  $ agentctl ctl --install-skill cursor
-  $ agentctl ctl --install-skill antigravity --global
-  $ agentctl ctl --install-skill gemini
+  $ agentctl ctl install-skill cursor
+  $ agentctl ctl install-skill antigravity --global
 `)
-    .action(withErrorHandling((op, command) => __awaiter(void 0, void 0, void 0, function* () {
-    const opts = ctl.opts();
-    if (opts.installSkill) {
-        yield (0, ctl_1.installSkill)(opts.installSkill, { global: opts.global });
+    .action(withErrorHandling(async (agent, opts, command) => {
+    if (!agent) {
+        command.help();
+        return;
     }
-    else {
-        // If no subcmd and no option, show help
-        if (command.args.length === 0) {
-            ctl.help();
+    await (0, ctl_1.installSkill)(agent, { global: opts.global });
+}));
+ctl.command('install')
+    .description('Install a command group from a remote Git repository.')
+    .argument('[repoUrl]', 'URL of the remote Git repository containing an .agentctl folder')
+    .argument('[pathParts...]', 'Optional local namespace/group to install into')
+    .option('-g, --global', 'Install globally instead of locally')
+    .option('--allow-collisions', 'Allow overwriting existing commands or merging into groups')
+    .summary('install remote command group')
+    .addHelpText('after', `
+Additional Info:
+  Fetches the .agentctl folder from the remote repository and installs it into
+  your local or global agentctl environment.
+
+Examples:
+  $ agentctl ctl install https://github.com/org/repo-tools
+  $ agentctl ctl install https://github.com/org/deploy-scripts deploy --global
+`)
+    .action(withErrorHandling(async (repoUrl, pathParts, opts, command) => {
+    if (!repoUrl) {
+        command.help();
+        return;
+    }
+    await (0, ctl_1.install)(repoUrl, pathParts, { global: opts.global, allowCollisions: opts.allowCollisions });
+}));
+// --- Dynamic Command Logic ---
+async function handleDynamicCommand(args) {
+    try {
+        const result = await (0, resolve_1.resolveCommand)(args);
+        if (!result) {
+            const effects = index_1.AppLogic.planApp(args, null);
+            await (0, effects_1.execute)(effects.map(e => e.type === 'log' ? { ...e, message: chalk_1.default.red(e.message) } : e));
+            process.exit(1);
+        }
+        if (result.manifest.run) {
+            const effects = index_1.AppLogic.planApp(args, result);
+            await (0, effects_1.execute)(effects);
+        }
+        else {
+            const all = await (0, ctl_1.list)();
+            const effects = index_1.AppLogic.planGroupList(result.manifest, result.cmdPath, all);
+            await (0, effects_1.execute)(effects.map(e => {
+                if (e.type === 'log') {
+                    if (e.message === result.manifest.name)
+                        return { ...e, message: chalk_1.default.blue(chalk_1.default.bold(e.message)) };
+                    if (e.message === '\nSubcommands:')
+                        return e;
+                    if (e.message.startsWith('  '))
+                        return e;
+                    if (e.message === 'No description')
+                        return { ...e, message: chalk_1.default.dim(e.message) };
+                }
+                return e;
+            }));
+        }
+    }
+    catch (e) {
+        if (e instanceof Error) {
+            console.error(chalk_1.default.red(e.message));
+        }
+        else {
+            console.error(chalk_1.default.red('An unknown error occurred'));
         }
+        process.exit(1);
     }
-})));
-// Inject dynamic commands into root help
-// We need to do this before parsing
-(() => __awaiter(void 0, void 0, void 0, function* () {
+}
+(async () => {
+    // Add help text for user commands dynamically
     try {
-        const allCommands = yield (0, ctl_1.list)();
-        const topLevel = allCommands.filter(c => !c.path.includes(' ')); // Only top level
+        const allCommands = await (0, ctl_1.list)();
+        const topLevel = allCommands.filter(c => !c.path.includes(' '));
         if (topLevel.length > 0) {
             const lines = [''];
-            lines.push('User Commands:');
+            lines.push(chalk_1.default.bold('User Commands:'));
             for (const cmd of topLevel) {
-                // simple padding
-                lines.push(`  ${cmd.path.padEnd(27)}${cmd.description}`);
+                lines.push(`  ${chalk_1.default.yellow(cmd.path.padEnd(27))}${cmd.description}`);
             }
             lines.push('');
             program.addHelpText('after', lines.join('\n'));
         }
     }
-    catch (_a) {
-        // Ignore errors during help generation (e.g. if not initialized)
+    catch {
+        // Ignore errors during help generation
+    }
+    // Process arguments
+    const args = process.argv.slice(2);
+    // If no args, show help
+    if (args.length === 0) {
+        program.help();
+        return;
+    }
+    // Special case: if it starts with 'ctl', or is '--help', '--version', '-h', etc.,
+    // let commander handle it natively.
+    const firstArg = args[0];
+    const isStandardCommand = ['ctl', '--help', '-h', '--version', '-V'].includes(firstArg) || firstArg.startsWith('-');
+    if (isStandardCommand) {
+        program.parse(process.argv);
+    }
+    else {
+        // It's a dynamic command
+        await handleDynamicCommand(args);
     }
-    program.parse(process.argv);
-}))();
+})();