@michaelhartmayer/agentctl 1.0.0

package/dist/index.js

@@ -0,0 +1,313 @@
+#!/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 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();
+program
+    .name('agentctl')
+    .description('Agent Controller CLI - Unified control plane for humans and agents')
+    .version('1.0.0')
+    .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);
+    }
+}));
+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 (...args) => __awaiter(void 0, void 0, void 0, function* () {
+        try {
+            yield 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((pathParts) => __awaiter(void 0, void 0, void 0, function* () {
+    yield (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);
+    }
+    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"
+`);
+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((parts) => __awaiter(void 0, void 0, void 0, function* () {
+    yield (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((parts, opts) => __awaiter(void 0, void 0, void 0, function* () {
+    yield (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((src, dest, opts) => __awaiter(void 0, void 0, void 0, function* () {
+    yield (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(() => __awaiter(void 0, void 0, void 0, function* () {
+    const items = yield (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((parts) => __awaiter(void 0, void 0, void 0, function* () {
+    const info = yield (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((parts, opts) => __awaiter(void 0, void 0, void 0, function* () {
+    yield (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((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)')
+    .addHelpText('after', `
+Examples:
+  $ agentctl ctl --install-skill cursor
+  $ agentctl ctl --install-skill antigravity --global
+  $ agentctl ctl --install-skill gemini
+`)
+    .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 });
+    }
+    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
+(() => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const allCommands = yield (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 (_a) {
+        // Ignore errors during help generation (e.g. if not initialized)
+    }
+    program.parse(process.argv);
+}))();

package/dist/manifest.js

@@ -0,0 +1,30 @@
+"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 });
+exports.readManifest = readManifest;
+exports.isCappedManifest = isCappedManifest;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+function readManifest(p) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            return yield fs_extra_1.default.readJson(p);
+        }
+        catch (_a) {
+            return null;
+        }
+    });
+}
+function isCappedManifest(m) {
+    return !!m.run || m.type === 'scaffold' || m.type === 'alias';
+}

package/dist/resolve.js

@@ -0,0 +1,123 @@
+"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 });
+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");
+function resolveCommand(args_1) {
+    return __awaiter(this, arguments, void 0, function* (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 && (yield fs_extra_1.default.pathExists(localPath))) {
+                const mPath = path_1.default.join(localPath, 'manifest.json');
+                if (yield fs_extra_1.default.pathExists(mPath)) {
+                    localManifest = yield (0, manifest_1.readManifest)(mPath);
+                }
+                if (!localManifest && (yield fs_extra_1.default.stat(localPath)).isDirectory()) {
+                    // Implicit group
+                    localManifest = { name: args[i], type: 'group' };
+                }
+            }
+            // check global
+            if (yield fs_extra_1.default.pathExists(globalPath)) {
+                const mPath = path_1.default.join(globalPath, 'manifest.json');
+                if (yield fs_extra_1.default.pathExists(mPath)) {
+                    globalManifest = yield (0, manifest_1.readManifest)(mPath);
+                }
+                if (!globalManifest && (yield 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/skills.js

@@ -0,0 +1,50 @@
+"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 });
+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'];
+function copySkill(targetDir, agent) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // 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')}`);
+        }
+        yield fs_extra_1.default.ensureDir(targetDir);
+        // Determine filename
+        const filename = agent === 'cursor' ? 'agentctl.md' : 'SKILL.md';
+        const targetFile = path_1.default.join(targetDir, filename);
+        yield fs_extra_1.default.copy(sourcePath, targetFile, { overwrite: true });
+        return targetFile;
+    });
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@michaelhartmayer/agentctl",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Agent Controller - A unified interface for humans and AI agents",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "bin": {
+    "agentctl": "./dist/index.js"
+  },
+  "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",
+    "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": {
+    "@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",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/scripts/register-path.js

@@ -0,0 +1,32 @@
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const binDir = path.resolve(__dirname, '..');
+
+// Create wrapper scripts for direct execution
+const cmdContent = `@echo off\r\nnode "%~dp0\\dist\\index.js" %*`;
+fs.writeFileSync(path.join(binDir, 'agentctl.cmd'), cmdContent);
+
+if (process.platform === 'win32') {
+    try {
+        const currentPath = execSync('powershell -Command "[Environment]::GetEnvironmentVariable(\'Path\', \'User\')"').toString().trim();
+        if (!currentPath.includes(binDir)) {
+            const newPath = currentPath + (currentPath.endsWith(';') ? '' : ';') + binDir;
+            // Use setx for persistence but beware truncation. Powershell is safer for full string.
+            // But setx /M needs admin. User path doesn't.
+            // Powershell approach:
+            const psCommand = `[Environment]::SetEnvironmentVariable('Path', '${newPath}', 'User')`;
+            execSync(`powershell -Command "${psCommand}"`);
+            console.log(`Successfully added ${binDir} to User PATH.`);
+            console.log('You may need to restart your terminal/shell for changes to take effect.');
+        } else {
+            console.log(`${binDir} is already in User PATH.`);
+        }
+    } catch (error) {
+        console.error('Failed to register path:', error.message);
+        process.exit(1);
+    }
+} else {
+    console.log('Path registration script currently supports Windows only.');
+}

package/scripts/unregister-path.js

@@ -0,0 +1,30 @@
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const binDir = path.resolve(__dirname, '..');
+
+if (process.platform === 'win32') {
+    try {
+        const currentPath = execSync('powershell -Command "[Environment]::GetEnvironmentVariable(\'Path\', \'User\')"').toString().trim();
+        if (currentPath.includes(binDir)) {
+            // split by ; to safely remove exactly our path
+            const paths = currentPath.split(';').filter(p => p && path.resolve(p) !== binDir);
+            const newPath = paths.join(';');
+
+            const psCommand = `[Environment]::SetEnvironmentVariable('Path', '${newPath}', 'User')`;
+            execSync(`powershell -Command "${psCommand}"`);
+            console.log(`Successfully removed ${binDir} from User PATH.`);
+        } else {
+            console.log(`${binDir} is not in User PATH.`);
+        }
+    } catch (error) {
+        console.error('Failed to unregister path:', error.message);
+        process.exit(1);
+    }
+}
+
+// Clean up wrapper
+if (fs.existsSync(path.join(binDir, 'agentctl.cmd'))) {
+    fs.unlinkSync(path.join(binDir, 'agentctl.cmd'));
+}