@michaelhartmayer/agentctl 1.1.0 → 1.1.4

package/README.md

@@ -90,14 +90,31 @@ Teach your AI agent how to use `agentctl` by installing a skill file.
 agentctl ctl --install-skill cursor
 ```
 
-### Headless Execution
-Run agentic workflows directly from the CLI.
+### Provide the proper help copy
+When creating commands, make sure the `manifest.json` properly scopes its information:
+- `description`: A short summary of the command, displayed when viewing the list of available commands.
+- `help`: A longer set of instructions/usage string. For `group` types, this is displayed when calling the group without a subcommand. For `scaffold` types, this is currently for reference only; your command script must manually handle an `--help` flag for detailed usage.
+
+#### Scaffold Schema
+```json
+{
+  "name": "<command_folder_name>",
+  "description": "<insert command summary here>",
+  "help": "<insert longer usage/help instructions here>",
+  "type": "scaffold",
+  "run": "./command.cmd"
+}
+```
 
-```bash
-# Run a headless Gemini session in the current directory
-agentctl agent headless-gemini . "refactor the formatting in src/"
+#### Group Schema
+```json
+{
+  "name": "<group_folder_name>",
+  "description": "<insert group summary here>",
+  "help": "<insert longer group description/instructions here>",
+  "type": "group"
+}
 ```
-*(Requires `gemini-cli` installed and authenticated)*
 
 ---
 
@@ -105,17 +122,119 @@ agentctl agent headless-gemini . "refactor the formatting in src/"
 
 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 |
+### `agentctl ctl scaffold <path>`
+Create a new script-based command. This generates a folder containing a `manifest.json` and a starter script (`command.cmd`/`command.sh`) for your logic.
+- **Why it's great:** Automates the boilerplate of creating a new CLI tool.
+- **When to use it:** When you have a complex script or an arbitrary executable (Node, Python, Go) you want to expose easily via the CLI.
+```bash
+agentctl ctl scaffold build:front
+agentctl ctl scaffold "build server" # Creates group 'build' and subcommand 'server'
+```
+
+### `agentctl ctl group <path>`
+Create a new namespace to organize subcommands. 
+- **Why it's great:** Keeps your CLI clean by grouping related tools without forcing you to write a parent CLI router.
+- **When to use it:** When you have a collection of similar commands (e.g., `db migrate`, `db reset`) and want an organized help menu grouping them under `db`.
+```bash
+agentctl ctl group data # Creates 'data' group
+agentctl ctl group "cloud aws" # Creates nested 'cloud/aws' groups
+```
+
+### `agentctl ctl alias <path> <target>`
+Create a command that simply runs an existing binary, string, or target.
+- **Why it's great:** Replaces bash aliases with structured, documentable commands that work locally or globally across environments and OSes.
+- **When to use it:** When you have a long, frequently used string (`docker compose run --rm node npm install`) and want a short name (`agentctl npm install`) without needing a whole generated shell script.
+```bash
+agentctl ctl alias "tools gh" gh
+agentctl ctl alias list-files "ls -la"
+```
+
+### `agentctl ctl rm [options] <path>`
+Permanently remove a command or entire group from your workspace.
+- **Why it's great:** Quickly clean up old tooling right from the CLI without needing to manually delete `.agentctl` directories.
+- **When to use it:** When retiring a script or cleaning up an obsolete group.
+
+**Options:**
+- `-g, --global`: Remove from global scope instead of local
+
+```bash
+agentctl ctl rm build:front # Removes local 'build front' command
+agentctl ctl rm mytool --global # Removes global 'mytool' command
+```
+
+### `agentctl ctl mv [options] <src> <dest>`
+Rename a command or move it to a new group/namespace.
+- **Why it's great:** Refactor your CLI commands like you'd refactor code, moving logic around namespaces without breaking the underlying executed scripts.
+- **When to use it:** When restructuring your toolbelt from a flat list to a nested categorization.
+
+**Options:**
+- `-g, --global`: Operate in global scope
+
+```bash
+agentctl ctl mv mytool my-new-tool
+agentctl ctl mv "tools ping" "network ping"
+agentctl ctl mv "tools ping" "network ping" --global # Moves in global scope
+```
+
+### `agentctl ctl list [options]`
+List all currently available commands across both your local and global scopes.
+- **Why it's great:** Generates an easy-to-read JSON summary of everything your agent can do.
+- **When to use it:** When programming an agent or exploring what tooling is available in a scoped project.
+
+```bash
+agentctl ctl list
+```
+
+### `agentctl ctl inspect [options] <path>`
+Dump the resolved manifest and location of a given command path.
+- **Why it's great:** Eliminates the "where did this command come from?" problem when debugging complex workspaces.
+- **When to use it:** When you have local/global conflicts or want to quickly see the JSON source manifest for a command.
+```bash
+agentctl ctl inspect dev:start
+```
+
+### `agentctl ctl global [options] <path>`
+Promote a local command or group to your globally available toolbelt.
+- **Why it's great:** Eject highly useful, generic project abstractions directly into your personal universal toolbelt.
+- **When to use it:** You wrote a script specific to a project and realized "I want this CLI tool in every repo I touch."
+
+**Options:**
+- `-c, --copy`: Copy the command (keep local version, default)
+- `-m, --move`: Move the command (delete local after copying)
+
+```bash
+agentctl ctl global "dev toolkit" # Copies the command to global scope
+agentctl ctl global "dev toolkit" --move # Moves it instead of copy
+```
+
+### `agentctl ctl local [options] <path>`
+Bring a global command down into the current local project environment.
+- **Why it's great:** Promotes collaboration seamlessly. You can take your personal script, localize it, and commit it to git for your entire team.
+- **When to use it:** You have a generic tool that is suddenly very relevant to a specific repository, and you want CI or your coworkers to access it.
+
+**Options:**
+- `-c, --copy`: Copy the command (keep global version, default)
+- `-m, --move`: Move the command (delete global after pulling)
+
+```bash
+agentctl ctl local "my global-tool"
+agentctl ctl local "my global-tool" --move
+```
+
+### `agentctl ctl install [options] <repo-url> [path...]`
+Install commands or groups directly from a remote Git repository's `.agentctl` folder into your local or global scope.
+- **Why it's great:** Provides dependency-free tool sharing! Distribute entire suites of scripts/commands without using a package manager.
+- **When to use it:** When you want to pull down shared utility commands that your team maintains in a central repository, or distribute your own tools to others.
+
+**Options:**
+- `-g, --global`: Install globally instead of locally
+- `--allow-collisions`: Allow overwriting existing commands or merging into groups
+
+```bash
+agentctl ctl install https://github.com/my-org/tools
+agentctl ctl install https://github.com/my-org/tools --global
+agentctl ctl install https://github.com/my-org/tools deploy --allow-collisions
+```
 
 ---
 

package/dist/ctl.js

@@ -8,206 +8,208 @@ 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.installSkill = installSkill;
+exports.install = install;
 exports.list = list;
-const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
-const resolve_1 = require("./resolve");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const os_1 = __importDefault(require("os"));
 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}`,
+const resolve_1 = require("./resolve");
+const effects_1 = require("./effects");
+const ctl_1 = require("./logic/ctl");
+const install_1 = require("./logic/install");
+async function getCappedAncestor(dir, baseDir) {
+    let current = path_1.default.dirname(dir);
+    while (current.length >= baseDir.length && current !== path_1.default.dirname(baseDir)) {
+        const mPath = path_1.default.join(current, 'manifest.json');
+        if (await fs_extra_1.default.pathExists(mPath)) {
+            try {
+                const m = await fs_extra_1.default.readJson(mPath);
+                if ((0, manifest_1.isCappedManifest)(m)) {
+                    return { path: current, relPath: path_1.default.relative(baseDir, current) };
+                }
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        current = path_1.default.dirname(current);
+    }
+    return null;
+}
+async function getContext(options) {
+    const cwd = options.cwd || process.cwd();
+    return {
+        cwd: path_1.default.resolve(cwd),
+        platform: process.platform,
+        localRoot: (0, fs_utils_1.findLocalRoot)(cwd),
+        globalRoot: options.globalDir || (0, fs_utils_1.getGlobalRoot)(),
+        homedir: process.env.HOME || process.env.USERPROFILE || os_1.default.homedir()
     };
-    await fs_extra_1.default.writeJson(path_1.default.join(targetDir, 'manifest.json'), manifest, { spaces: 2 });
-    console.log(`Scaffolded command: ${args.join(' ')}`);
+}
+async function scaffold(args, options = {}) {
+    const ctx = await getContext(options);
+    const localRoot = ctx.localRoot || ctx.cwd;
+    const agentctlDir = path_1.default.join(localRoot, '.agentctl');
+    const targetDir = path_1.default.join(agentctlDir, args.join(path_1.default.sep));
+    const exists = await fs_extra_1.default.pathExists(targetDir);
+    const cappedAncestor = await getCappedAncestor(targetDir, agentctlDir);
+    const { effects } = ctl_1.Logic.planScaffold(args, ctx, { exists, cappedAncestor: cappedAncestor || undefined, type: 'scaffold' });
+    await (0, effects_1.execute)(effects);
 }
 async function alias(args, target, options = {}) {
-    const { targetDir, name } = await prepareCommand(args, options);
-    const manifest = {
-        name,
-        description: '',
+    const ctx = await getContext(options);
+    const localRoot = ctx.localRoot || ctx.cwd;
+    const agentctlDir = path_1.default.join(localRoot, '.agentctl');
+    const targetDir = path_1.default.join(agentctlDir, args.join(path_1.default.sep));
+    const exists = await fs_extra_1.default.pathExists(targetDir);
+    const cappedAncestor = await getCappedAncestor(targetDir, agentctlDir);
+    const { effects } = ctl_1.Logic.planScaffold(args, ctx, {
+        exists,
+        cappedAncestor: cappedAncestor || undefined,
         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}`);
+        target
+    });
+    await (0, effects_1.execute)(effects);
 }
 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(' ')}`);
+    const ctx = await getContext(options);
+    const localRoot = ctx.localRoot || ctx.cwd;
+    const agentctlDir = path_1.default.join(localRoot, '.agentctl');
+    const targetDir = path_1.default.join(agentctlDir, args.join(path_1.default.sep));
+    const exists = await fs_extra_1.default.pathExists(targetDir);
+    const cappedAncestor = await getCappedAncestor(targetDir, agentctlDir);
+    const { effects } = ctl_1.Logic.planScaffold(args, ctx, {
+        exists,
+        cappedAncestor: cappedAncestor || undefined,
+        type: 'group'
+    });
+    await (0, effects_1.execute)(effects);
 }
 async function pushGlobal(args, options = {}) {
-    const cwd = options.cwd || process.cwd();
-    const localRoot = (0, fs_utils_1.findLocalRoot)(cwd);
-    if (!localRoot)
+    const ctx = await getContext(options);
+    if (!ctx.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`);
-    }
+    const existsInLocal = await fs_extra_1.default.pathExists(path_1.default.join(ctx.localRoot, '.agentctl', cmdPathStr));
+    const existsInGlobal = await fs_extra_1.default.pathExists(path_1.default.join(ctx.globalRoot, cmdPathStr));
+    const effects = ctl_1.Logic.planPushGlobal(args, ctx, {
+        move: options.move,
+        existsInLocal,
+        existsInGlobal
+    });
+    await (0, effects_1.execute)(effects);
 }
 async function pullLocal(args, options = {}) {
-    const cwd = options.cwd || process.cwd();
-    const localRoot = (0, fs_utils_1.findLocalRoot)(cwd);
-    if (!localRoot)
+    const ctx = await getContext(options);
+    if (!ctx.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}`);
+    const existsInGlobal = await fs_extra_1.default.pathExists(path_1.default.join(ctx.globalRoot, cmdPathStr));
+    const existsInLocal = await fs_extra_1.default.pathExists(path_1.default.join(ctx.localRoot, '.agentctl', cmdPathStr));
+    const effects = ctl_1.Logic.planPullLocal(args, ctx, {
+        move: options.move,
+        existsInLocal,
+        existsInGlobal
+    });
+    await (0, effects_1.execute)(effects);
 }
 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(' ')}`);
+    const ctx = await getContext(options);
+    const effects = ctl_1.Logic.planRemove(args, ctx, {
+        resolvedPath: resolved?.manifestPath || null,
+        scope: resolved?.scope || 'unknown',
+        global: options.global
+    });
+    await (0, effects_1.execute)(effects);
 }
 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}`);
+    const ctx = await getContext(options);
+    let rootDir = null;
+    let agentctlDir = null;
+    let destExists = false;
+    let cappedAncestor = null;
+    if (resolved) {
+        rootDir = resolved.scope === 'local'
+            ? (0, fs_utils_1.findLocalRoot)(options.cwd || process.cwd())
+            : (options.globalDir || (0, fs_utils_1.getGlobalRoot)());
+        if (rootDir) {
+            agentctlDir = resolved.scope === 'local' ? path_1.default.join(rootDir, '.agentctl') : rootDir;
+            const destPathStr = destArgs.join(path_1.default.sep);
+            const destDir = path_1.default.join(agentctlDir, destPathStr);
+            destExists = await fs_extra_1.default.pathExists(destDir);
+            const ancestor = await getCappedAncestor(destDir, agentctlDir);
+            if (ancestor)
+                cappedAncestor = { relPath: ancestor.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(' ')}`);
+    const effects = ctl_1.Logic.planMove(srcArgs, destArgs, ctx, {
+        resolvedSrc: resolved ? { manifestPath: resolved.manifestPath, scope: resolved.scope, manifest: resolved.manifest } : null,
+        destExists,
+        cappedAncestor: cappedAncestor || undefined,
+        rootDir,
+        agentctlDir
+    });
+    await (0, effects_1.execute)(effects);
 }
 async function inspect(args, options = {}) {
     const resolved = await (0, resolve_1.resolveCommand)(args, options);
-    if (!resolved) {
+    if (!resolved)
         return null;
-    }
     return {
         manifest: resolved.manifest,
         resolvedPath: resolved.manifestPath,
         scope: resolved.scope
     };
 }
+async function installSkill(agent, options = {}) {
+    const ctx = await getContext(options);
+    const effects = ctl_1.Logic.planInstallSkill(agent, ctx, options);
+    await (0, effects_1.execute)(effects);
+}
+async function install(repoUrl, pathArgs, options = {}) {
+    const ctx = await getContext(options);
+    const installCtx = {
+        repoUrl,
+        pathParts: pathArgs,
+        global: !!options.global,
+        allowCollisions: !!options.allowCollisions,
+        localRoot: ctx.localRoot || ctx.cwd,
+        isNewLocalRoot: !options.global && !ctx.localRoot,
+        globalRoot: ctx.globalRoot,
+        osTmpdir: os_1.default.tmpdir()
+    };
+    // Phase 1: Clone
+    const tempFolderName = `agentctl-install-${Date.now()}-${Math.floor(Math.random() * 10000)}`;
+    const { effects: cloneEffects, tempDir } = (0, install_1.planInstallClone)(installCtx, { tempFolderName });
+    await (0, effects_1.execute)(cloneEffects);
+    // Phase 2: Copy
+    const tempAgentctlDir = path_1.default.join(tempDir, '.agentctl');
+    if (!(await fs_extra_1.default.pathExists(tempAgentctlDir))) {
+        await fs_extra_1.default.remove(tempDir);
+        throw new Error(`Repository does not contain an .agentctl directory at the root.`);
+    }
+    const downloadedItems = await fs_extra_1.default.readdir(tempAgentctlDir);
+    const rootDir = installCtx.global ? installCtx.globalRoot : installCtx.localRoot;
+    const agentctlDir = installCtx.global ? rootDir : path_1.default.join(rootDir, '.agentctl');
+    const targetDir = path_1.default.join(agentctlDir, ...installCtx.pathParts);
+    const existingItems = (await fs_extra_1.default.pathExists(targetDir)) ? await fs_extra_1.default.readdir(targetDir) : [];
+    const { effects: copyEffects } = (0, install_1.planInstallCopy)(installCtx, {
+        tempAgentctlDir,
+        existingItems,
+        downloadedItems
+    });
+    await (0, effects_1.execute)(copyEffects);
+}
 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 ctx = await getContext(options);
     const commands = new Map();
     async function walk(dir, prefix, scope) {
         if (!await fs_extra_1.default.pathExists(dir))
@@ -228,89 +230,34 @@ async function list(options = {}) {
             const cmdPath = cmdPathParts.join(' ');
             let manifest = null;
             const mPath = path_1.default.join(filePath, 'manifest.json');
-            if (await fs_extra_1.default.pathExists(mPath)) {
+            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)) {
+                if ((0, manifest_1.isCappedManifest)(manifest))
                     type = manifest.type || 'scaffold';
-                }
-                else if (manifest.type) {
+                else if (manifest.type)
                     type = manifest.type;
-                }
             }
-            const item = {
-                path: cmdPath,
-                type,
-                scope,
-                description: manifest?.description || ''
-            };
             if (!commands.has(cmdPath)) {
-                commands.set(cmdPath, item);
+                if (manifest) {
+                    const item = { path: cmdPath, type, scope, description: manifest.description || '' };
+                    commands.set(cmdPath, item);
+                }
                 const effectiveManifest = manifest || { name: file, type: 'group' };
-                if (!(0, manifest_1.isCappedManifest)(effectiveManifest)) {
+                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 (existing && existing.scope === 'local' && 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');
+    if (ctx.localRoot)
+        await walk(path_1.default.join(ctx.localRoot, '.agentctl'), [], 'local');
+    await walk(ctx.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) === '';
-}