@michaelhartmayer/agentctl 1.0.2 → 1.0.3

package/dist/index.js

@@ -21,10 +21,12 @@ const resolve_1 = require("./resolve");
 const child_process_1 = require("child_process");
 const chalk_1 = __importDefault(require("chalk"));
 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('1.0.0')
+    .version(pkg.version)
     .allowUnknownOption()
     .helpOption(false) // Disable default help to allow pass-through
     .argument('[command...]', 'Command to run')

package/dist/package.json

@@ -0,0 +1,60 @@
+{
+    "name": "@michaelhartmayer/agentctl",
+    "publishConfig": {
+        "access": "public"
+    },
+    "description": "Agent Controller - A unified interface for humans and AI agents",
+    "version": "1.0.3",
+    "main": "dist/index.js",
+    "bin": {
+        "agentctl": "./dist/index.js"
+    },
+    "files": [
+        "dist",
+        "skills",
+        "scripts",
+        "agentctl.cmd",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "lint": "eslint src tests",
+        "register:path": "node scripts/register-path.js",
+        "unregister:path": "node scripts/unregister-path.js",
+        "release": "standard-version",
+        "prepublishOnly": "npm run build && npm run test",
+        "prepare": "husky"
+    },
+    "keywords": [
+        "cli",
+        "agent",
+        "ai",
+        "automation",
+        "framework"
+    ],
+    "author": "Michael Hartmayer",
+    "license": "MIT",
+    "dependencies": {
+        "chalk": "^4.1.2",
+        "commander": "^14.0.3",
+        "fs-extra": "^11.3.3"
+    },
+    "devDependencies": {
+        "@commitlint/cli": "^20.4.1",
+        "@commitlint/config-conventional": "^20.4.1",
+        "@types/fs-extra": "^11.0.4",
+        "@types/node": "^25.2.3",
+        "@typescript-eslint/eslint-plugin": "^8.55.0",
+        "@typescript-eslint/parser": "^8.55.0",
+        "@vitest/coverage-v8": "^4.0.18",
+        "eslint": "^8.57.1",
+        "eslint-plugin-eslint-comments": "^3.2.0",
+        "husky": "^9.1.7",
+        "standard-version": "^9.5.0",
+        "ts-node": "^10.9.2",
+        "typescript": "^5.9.3",
+        "vitest": "^4.0.18"
+    }
+}

package/dist/src/ctl.js

@@ -0,0 +1,316 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scaffold = scaffold;
+exports.alias = alias;
+exports.group = group;
+exports.pushGlobal = pushGlobal;
+exports.pullLocal = pullLocal;
+exports.installSkill = installSkill;
+exports.rm = rm;
+exports.mv = mv;
+exports.inspect = inspect;
+exports.list = list;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const resolve_1 = require("./resolve");
+const fs_utils_1 = require("./fs-utils");
+const manifest_1 = require("./manifest");
+async function scaffold(args, options = {}) {
+    const { targetDir, name, isWin } = await prepareCommand(args, options);
+    const scriptName = isWin ? 'command.cmd' : 'command.sh';
+    const scriptPath = path_1.default.join(targetDir, scriptName);
+    const scriptContent = isWin
+        ? '@echo off\r\nREM Add your command logic here\r\necho Not implemented'
+        : '#!/usr/bin/env bash\n# Add your command logic here\necho "Not implemented"';
+    await fs_extra_1.default.writeFile(scriptPath, scriptContent);
+    if (!isWin)
+        await fs_extra_1.default.chmod(scriptPath, 0o755);
+    const manifest = {
+        name,
+        description: '',
+        type: 'scaffold',
+        run: `./${scriptName}`,
+    };
+    await fs_extra_1.default.writeJson(path_1.default.join(targetDir, 'manifest.json'), manifest, { spaces: 2 });
+    console.log(`Scaffolded command: ${args.join(' ')}`);
+}
+async function alias(args, target, options = {}) {
+    const { targetDir, name } = await prepareCommand(args, options);
+    const manifest = {
+        name,
+        description: '',
+        type: 'alias',
+        run: target,
+    };
+    await fs_extra_1.default.writeJson(path_1.default.join(targetDir, 'manifest.json'), manifest, { spaces: 2 });
+    console.log(`Aliased command: ${args.join(' ')} -> ${target}`);
+}
+async function group(args, options = {}) {
+    const { targetDir, name } = await prepareCommand(args, options);
+    const manifest = {
+        name,
+        description: '',
+        type: 'group',
+    };
+    await fs_extra_1.default.writeJson(path_1.default.join(targetDir, 'manifest.json'), manifest, { spaces: 2 });
+    console.log(`Created group: ${args.join(' ')}`);
+}
+async function pushGlobal(args, options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const localRoot = (0, fs_utils_1.findLocalRoot)(cwd);
+    if (!localRoot)
+        throw new Error('Not in a local context');
+    const globalRoot = options.globalDir || (0, fs_utils_1.getGlobalRoot)();
+    const localAgentctl = path_1.default.join(localRoot, '.agentctl');
+    const cmdPathStr = args.join(path_1.default.sep);
+    const srcDir = path_1.default.join(localAgentctl, cmdPathStr);
+    if (!await fs_extra_1.default.pathExists(srcDir)) {
+        throw new Error(`Local command ${args.join(' ')} not found`);
+    }
+    const destDir = path_1.default.join(globalRoot, cmdPathStr);
+    if (await fs_extra_1.default.pathExists(destDir)) {
+        throw new Error(`Global command ${args.join(' ')} already exists`);
+    }
+    await fs_extra_1.default.ensureDir(path_1.default.dirname(destDir));
+    if (options.move) {
+        await fs_extra_1.default.move(srcDir, destDir);
+        console.log(`Moved ${args.join(' ')} to global scope`);
+    }
+    else {
+        await fs_extra_1.default.copy(srcDir, destDir);
+        console.log(`Copied ${args.join(' ')} to global scope`);
+    }
+}
+async function pullLocal(args, options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const localRoot = (0, fs_utils_1.findLocalRoot)(cwd);
+    if (!localRoot)
+        throw new Error('Not in a local context');
+    const globalRoot = options.globalDir || (0, fs_utils_1.getGlobalRoot)();
+    const cmdPathStr = args.join(path_1.default.sep);
+    const srcDir = path_1.default.join(globalRoot, cmdPathStr);
+    if (!await fs_extra_1.default.pathExists(srcDir)) {
+        throw new Error(`Global command ${args.join(' ')} not found`);
+    }
+    const localAgentctl = path_1.default.join(localRoot, '.agentctl');
+    const destDir = path_1.default.join(localAgentctl, cmdPathStr);
+    if (await fs_extra_1.default.pathExists(destDir)) {
+        throw new Error(`Local command ${args.join(' ')} already exists`);
+    }
+    await fs_extra_1.default.ensureDir(path_1.default.dirname(destDir));
+    if (options.move) {
+        await fs_extra_1.default.move(srcDir, destDir);
+        console.log(`Moved ${args.join(' ')} to local scope`);
+    }
+    else {
+        await fs_extra_1.default.copy(srcDir, destDir);
+        console.log(`Copied ${args.join(' ')} to local scope`);
+    }
+}
+const skills_1 = require("./skills");
+async function installSkill(agent, options = {}) {
+    const cwd = options.cwd || process.cwd();
+    if (!skills_1.SUPPORTED_AGENTS.includes(agent)) {
+        throw new Error(`Agent '${agent}' not supported. Supported agents: ${skills_1.SUPPORTED_AGENTS.join(', ')}`);
+    }
+    let targetDir;
+    if (agent === 'cursor') {
+        targetDir = path_1.default.join(cwd, '.cursor', 'skills');
+    }
+    else if (agent === 'antigravity') {
+        if (options.global) {
+            const globalRoot = options.antigravityGlobalDir || (0, fs_utils_1.getAntigravityGlobalRoot)();
+            targetDir = path_1.default.join(globalRoot, 'skills', 'agentctl');
+        }
+        else {
+            targetDir = path_1.default.join(cwd, '.agent', 'skills', 'agentctl');
+        }
+    }
+    else if (agent === 'agentsmd') {
+        targetDir = path_1.default.join(cwd, '.agents', 'skills', 'agentctl');
+    }
+    else if (agent === 'gemini') {
+        if (options.global) {
+            const globalRoot = options.geminiGlobalDir || path_1.default.join(process.env.HOME || process.env.USERPROFILE, '.gemini');
+            targetDir = path_1.default.join(globalRoot, 'skills', 'agentctl');
+        }
+        else {
+            targetDir = path_1.default.join(cwd, '.gemini', 'skills', 'agentctl');
+        }
+    }
+    else {
+        throw new Error(`Agent logic for '${agent}' not implemented.`);
+    }
+    const p = await (0, skills_1.copySkill)(targetDir, agent);
+    console.log(`Installed skill for ${agent} at ${p}`);
+}
+async function rm(args, options = {}) {
+    const resolved = await (0, resolve_1.resolveCommand)(args, options);
+    if (!resolved) {
+        throw new Error(`Command ${args.join(' ')} not found${options.global ? ' in global scope' : ''}`);
+    }
+    const targetDir = path_1.default.dirname(resolved.manifestPath);
+    await fs_extra_1.default.remove(targetDir);
+    console.log(`Removed ${resolved.scope} command: ${args.join(' ')}`);
+}
+async function mv(srcArgs, destArgs, options = {}) {
+    const resolved = await (0, resolve_1.resolveCommand)(srcArgs, options);
+    if (!resolved) {
+        throw new Error(`Command ${srcArgs.join(' ')} not found`);
+    }
+    const srcDir = path_1.default.dirname(resolved.manifestPath);
+    const rootDir = resolved.scope === 'local'
+        ? (0, fs_utils_1.findLocalRoot)(options.cwd || process.cwd())
+        : (options.globalDir || (0, fs_utils_1.getGlobalRoot)());
+    if (!rootDir)
+        throw new Error('Cannot determine root for move');
+    const agentctlDir = resolved.scope === 'local' ? path_1.default.join(rootDir, '.agentctl') : rootDir;
+    // For global, rootDir IS the agentctl dir (config dir). Local has .agentctl subdir.
+    const destPathStr = destArgs.join(path_1.default.sep);
+    const destDir = path_1.default.join(agentctlDir, destPathStr);
+    if (await fs_extra_1.default.pathExists(destDir)) {
+        throw new Error(`Destination ${destArgs.join(' ')} already exists`);
+    }
+    // Check parent validity (nesting under capped)
+    let current = path_1.default.dirname(destDir);
+    while (current.length >= agentctlDir.length && !isSamePath(current, path_1.default.dirname(agentctlDir))) {
+        if (await isCapped(current)) {
+            const relPath = path_1.default.relative(agentctlDir, current); // relative to base
+            throw new Error(`Cannot nest command under capped command: ${relPath}`);
+        }
+        current = path_1.default.dirname(current);
+    }
+    await fs_extra_1.default.move(srcDir, destDir);
+    // Update manifest name
+    const manifestPath = path_1.default.join(destDir, 'manifest.json');
+    if (await fs_extra_1.default.pathExists(manifestPath)) {
+        const manifest = await fs_extra_1.default.readJson(manifestPath);
+        manifest.name = destArgs[destArgs.length - 1];
+        await fs_extra_1.default.writeJson(manifestPath, manifest, { spaces: 2 });
+    }
+    console.log(`Moved ${srcArgs.join(' ')} to ${destArgs.join(' ')}`);
+}
+async function inspect(args, options = {}) {
+    const resolved = await (0, resolve_1.resolveCommand)(args, options);
+    if (!resolved) {
+        return null;
+    }
+    return {
+        manifest: resolved.manifest,
+        resolvedPath: resolved.manifestPath,
+        scope: resolved.scope
+    };
+}
+async function list(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const localRoot = (0, fs_utils_1.findLocalRoot)(cwd);
+    const globalRoot = options.globalDir || (0, fs_utils_1.getGlobalRoot)();
+    const commands = new Map();
+    async function walk(dir, prefix, scope) {
+        if (!await fs_extra_1.default.pathExists(dir))
+            return;
+        const files = await fs_extra_1.default.readdir(dir);
+        for (const file of files) {
+            const filePath = path_1.default.join(dir, file);
+            let stats;
+            try {
+                stats = await fs_extra_1.default.stat(filePath);
+            }
+            catch {
+                continue;
+            }
+            if (!stats.isDirectory())
+                continue;
+            const cmdPathParts = [...prefix, file];
+            const cmdPath = cmdPathParts.join(' ');
+            let manifest = null;
+            const mPath = path_1.default.join(filePath, 'manifest.json');
+            if (await fs_extra_1.default.pathExists(mPath)) {
+                manifest = await (0, manifest_1.readManifest)(mPath);
+            }
+            let type = 'group';
+            if (manifest) {
+                if ((0, manifest_1.isCappedManifest)(manifest)) {
+                    type = manifest.type || 'scaffold';
+                }
+                else if (manifest.type) {
+                    type = manifest.type;
+                }
+            }
+            const item = {
+                path: cmdPath,
+                type,
+                scope,
+                description: manifest?.description || ''
+            };
+            if (!commands.has(cmdPath)) {
+                commands.set(cmdPath, item);
+                const effectiveManifest = manifest || { name: file, type: 'group' };
+                if (!(0, manifest_1.isCappedManifest)(effectiveManifest)) {
+                    await walk(filePath, cmdPathParts, scope);
+                }
+            }
+            else {
+                const existing = commands.get(cmdPath);
+                if (existing && existing.scope === 'local') {
+                    if (existing.type === 'group' && type === 'group') {
+                        await walk(filePath, cmdPathParts, scope);
+                    }
+                }
+            }
+        }
+    }
+    if (localRoot) {
+        await walk(path_1.default.join(localRoot, '.agentctl'), [], 'local');
+    }
+    await walk(globalRoot, [], 'global');
+    return Array.from(commands.values());
+}
+// Helpers
+async function prepareCommand(args, options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const rootDir = cwd;
+    const agentctlDir = path_1.default.join(rootDir, '.agentctl');
+    if (args.length === 0)
+        throw new Error('No command path provided');
+    const cmdPath = args.join(path_1.default.sep);
+    const targetDir = path_1.default.join(agentctlDir, cmdPath);
+    if (await fs_extra_1.default.pathExists(targetDir)) {
+        throw new Error(`Command ${args.join(' ')} already exists`);
+    }
+    let current = path_1.default.dirname(targetDir);
+    while (current.length >= agentctlDir.length && !isSamePath(current, path_1.default.dirname(agentctlDir))) {
+        if (await isCapped(current)) {
+            const relPath = path_1.default.relative(agentctlDir, current); // This uses cwd for resolution if agentctlDir is cwd resolved
+            // Need to verify relative works predictably
+            // agentctlDir comes from path.join(cwd, '.agentctl').
+            throw new Error(`Cannot nest command under capped command: ${relPath}`);
+        }
+        current = path_1.default.dirname(current);
+    }
+    await fs_extra_1.default.ensureDir(targetDir);
+    return {
+        targetDir,
+        name: args[args.length - 1],
+        isWin: process.platform === 'win32'
+    };
+}
+async function isCapped(dir) {
+    const manifestPath = path_1.default.join(dir, 'manifest.json');
+    if (await fs_extra_1.default.pathExists(manifestPath)) {
+        try {
+            const m = await fs_extra_1.default.readJson(manifestPath);
+            return (0, manifest_1.isCappedManifest)(m);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+function isSamePath(p1, p2) {
+    return path_1.default.relative(p1, p2) === '';
+}

package/dist/src/fs-utils.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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"));
+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');
+}
+function getAntigravityGlobalRoot() {
+    return path_1.default.join(os_1.default.homedir(), '.gemini', 'antigravity');
+}
+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);
+    }
+}

package/dist/src/index.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+"use strict";
+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 ctl_1 = require("./ctl");
+const resolve_1 = require("./resolve");
+const child_process_1 = require("child_process");
+const chalk_1 = __importDefault(require("chalk"));
+const program = new commander_1.Command();
+const package_json_1 = __importDefault(require("../package.json"));
+program
+    .name('agentctl')
+    .description('Agent Controller CLI - Unified control plane for humans and agents')
+    .version(package_json_1.default.version)
+    .allowUnknownOption()
+    .helpOption(false) // Disable default help to allow pass-through
+    .argument('[command...]', 'Command to run')
+    .action(async (args, _options, _command) => {
+    // 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 = await (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: { ...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 = await (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);
+    }
+});
+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
+const withErrorHandling = (fn) => {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (e) {
+            if (e instanceof Error) {
+                console.error(chalk_1.default.red(e.message));
+            }
+            else {
+                console.error(chalk_1.default.red(String(e)));
+            }
+            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")')
+    .addHelpText('after', `
+Examples:
+  $ agentctl ctl scaffold dev start
+  $ agentctl ctl scaffold sys backup
+`)
+    .action(withErrorHandling(async (pathParts) => {
+    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(async (args) => {
+    if (args.length < 2) {
+        console.error('Usage: ctl alias <name...> <target>');
+        process.exit(1);
+    }
+    const target = args.pop();
+    const name = args;
+    await (0, ctl_1.alias)(name, target);
+}))
+    .addHelpText('after', `
+Examples:
+  $ agentctl ctl alias tools gh "gh"
+  $ agentctl ctl alias dev build "npm run build"
+`);
+ctl.command('group')
+    .description('Create a new command group (namespace)')
+    .argument('<path...>', 'Group path (e.g., "dev")')
+    .addHelpText('after', `
+Examples:
+  $ agentctl ctl group dev
+  $ agentctl ctl group tools
+`)
+    .action(withErrorHandling(async (parts) => {
+    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')
+    .addHelpText('after', `
+Examples:
+  $ agentctl ctl rm dev start
+  $ agentctl ctl rm tools --global
+`)
+    .action(withErrorHandling(async (parts, opts) => {
+    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')
+    .addHelpText('after', `
+Examples:
+  $ agentctl ctl mv "dev start" "dev boot"
+  $ agentctl ctl mv tools/gh tools/github --global
+`)
+    .action(withErrorHandling(async (src, dest, opts) => {
+    await (0, ctl_1.mv)(src.split(' '), dest.split(' '), { global: opts.global });
+}));
+// --- Introspection ---
+ctl.command('list')
+    .description('List all available commands across local and global scopes')
+    .action(withErrorHandling(async () => {
+    const items = await (0, ctl_1.list)();
+    console.log('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}`);
+    }
+}));
+ctl.command('inspect')
+    .description('Inspect the internal manifest and details of a command')
+    .argument('<path...>', 'Command path to inspect')
+    .action(withErrorHandling(async (parts) => {
+    const info = await (0, ctl_1.inspect)(parts);
+    if (info) {
+        console.log(JSON.stringify(info, null, 2));
+    }
+    else {
+        console.error('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)')
+    .addHelpText('after', `
+Examples:
+  $ agentctl ctl global sys --move
+  $ agentctl ctl global tools --copy
+`)
+    .action(withErrorHandling(async (parts, opts) => {
+    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)')
+    .addHelpText('after', `
+Examples:
+  $ agentctl ctl local tools --copy
+`)
+    .action(withErrorHandling(async (parts, opts) => {
+    await (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)')
+    .addHelpText('after', `
+Examples:
+  $ agentctl ctl --install-skill cursor
+  $ agentctl ctl --install-skill antigravity --global
+  $ agentctl ctl --install-skill gemini
+`)
+    .action(withErrorHandling(async (op, command) => {
+    const opts = ctl.opts();
+    if (opts.installSkill) {
+        await (0, ctl_1.installSkill)(opts.installSkill, { global: opts.global });
+    }
+    else {
+        // If no subcmd and no option, show help
+        if (command.args.length === 0) {
+            ctl.help();
+        }
+    }
+}));
+// Inject dynamic commands into root help
+// We need to do this before parsing
+(async () => {
+    try {
+        const allCommands = await (0, ctl_1.list)();
+        const topLevel = allCommands.filter(c => !c.path.includes(' ')); // Only top level
+        if (topLevel.length > 0) {
+            const lines = [''];
+            lines.push('User Commands:');
+            for (const cmd of topLevel) {
+                // simple padding
+                lines.push(`  ${cmd.path.padEnd(27)}${cmd.description}`);
+            }
+            lines.push('');
+            program.addHelpText('after', lines.join('\n'));
+        }
+    }
+    catch {
+        // Ignore errors during help generation (e.g. if not initialized)
+    }
+    program.parse(process.argv);
+})();

package/dist/src/manifest.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readManifest = readManifest;
+exports.isCappedManifest = isCappedManifest;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+async function readManifest(p) {
+    try {
+        return await fs_extra_1.default.readJson(p);
+    }
+    catch {
+        return null;
+    }
+}
+function isCappedManifest(m) {
+    return !!m.run || m.type === 'scaffold' || m.type === 'alias';
+}

package/dist/src/resolve.js

@@ -0,0 +1,112 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCommand = resolveCommand;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const fs_utils_1 = require("./fs-utils");
+const manifest_1 = require("./manifest");
+async function resolveCommand(args, options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const localRoot = !options.global ? (0, fs_utils_1.findLocalRoot)(cwd) : null;
+    const globalRoot = options.globalDir || (0, fs_utils_1.getGlobalRoot)();
+    const localAgentctl = localRoot ? path_1.default.join(localRoot, '.agentctl') : null;
+    let currentMatch = null;
+    // Iterate through args to find longest match
+    for (let i = 0; i < args.length; i++) {
+        // Path corresponding to args[0..i]
+        const currentArgs = args.slice(0, i + 1);
+        const relPath = currentArgs.join(path_1.default.sep);
+        const cmdPath = currentArgs.join(' ');
+        const localPath = localAgentctl ? path_1.default.join(localAgentctl, relPath) : null;
+        const globalPath = path_1.default.join(globalRoot, relPath);
+        let localManifest = null;
+        let globalManifest = null;
+        // check local
+        if (localPath && await fs_extra_1.default.pathExists(localPath)) {
+            const mPath = path_1.default.join(localPath, 'manifest.json');
+            if (await fs_extra_1.default.pathExists(mPath)) {
+                localManifest = await (0, manifest_1.readManifest)(mPath);
+            }
+            if (!localManifest && (await fs_extra_1.default.stat(localPath)).isDirectory()) {
+                // Implicit group
+                localManifest = { name: args[i], type: 'group' };
+            }
+        }
+        // check global
+        if (await fs_extra_1.default.pathExists(globalPath)) {
+            const mPath = path_1.default.join(globalPath, 'manifest.json');
+            if (await fs_extra_1.default.pathExists(mPath)) {
+                globalManifest = await (0, manifest_1.readManifest)(mPath);
+            }
+            if (!globalManifest && (await fs_extra_1.default.stat(globalPath)).isDirectory()) {
+                globalManifest = { name: args[i], type: 'group' };
+            }
+        }
+        if (!localManifest && !globalManifest) {
+            break;
+        }
+        const remainingArgs = args.slice(i + 1);
+        // Priority logic
+        // 1. Local Capped -> Return Match immediately.
+        if (localManifest && (0, manifest_1.isCappedManifest)(localManifest)) {
+            return {
+                manifest: localManifest,
+                manifestPath: path_1.default.join(localPath, 'manifest.json'),
+                args: remainingArgs,
+                scope: 'local',
+                cmdPath
+            };
+        }
+        // 2. Global Capped
+        if (globalManifest && (0, manifest_1.isCappedManifest)(globalManifest)) {
+            // Check if shadowed by Local Group
+            if (localManifest) {
+                // Local exists (must be group since checked capped above).
+                // Shadowed. Treat as Local Group.
+                currentMatch = {
+                    manifest: localManifest,
+                    manifestPath: path_1.default.join(localPath, 'manifest.json'),
+                    args: remainingArgs,
+                    scope: 'local',
+                    cmdPath
+                };
+            }
+            else {
+                // Not shadowed. Global Capped wins. Return immediately.
+                return {
+                    manifest: globalManifest,
+                    manifestPath: path_1.default.join(globalPath, 'manifest.json'),
+                    args: remainingArgs,
+                    scope: 'global',
+                    cmdPath
+                };
+            }
+        }
+        else {
+            // Neither is capped. Both are groups (or one is).
+            // Local wins if exists.
+            if (localManifest) {
+                currentMatch = {
+                    manifest: localManifest,
+                    manifestPath: path_1.default.join(localPath, 'manifest.json'),
+                    args: remainingArgs,
+                    scope: 'local',
+                    cmdPath
+                };
+            }
+            else {
+                currentMatch = {
+                    manifest: globalManifest,
+                    manifestPath: path_1.default.join(globalPath, 'manifest.json'),
+                    args: remainingArgs,
+                    scope: 'global',
+                    cmdPath
+                };
+            }
+        }
+    }
+    return currentMatch;
+}

package/dist/src/skills.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_AGENTS = void 0;
+exports.copySkill = copySkill;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+exports.SUPPORTED_AGENTS = ['cursor', 'antigravity', 'agentsmd', 'gemini'];
+async function copySkill(targetDir, agent) {
+    // We assume the skill file is located at ../skills/agentctl/SKILL.md relative to specific dist/src/ location
+    // Or we find it in the project root if running from source.
+    // In production (dist), structure might be:
+    // dist/index.js
+    // skills/agentctl/SKILL.md (if we copy it to dist)
+    // Let's try to locate the source SKILL.md
+    // If we are in /src, it is in ../skills/agentctl/SKILL.md
+    // If we are in /dist/src (tsc default?), it depends on build.
+    // Robust finding:
+    let sourcePath = path_1.default.resolve(__dirname, '../../skills/agentctl/SKILL.md');
+    if (!fs_extra_1.default.existsSync(sourcePath)) {
+        // Try looking in src check (dev mode)
+        sourcePath = path_1.default.resolve(__dirname, '../skills/agentctl/SKILL.md');
+    }
+    if (!fs_extra_1.default.existsSync(sourcePath)) {
+        // Fallback for when running from dist/src
+        sourcePath = path_1.default.resolve(__dirname, '../../../skills/agentctl/SKILL.md');
+    }
+    if (!fs_extra_1.default.existsSync(sourcePath)) {
+        throw new Error(`Could not locate source SKILL.md. Checked: ${path_1.default.resolve(__dirname, '../../skills/agentctl/SKILL.md')}`);
+    }
+    await fs_extra_1.default.ensureDir(targetDir);
+    // Determine filename
+    const filename = agent === 'cursor' ? 'agentctl.md' : 'SKILL.md';
+    const targetFile = path_1.default.join(targetDir, filename);
+    await fs_extra_1.default.copy(sourcePath, targetFile, { overwrite: true });
+    return targetFile;
+}

package/package.json

@@ -4,7 +4,7 @@
     "access": "public"
   },
   "description": "Agent Controller - A unified interface for humans and AI agents",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "main": "dist/index.js",
   "bin": {
     "agentctl": "./dist/index.js"