@michaelhartmayer/agentctl 1.2.1 → 1.2.2

package/dist/ctl.js

@@ -42,6 +42,18 @@ async function getCappedAncestor(dir, baseDir) {
     }
     return null;
 }
+async function getMissingAncestorGroups(args, agentctlDir) {
+    const missing = [];
+    for (let i = 1; i < args.length; i++) {
+        const segments = args.slice(0, i);
+        const dir = path_1.default.join(agentctlDir, ...segments);
+        const manifestPath = path_1.default.join(dir, 'manifest.json');
+        if (!(await fs_extra_1.default.pathExists(manifestPath))) {
+            missing.push({ dir, name: segments[segments.length - 1] });
+        }
+    }
+    return missing;
+}
 async function getContext(options) {
     const cwd = options.cwd || process.cwd();
     return {
@@ -54,56 +66,50 @@ async function getContext(options) {
 }
 async function scaffold(args, options = {}) {
     const ctx = await getContext(options);
-    const isGlobal = !!options.global;
-    const rootDir = isGlobal ? ctx.globalRoot : ctx.cwd;
-    const agentctlDir = isGlobal ? rootDir : path_1.default.join(rootDir, '.agentctl');
+    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 = isGlobal ? null : await getCappedAncestor(targetDir, agentctlDir);
-    const isNewLocalRoot = !isGlobal && !(await fs_extra_1.default.pathExists(agentctlDir));
+    const cappedAncestor = await getCappedAncestor(targetDir, agentctlDir);
+    const missingAncestorGroups = await getMissingAncestorGroups(args, agentctlDir);
     const { effects } = ctl_1.Logic.planScaffold(args, ctx, {
         exists,
         cappedAncestor: cappedAncestor || undefined,
         type: 'scaffold',
-        scope: isGlobal ? 'global' : 'local',
-        isNewLocalRoot
+        missingAncestorGroups
     });
     await (0, effects_1.execute)(effects);
 }
 async function alias(args, target, options = {}) {
     const ctx = await getContext(options);
-    const isGlobal = !!options.global;
-    const rootDir = isGlobal ? ctx.globalRoot : ctx.cwd;
-    const agentctlDir = isGlobal ? rootDir : path_1.default.join(rootDir, '.agentctl');
+    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 = isGlobal ? null : await getCappedAncestor(targetDir, agentctlDir);
-    const isNewLocalRoot = !isGlobal && !(await fs_extra_1.default.pathExists(agentctlDir));
+    const cappedAncestor = await getCappedAncestor(targetDir, agentctlDir);
+    const missingAncestorGroups = await getMissingAncestorGroups(args, agentctlDir);
     const { effects } = ctl_1.Logic.planScaffold(args, ctx, {
         exists,
         cappedAncestor: cappedAncestor || undefined,
         type: 'alias',
         target,
-        scope: isGlobal ? 'global' : 'local',
-        isNewLocalRoot
+        missingAncestorGroups
     });
     await (0, effects_1.execute)(effects);
 }
 async function group(args, options = {}) {
     const ctx = await getContext(options);
-    const isGlobal = !!options.global;
-    const rootDir = isGlobal ? ctx.globalRoot : ctx.cwd;
-    const agentctlDir = isGlobal ? rootDir : path_1.default.join(rootDir, '.agentctl');
+    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 = isGlobal ? null : await getCappedAncestor(targetDir, agentctlDir);
-    const isNewLocalRoot = !isGlobal && !(await fs_extra_1.default.pathExists(agentctlDir));
+    const cappedAncestor = await getCappedAncestor(targetDir, agentctlDir);
+    const missingAncestorGroups = await getMissingAncestorGroups(args, agentctlDir);
     const { effects } = ctl_1.Logic.planScaffold(args, ctx, {
         exists,
         cappedAncestor: cappedAncestor || undefined,
         type: 'group',
-        scope: isGlobal ? 'global' : 'local',
-        isNewLocalRoot
+        missingAncestorGroups
     });
     await (0, effects_1.execute)(effects);
 }
@@ -192,14 +198,13 @@ async function installSkill(agent, options = {}) {
 }
 async function install(repoUrl, pathArgs, options = {}) {
     const ctx = await getContext(options);
-    const isNewLocalRoot = !options.global && !(await fs_extra_1.default.pathExists(path_1.default.join(ctx.cwd, '.agentctl')));
     const installCtx = {
         repoUrl,
         pathParts: pathArgs,
         global: !!options.global,
         allowCollisions: !!options.allowCollisions,
-        localRoot: options.global ? ctx.globalRoot : ctx.cwd,
-        isNewLocalRoot,
+        localRoot: ctx.localRoot || ctx.cwd,
+        isNewLocalRoot: !options.global && !ctx.localRoot,
         globalRoot: ctx.globalRoot,
         osTmpdir: os_1.default.tmpdir()
     };

package/dist/effects.js

@@ -46,7 +46,9 @@ async function execute(effects) {
                 break;
             }
             case 'spawn': {
-                const child = (0, child_process_1.spawn)(effect.command, effect.options);
+                const child = effect.args
+                    ? (0, child_process_1.spawn)(effect.command, effect.args, effect.options)
+                    : (0, child_process_1.spawn)(effect.command, effect.options);
                 if (effect.onExit) {
                     child.on('exit', effect.onExit);
                 }

package/dist/index.js

@@ -28,33 +28,33 @@ const ctl = program.command('ctl')
     .action((opts, command) => {
     command.help();
 })
-    .addHelpText('after', `
-${chalk_1.default.bold('Agentctl Paradigm:')}
-  Agentctl acts as a unified control plane allowing both Humans and AI Agents
-  to create, discover, and execute local shell commands. By running \`agentctl ctl scaffold <name>\`
-  you create a directory in the \`.agentctl\` folder containing a \`manifest.json\` 
-  and a run script. This dynamically creates a new \`agentctl <name>\` command that
-  is easily callable by agents and globally executable on your machine.
-
-Commands:
-
-  ${chalk_1.default.bold('Creation')}
-    scaffold [path...]                          create a new command
-    alias [args...]                             create a shell alias
-    group [path...]                             create a namespace group
-
-  ${chalk_1.default.bold('Organize & Scope')}
-    rm [options] [path...]                      delete a command
-    mv [options] [src] [dest]                   rename/move a command
-    global [options] [path...]                  make a command global
-    local [options] [path...]                   make a command local
-
-  ${chalk_1.default.bold('Information')}
-    list                                        list all commands
-    inspect [path...]                           inspect command details
-
-  ${chalk_1.default.bold('Integration')}
-    install [options] [repoUrl] [pathParts...]  install remote command group
+    .addHelpText('after', `
+${chalk_1.default.bold('Agentctl Paradigm:')}
+  Agentctl acts as a unified control plane allowing both Humans and AI Agents
+  to create, discover, and execute local shell commands. By running \`agentctl ctl scaffold <name>\`
+  you create a directory in the \`.agentctl\` folder containing a \`manifest.json\` 
+  and a run script. This dynamically creates a new \`agentctl <name>\` command that
+  is easily callable by agents and globally executable on your machine.
+
+Commands:
+
+  ${chalk_1.default.bold('Creation')}
+    scaffold [path...]                          create a new command
+    alias [args...]                             create a shell alias
+    group [path...]                             create a namespace group
+
+  ${chalk_1.default.bold('Organize & Scope')}
+    rm [options] [path...]                      delete a command
+    mv [options] [src] [dest]                   rename/move a command
+    global [options] [path...]                  make a command global
+    local [options] [path...]                   make a command local
+
+  ${chalk_1.default.bold('Information')}
+    list                                        list all commands
+    inspect [path...]                           inspect command details
+
+  ${chalk_1.default.bold('Integration')}
+    install [options] [repoUrl] [pathParts...]  install remote command group
 `);
 const withErrorHandling = (fn) => {
     return async (...args) => {
@@ -76,31 +76,30 @@ const normalizePath = (parts) => parts.flatMap(p => p.split(/[\s/\\:]+/).filter(
 ctl.command('scaffold')
     .description('Scaffold a new command directory with a manifest and starter script.')
     .argument('[path...]', 'Hierarchical path for the new command (e.g., "dev start" or "utils/cleanup")')
-    .option('-g, --global', 'Create command in global scope')
     .summary('create a new command')
-    .addHelpText('after', `
-Additional Info:
-  This command creates a folder in your local .agentctl directory.
-  Inside this newly created folder, it generates:
-    - manifest.json: Metadata config to edit for your command.
-    - command.sh/cmd: A starter script to edit for your actual logic.
-    
-  Manifest Schema (manifest.json) to edit:
-  {
-    "name": "<command_folder_name>",
-    "description": "<insert command summary here>",
-    "help": "<insert longer usage/help instructions here>",
-    "type": "scaffold", // do not change!
-    "run": "./command.cmd" // points to the script to execute
-  }
-  
-  Note: 
-  - The "description" is displayed when you view this command in a list.
-  - Commands must provide their own help implementation (e.g. by handling --help inside your script).
-
-Examples:
-  $ agentctl ctl scaffold build:front
-  $ agentctl ctl scaffold "build front" # Creates group 'build' and subcommand 'front'
+    .addHelpText('after', `
+Additional Info:
+  This command creates a folder in your local .agentctl directory.
+  Inside this newly created folder, it generates:
+    - manifest.json: Metadata config to edit for your command.
+    - command.sh/cmd: A starter script to edit for your actual logic.
+    
+  Manifest Schema (manifest.json) to edit:
+  {
+    "name": "<command_folder_name>",
+    "description": "<insert command summary here>",
+    "help": "<insert longer usage/help instructions here>",
+    "type": "scaffold", // do not change!
+    "run": "./command.cmd" // points to the script to execute
+  }
+  
+  Note: 
+  - The "description" is displayed when you view this command in a list.
+  - Commands must provide their own help implementation (e.g. by handling --help inside your script).
+
+Examples:
+  $ agentctl ctl scaffold build:front
+  $ agentctl ctl scaffold "build front" # Creates group 'build' and subcommand 'front'
 `)
     .action(withErrorHandling(async (pathParts, opts, command) => {
     const normalized = normalizePath(pathParts);
@@ -108,17 +107,16 @@ Examples:
         command.help();
         return;
     }
-    await (0, ctl_1.scaffold)(normalized, { global: opts.global });
+    await (0, ctl_1.scaffold)(normalized);
 }));
 ctl.command('alias')
     .description('Create a command that executes a raw shell string.')
     .argument('[args...]', 'Hierarchical path segments followed by the shell command target')
-    .option('-g, --global', 'Create alias in global scope')
     .summary('create a shell alias')
-    .addHelpText('after', `
-Examples:
-  $ agentctl ctl alias dev logs "docker compose logs -f"
-  $ agentctl ctl alias list-files "ls -la"
+    .addHelpText('after', `
+Examples:
+  $ agentctl ctl alias dev logs "docker compose logs -f"
+  $ agentctl ctl alias list-files "ls -la"
 `)
     .action(withErrorHandling(async (args, opts, command) => {
     if (!args || args.length < 2) {
@@ -131,36 +129,35 @@ Examples:
         command.help();
         return;
     }
-    await (0, ctl_1.alias)(name, target, { global: opts.global });
+    await (0, ctl_1.alias)(name, target);
 }));
 ctl.command('group')
     .description('Create a command group (namespace) to organize subcommands.')
     .argument('[path...]', 'Hierarchical path for the group (e.g., "dev" or "cloud/aws")')
-    .option('-g, --global', 'Create group in global scope')
     .summary('create a namespace group')
-    .addHelpText('after', `
-Additional Info:
-  Groups allow you to categorize commands. Running a group command without
-  subcommands will list all direct subcommands within that group.
-  
-  This command creates a folder in your local .agentctl directory.
-  Inside this newly created folder, it generates a manifest.json.
-  
-  Group Schema (manifest.json) to edit:
-  {
-    "name": "<group_folder_name>",
-    "description": "<insert group summary here>",
-    "help": "<insert longer group description/instructions here>",
-    "type": "group" // do not change!
-  }
-  
-  Note: 
-  - The "description" is displayed when you view this group in a list.
-  - The "help" is displayed when you call this group without a subcommand.
-
-Examples:
-  $ agentctl ctl group dev
-  $ agentctl ctl group "data pipelines" # Creates group 'data' and subgroup 'pipelines'
+    .addHelpText('after', `
+Additional Info:
+  Groups allow you to categorize commands. Running a group command without
+  subcommands will list all direct subcommands within that group.
+  
+  This command creates a folder in your local .agentctl directory.
+  Inside this newly created folder, it generates a manifest.json.
+  
+  Group Schema (manifest.json) to edit:
+  {
+    "name": "<group_folder_name>",
+    "description": "<insert group summary here>",
+    "help": "<insert longer group description/instructions here>",
+    "type": "group" // do not change!
+  }
+  
+  Note: 
+  - The "description" is displayed when you view this group in a list.
+  - The "help" is displayed when you call this group without a subcommand.
+
+Examples:
+  $ agentctl ctl group dev
+  $ agentctl ctl group "data pipelines" # Creates group 'data' and subgroup 'pipelines'
 `)
     .action(withErrorHandling(async (parts, opts, command) => {
     const normalized = normalizePath(parts);
@@ -168,17 +165,17 @@ Examples:
         command.help();
         return;
     }
-    await (0, ctl_1.group)(normalized, { global: opts.global });
+    await (0, ctl_1.group)(normalized);
 }));
 ctl.command('rm')
     .description('Permanently remove a command or group.')
     .argument('[path...]', 'Command path to remove')
     .option('-g, --global', 'Remove from global scope instead of local')
     .summary('delete a command')
-    .addHelpText('after', `
-Examples:
-        $ agentctl ctl rm dev start
-  $ agentctl ctl rm utils--global
+    .addHelpText('after', `
+Examples:
+        $ agentctl ctl rm dev start
+  $ agentctl ctl rm utils--global
         `)
     .action(withErrorHandling(async (parts, opts, command) => {
     const normalized = normalizePath(parts);
@@ -194,10 +191,10 @@ ctl.command('mv')
     .argument('[dest]', 'New path (space-separated or quoted)')
     .option('-g, --global', 'Operate in global scope')
     .summary('rename/move a command')
-    .addHelpText('after', `
-Examples:
-        $ agentctl ctl mv "dev start" "dev begin"
-  $ agentctl ctl mv utils scripts--global
+    .addHelpText('after', `
+Examples:
+        $ agentctl ctl mv "dev start" "dev begin"
+  $ agentctl ctl mv utils scripts--global
         `)
     .action(withErrorHandling(async (src, dest, opts, command) => {
     const normalizedSrc = normalizePath(src ? [src] : []);
@@ -211,12 +208,12 @@ Examples:
 ctl.command('list')
     .description('List all available commands across local and global scopes.')
     .summary('list all commands')
-    .addHelpText('after', `
-Output Columns:
-        TYPE - scaffold, alias, or group
-  SCOPE - local(project - specific) or global(user - wide)
-  COMMAND - The path used to invoke the command
-  DESCRIPTION - Brief text from the command's manifest
+    .addHelpText('after', `
+Output Columns:
+        TYPE - scaffold, alias, or group
+  SCOPE - local(project - specific) or global(user - wide)
+  COMMAND - The path used to invoke the command
+  DESCRIPTION - Brief text from the command's manifest
         `)
     .action(withErrorHandling(async () => {
     const items = await (0, ctl_1.list)();
@@ -231,9 +228,9 @@ ctl.command('inspect')
     .description('Show the internal manifest and file system path of a command.')
     .argument('[path...]', 'Command path to inspect')
     .summary('inspect command details')
-    .addHelpText('after', `
-Examples:
-        $ agentctl ctl inspect dev start
+    .addHelpText('after', `
+Examples:
+        $ agentctl ctl inspect dev start
         `)
     .action(withErrorHandling(async (parts, opts, command) => {
     const normalized = normalizePath(parts);
@@ -256,13 +253,13 @@ ctl.command('global')
     .option('-m, --move', 'Move the command (delete local after copying)')
     .option('-c, --copy', 'Copy the command (keep local version, default)')
     .summary('make a command global')
-    .addHelpText('after', `
-Additional Info:
-        Global commands are stored in your home directory and are available in any project.
-
-        Examples:
-        $ agentctl ctl global utils / cleanup
-  $ agentctl ctl global dev / deploy--move
+    .addHelpText('after', `
+Additional Info:
+        Global commands are stored in your home directory and are available in any project.
+
+        Examples:
+        $ agentctl ctl global utils / cleanup
+  $ agentctl ctl global dev / deploy--move
         `)
     .action(withErrorHandling(async (parts, opts, command) => {
     const normalized = normalizePath(parts);
@@ -278,10 +275,10 @@ ctl.command('local')
     .option('-m, --move', 'Move the command (delete global after pulling)')
     .option('-c, --copy', 'Copy the command (keep global version, default)')
     .summary('make a command local')
-    .addHelpText('after', `
-Examples:
-        $ agentctl ctl local utils / shared
-  $ agentctl ctl local snippets / js--move
+    .addHelpText('after', `
+Examples:
+        $ agentctl ctl local utils / shared
+  $ agentctl ctl local snippets / js--move
         `)
     .action(withErrorHandling(async (parts, opts, command) => {
     const normalized = normalizePath(parts);
@@ -298,14 +295,14 @@ ctl.command('install')
     .option('-g, --global', 'Install globally instead of locally')
     .option('--allow-collisions', 'Allow overwriting existing commands or merging into groups')
     .summary('install remote command group')
-    .addHelpText('after', `
-Additional Info:
-        Fetches the.agentctl folder from the remote repository and installs it into
-  your local or global agentctl environment.
-
-        Examples:
-        $ agentctl ctl install https://github.com/org/repo-tools
-        $ agentctl ctl install https://github.com/org/deploy-scripts deploy --global
+    .addHelpText('after', `
+Additional Info:
+        Fetches the.agentctl folder from the remote repository and installs it into
+  your local or global agentctl environment.
+
+        Examples:
+        $ agentctl ctl install https://github.com/org/repo-tools
+        $ agentctl ctl install https://github.com/org/deploy-scripts deploy --global
         `)
     .action(withErrorHandling(async (repoUrl, pathParts, opts, command) => {
     if (!repoUrl) {

package/dist/logic/ctl.js

@@ -21,15 +21,21 @@ exports.Logic = {
         if (options.cappedAncestor) {
             throw new Error(`Cannot nest command under capped command: ${options.cappedAncestor.relPath}`);
         }
-        const isGlobal = options.scope === 'global';
-        const rootDir = isGlobal ? ctx.globalRoot : ctx.cwd;
-        const agentctlDir = isGlobal ? rootDir : path_1.default.join(rootDir, '.agentctl');
+        const localRoot = ctx.localRoot || ctx.cwd;
+        const agentctlDir = path_1.default.join(localRoot, '.agentctl');
         const cmdPath = args.join(path_1.default.sep);
         const targetDir = path_1.default.join(agentctlDir, cmdPath);
         const name = args[args.length - 1];
         const type = options.type || 'scaffold';
         const isWin = ctx.platform === 'win32';
         const effects = [{ type: 'mkdir', path: targetDir }];
+        for (const group of options.missingAncestorGroups || []) {
+            effects.push({
+                type: 'writeJson',
+                path: path_1.default.join(group.dir, 'manifest.json'),
+                content: { name: group.name, type: 'group' }
+            });
+        }
         const manifest = {
             name,
             description: '<insert summary>',
@@ -54,9 +60,6 @@ exports.Logic = {
         const logMsg = type === 'scaffold' ? `Scaffolded command: ${args.join(' ')}` :
             type === 'alias' ? `Aliased command: ${args.join(' ')} -> ${options.target}` :
                 `Created group: ${args.join(' ')}`;
-        if (options.isNewLocalRoot) {
-            effects.unshift({ type: 'log', message: `Initialized new .agentctl folder in ${rootDir}` });
-        }
         effects.push({ type: 'log', message: logMsg });
         return { effects };
     },

package/dist/logic/index.js

@@ -27,13 +27,17 @@ exports.AppLogic = {
                 runCmd = path_1.default.resolve(cmdDir, runCmd);
             }
             runCmd = runCmd.replace(/{{DIR}}/g, cmdDir);
-            const fullCommand = `${runCmd} ${remainingArgs.join(' ')}`;
+            const quoteArg = (arg) => /[\s"'\\$`]/.test(arg) ? JSON.stringify(arg) : arg;
+            const displayedArgs = remainingArgs.map(quoteArg).join(' ');
+            const fullCommand = displayedArgs ? `${runCmd} ${displayedArgs}` : runCmd;
+            const isAlias = manifest.type === 'alias';
             effects.push({ type: 'log', message: `[${scope}] Running: ${fullCommand}` }, {
                 type: 'spawn',
-                command: fullCommand,
+                command: isAlias ? fullCommand : runCmd,
+                args: isAlias ? undefined : remainingArgs,
                 options: {
                     cwd: process.cwd(),
-                    shell: true,
+                    shell: isAlias,
                     stdio: 'inherit',
                     env: { ...process.env, AGENTCTL_SCOPE: scope }
                 },

package/package.json

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