@michaelhartmayer/agentctl 1.0.0

package/.eslintignore

@@ -0,0 +1,5 @@
+dist/
+coverage/
+**/*.js
+!scripts/*.js
+!*.config.js

package/.eslintrc.json

@@ -0,0 +1,22 @@
+{
+    "parser": "@typescript-eslint/parser",
+    "plugins": [
+        "@typescript-eslint",
+        "eslint-comments"
+    ],
+    "extends": [
+        "eslint:recommended",
+        "plugin:@typescript-eslint/recommended",
+        "plugin:eslint-comments/recommended"
+    ],
+    "rules": {
+        "eslint-comments/no-use": "error",
+        "@typescript-eslint/no-explicit-any": "warn",
+        "@typescript-eslint/no-unused-vars": [
+            "error",
+            {
+                "argsIgnorePattern": "^_"
+            }
+        ]
+    }
+}

package/.husky/pre-commit

@@ -0,0 +1,2 @@
+npm run lint
+npm test

package/README.md

@@ -0,0 +1,124 @@
+# agentctl 🤖🛠️
+
+**One CLI to rule them all.**
+
+> **agentctl** is a unified control plane for humans and AI agents. It lets you build, organize, and manage command-line tools without frameworks or complex protocols. Just structured shell commands that anyone (or anything) can run.
+
+## Why?
+
+- **Zero Friction**: Turn any script or one-liner into a structured CLI command in seconds.
+- **Universal Interface**: Humans get a nice help menu; Agents get a discoverable toolset.
+- **Scoped Execution**: Keep project-specific commands in your repo (`.agentctl/`), and user-wide tools in your global config (`~/.config/agentctl/`).
+- **AI Native**: Built-in support for installing "skills" into AI coding assistants (Cursor, Antigravity, Gemini).
+
+---
+
+## Installation
+
+```bash
+npm install -g agentctl
+# or run directly
+npx agentctl <command>
+```
+
+## Quick Start
+
+### 1. Create a command
+Scaffold a new command. This creates a script file you can edit.
+
+```bash
+agentctl ctl scaffold "dev start"
+# Created .agentctl/dev/start/command.sh (or .cmd on Windows)
+```
+
+### 2. Run it
+```bash
+agentctl dev start
+# Executes your script!
+```
+
+### 3. Alias an existing tool
+Group your favorite tools under a unified namespace.
+
+```bash
+agentctl ctl group tools
+agentctl ctl alias "tools gh" gh
+agentctl ctl alias "tools slack" slack-cli
+
+agentctl tools
+# Lists available tools: gh, slack
+```
+
+---
+
+## Core Concepts
+
+### 📂 Groups & Commands
+- **Group**: A namespace (folder) that contains other commands.
+- **Command**: A leaf node that executes a script or binary.
+
+The filesystem **IS** the command tree.
+`.agentctl/dev/build/` → `agentctl dev build`
+
+### 🌍 Scoping
+
+**Local Scope**: `.agentctl/` in your current directory.
+- Ideal for project-specific workflows (build, test, deploy).
+- Check it into git to share with your team!
+
+**Global Scope**: `~/.config/agentctl/` (or `%APPDATA%\agentctl` on Windows).
+- Ideal for your personal toolbelt.
+- Access these commands from anywhere.
+
+**Move between scopes:**
+```bash
+# Move a local command to global scope
+agentctl ctl global "my-script" --move
+```
+
+---
+
+## Agent Integration 🧠
+
+`agentctl` is designed to be the bridge between you and your AI agents.
+
+### Install Skills
+Teach your AI agent how to use `agentctl` by installing a skill file.
+
+```bash
+# For Cursor / Windsurf / Antigravity
+agentctl ctl --install-skill cursor
+```
+
+### Headless Execution
+Run agentic workflows directly from the CLI.
+
+```bash
+# Run a headless Gemini session in the current directory
+agentctl agent headless-gemini . "refactor the formatting in src/"
+```
+*(Requires `gemini-cli` installed and authenticated)*
+
+---
+
+## Management Commands (`ctl`)
+
+The `ctl` subcommand is the meta-layer for managing `agentctl` itself.
+
+| Command | Description |
+|---|---|
+| `scaffold <path>` | Create a new script-based command |
+| `alias <path> <target>` | Create a command that runs another command |
+| `group <path>` | Create a new namespace |
+| `rm <path>` | Remove a command or group |
+| `mv <src> <dest>` | and/or rename a command |
+| `list` | Show all commands (local + global) |
+| `inspect <path>` | JSON dump of command manifest |
+| `global <path>` | Promote local command to global |
+| `local <path>` | Pull global command to local |
+
+---
+
+## License
+
+MIT

package/agentctl.cmd

@@ -0,0 +1,2 @@
+@echo off
+node "%~dp0\dist\index.js" %*

package/dist/ctl.js

@@ -0,0 +1,351 @@
+"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.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");
+function scaffold(args_1) {
+    return __awaiter(this, arguments, void 0, function* (args, options = {}) {
+        const { targetDir, name, isWin } = yield 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"';
+        yield fs_extra_1.default.writeFile(scriptPath, scriptContent);
+        if (!isWin)
+            yield fs_extra_1.default.chmod(scriptPath, 0o755);
+        const manifest = {
+            name,
+            description: '',
+            type: 'scaffold',
+            run: `./${scriptName}`,
+        };
+        yield fs_extra_1.default.writeJson(path_1.default.join(targetDir, 'manifest.json'), manifest, { spaces: 2 });
+        console.log(`Scaffolded command: ${args.join(' ')}`);
+    });
+}
+function alias(args_1, target_1) {
+    return __awaiter(this, arguments, void 0, function* (args, target, options = {}) {
+        const { targetDir, name } = yield prepareCommand(args, options);
+        const manifest = {
+            name,
+            description: '',
+            type: 'alias',
+            run: target,
+        };
+        yield fs_extra_1.default.writeJson(path_1.default.join(targetDir, 'manifest.json'), manifest, { spaces: 2 });
+        console.log(`Aliased command: ${args.join(' ')} -> ${target}`);
+    });
+}
+function group(args_1) {
+    return __awaiter(this, arguments, void 0, function* (args, options = {}) {
+        const { targetDir, name } = yield prepareCommand(args, options);
+        const manifest = {
+            name,
+            description: '',
+            type: 'group',
+        };
+        yield fs_extra_1.default.writeJson(path_1.default.join(targetDir, 'manifest.json'), manifest, { spaces: 2 });
+        console.log(`Created group: ${args.join(' ')}`);
+    });
+}
+function pushGlobal(args_1) {
+    return __awaiter(this, arguments, void 0, function* (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 (!(yield fs_extra_1.default.pathExists(srcDir))) {
+            throw new Error(`Local command ${args.join(' ')} not found`);
+        }
+        const destDir = path_1.default.join(globalRoot, cmdPathStr);
+        if (yield fs_extra_1.default.pathExists(destDir)) {
+            throw new Error(`Global command ${args.join(' ')} already exists`);
+        }
+        yield fs_extra_1.default.ensureDir(path_1.default.dirname(destDir));
+        if (options.move) {
+            yield fs_extra_1.default.move(srcDir, destDir);
+            console.log(`Moved ${args.join(' ')} to global scope`);
+        }
+        else {
+            yield fs_extra_1.default.copy(srcDir, destDir);
+            console.log(`Copied ${args.join(' ')} to global scope`);
+        }
+    });
+}
+function pullLocal(args_1) {
+    return __awaiter(this, arguments, void 0, function* (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 (!(yield 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 (yield fs_extra_1.default.pathExists(destDir)) {
+            throw new Error(`Local command ${args.join(' ')} already exists`);
+        }
+        yield fs_extra_1.default.ensureDir(path_1.default.dirname(destDir));
+        if (options.move) {
+            yield fs_extra_1.default.move(srcDir, destDir);
+            console.log(`Moved ${args.join(' ')} to local scope`);
+        }
+        else {
+            yield fs_extra_1.default.copy(srcDir, destDir);
+            console.log(`Copied ${args.join(' ')} to local scope`);
+        }
+    });
+}
+const skills_1 = require("./skills");
+function installSkill(agent_1) {
+    return __awaiter(this, arguments, void 0, function* (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 = yield (0, skills_1.copySkill)(targetDir, agent);
+        console.log(`Installed skill for ${agent} at ${p}`);
+    });
+}
+function rm(args_1) {
+    return __awaiter(this, arguments, void 0, function* (args, options = {}) {
+        const resolved = yield (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);
+        yield fs_extra_1.default.remove(targetDir);
+        console.log(`Removed ${resolved.scope} command: ${args.join(' ')}`);
+    });
+}
+function mv(srcArgs_1, destArgs_1) {
+    return __awaiter(this, arguments, void 0, function* (srcArgs, destArgs, options = {}) {
+        const resolved = yield (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 (yield 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 (yield 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);
+        }
+        yield fs_extra_1.default.move(srcDir, destDir);
+        // Update manifest name
+        const manifestPath = path_1.default.join(destDir, 'manifest.json');
+        if (yield fs_extra_1.default.pathExists(manifestPath)) {
+            const manifest = yield fs_extra_1.default.readJson(manifestPath);
+            manifest.name = destArgs[destArgs.length - 1];
+            yield fs_extra_1.default.writeJson(manifestPath, manifest, { spaces: 2 });
+        }
+        console.log(`Moved ${srcArgs.join(' ')} to ${destArgs.join(' ')}`);
+    });
+}
+function inspect(args_1) {
+    return __awaiter(this, arguments, void 0, function* (args, options = {}) {
+        const resolved = yield (0, resolve_1.resolveCommand)(args, options);
+        if (!resolved) {
+            return null;
+        }
+        return {
+            manifest: resolved.manifest,
+            resolvedPath: resolved.manifestPath,
+            scope: resolved.scope
+        };
+    });
+}
+function list() {
+    return __awaiter(this, arguments, void 0, function* (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();
+        function walk(dir, prefix, scope) {
+            return __awaiter(this, void 0, void 0, function* () {
+                if (!(yield fs_extra_1.default.pathExists(dir)))
+                    return;
+                const files = yield fs_extra_1.default.readdir(dir);
+                for (const file of files) {
+                    const filePath = path_1.default.join(dir, file);
+                    let stats;
+                    try {
+                        stats = yield fs_extra_1.default.stat(filePath);
+                    }
+                    catch (_a) {
+                        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 (yield fs_extra_1.default.pathExists(mPath)) {
+                        manifest = yield (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 === null || manifest === void 0 ? void 0 : manifest.description) || ''
+                    };
+                    if (!commands.has(cmdPath)) {
+                        commands.set(cmdPath, item);
+                        const effectiveManifest = manifest || { name: file, type: 'group' };
+                        if (!(0, manifest_1.isCappedManifest)(effectiveManifest)) {
+                            yield walk(filePath, cmdPathParts, scope);
+                        }
+                    }
+                    else {
+                        const existing = commands.get(cmdPath);
+                        if (existing && existing.scope === 'local') {
+                            if (existing.type === 'group' && type === 'group') {
+                                yield walk(filePath, cmdPathParts, scope);
+                            }
+                        }
+                    }
+                }
+            });
+        }
+        if (localRoot) {
+            yield walk(path_1.default.join(localRoot, '.agentctl'), [], 'local');
+        }
+        yield walk(globalRoot, [], 'global');
+        return Array.from(commands.values());
+    });
+}
+// Helpers
+function prepareCommand(args_1) {
+    return __awaiter(this, arguments, void 0, function* (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 (yield 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 (yield 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);
+        }
+        yield fs_extra_1.default.ensureDir(targetDir);
+        return {
+            targetDir,
+            name: args[args.length - 1],
+            isWin: process.platform === 'win32'
+        };
+    });
+}
+function isCapped(dir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const manifestPath = path_1.default.join(dir, 'manifest.json');
+        if (yield fs_extra_1.default.pathExists(manifestPath)) {
+            try {
+                const m = yield fs_extra_1.default.readJson(manifestPath);
+                return (0, manifest_1.isCappedManifest)(m);
+            }
+            catch (_a) {
+                return false;
+            }
+        }
+        return false;
+    });
+}
+function isSamePath(p1, p2) {
+    return path_1.default.relative(p1, p2) === '';
+}

package/dist/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);
+    }
+}