@michaelhartmayer/agentctl 1.0.0

package/tests/group.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import path from 'path';
+import fs from 'fs-extra';
+import { createTestDir, cleanupTestDir } from './helpers';
+import { group, scaffold } from '../src/ctl';
+
+describe('ctl group', () => {
+    let cwd: string;
+
+    beforeEach(async () => {
+        cwd = await createTestDir();
+    });
+
+    afterEach(async () => {
+        await cleanupTestDir(cwd);
+    });
+
+    it('creates an uncapped command (group) with minimal manifest', async () => {
+        await group(['dev'], { cwd });
+
+        const groupDir = path.join(cwd, '.agentctl', 'dev');
+        expect(await fs.pathExists(groupDir)).toBe(true);
+
+        const manifestPath = path.join(groupDir, 'manifest.json');
+        expect(await fs.pathExists(manifestPath)).toBe(true);
+        const manifest = await fs.readJson(manifestPath);
+
+        expect(manifest).toEqual(expect.objectContaining({
+            name: 'dev',
+            type: 'group',
+        }));
+        expect(manifest.run).toBeUndefined();
+    });
+
+    it('fails if path exists as capped command', async () => {
+        // Create capped command 'dev'
+        await scaffold(['dev'], { cwd });
+
+        await expect(group(['dev'], { cwd }))
+            .rejects.toThrow(/already exists/);
+    });
+
+    it('fails if path exists as directory (group)', async () => {
+        await group(['dev'], { cwd });
+        await expect(group(['dev'], { cwd }))
+            .rejects.toThrow(/already exists/);
+    });
+});

package/tests/helpers.ts

@@ -0,0 +1,16 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+
+const BASE_TEST_DIR = path.join(os.tmpdir(), 'agentctl-tests');
+
+export async function createTestDir() {
+    const dir = path.join(BASE_TEST_DIR, crypto.randomUUID());
+    await fs.ensureDir(dir);
+    return dir;
+}
+
+export async function cleanupTestDir(dir: string) {
+    await fs.remove(dir);
+}

package/tests/introspection.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import path from 'path';
+import fs from 'fs-extra';
+import { createTestDir, cleanupTestDir } from './helpers';
+import { list, inspect } from '../src/ctl';
+import { scaffold } from '../src/ctl';
+
+describe('ctl introspection', () => {
+    let localRoot: string;
+    let globalRoot: string;
+    let baseDir: string;
+
+    beforeEach(async () => {
+        baseDir = await createTestDir();
+        localRoot = path.join(baseDir, 'local');
+        globalRoot = path.join(baseDir, 'global');
+        await fs.ensureDir(localRoot);
+        await fs.ensureDir(globalRoot);
+    });
+
+    afterEach(async () => {
+        await cleanupTestDir(baseDir);
+    });
+
+    it('list commands recursively from both scopes', async () => {
+        // Local: dev start (scaffold), tools (group)
+        await scaffold(['dev', 'start'], { cwd: localRoot });
+        await fs.ensureDir(path.join(localRoot, '.agentctl', 'tools')); // implicit group
+
+        // Global: gh (alias), tools lint (alias)
+        const ghDir = path.join(globalRoot, 'gh');
+        await fs.ensureDir(ghDir);
+        await fs.writeJson(path.join(ghDir, 'manifest.json'), { name: 'gh', type: 'alias', run: 'gh' });
+
+        const toolsLintDir = path.join(globalRoot, 'tools', 'lint');
+        await fs.ensureDir(toolsLintDir);
+        await fs.writeJson(path.join(toolsLintDir, 'manifest.json'), { name: 'lint', type: 'alias', run: 'lint' });
+
+        const results = await list({ cwd: localRoot, globalDir: globalRoot });
+
+        const paths = results.map(r => r.path).sort();
+        expect(paths).toContain('dev');
+        expect(paths).toContain('dev start');
+        expect(paths).toContain('gh');
+        expect(paths).toContain('tools');
+        expect(paths).toContain('tools lint');
+
+        const dev = results.find(r => r.path === 'dev');
+        expect(dev.scope).toBe('local');
+        expect(dev.type).toBe('group');
+
+        const gh = results.find(r => r.path === 'gh');
+        expect(gh.scope).toBe('global');
+        expect(gh.type).toBe('alias');
+
+        // Ensure tools is merged/handled
+        const tools = results.find(r => r.path === 'tools');
+        // It resides in both (implicitly in global as parent of lint, explicitly in local).
+        // Local wins metadata. It's a group.
+        expect(tools.type).toBe('group');
+    });
+
+    it('inspect shows command details', async () => {
+        await scaffold(['deploy'], { cwd: localRoot });
+
+        const details = await inspect(['deploy'], { cwd: localRoot, globalDir: globalRoot });
+        expect(details).not.toBeNull();
+        expect(details.manifest.name).toBe('deploy');
+        expect(details.resolvedPath).toContain(path.join(localRoot, '.agentctl', 'deploy'));
+    });
+});

package/tests/lifecycle-guards.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs-extra';
+import path from 'path';
+import { createTestDir, cleanupTestDir } from './helpers';
+import { mv, scaffold } from '../src/ctl';
+
+describe('lifecycle nesting guards', () => {
+    let testDir: string;
+    let agentctlDir: string;
+
+    beforeEach(async () => {
+        testDir = await createTestDir();
+        agentctlDir = path.join(testDir, '.agentctl');
+        await fs.ensureDir(agentctlDir);
+    });
+
+    afterEach(async () => {
+        await cleanupTestDir(testDir);
+    });
+
+    it('mv throws when trying to nest under a capped command', async () => {
+        // Create a capped command 'calc'
+        await scaffold(['calc'], { cwd: testDir });
+
+        // Create another command 'git'
+        await scaffold(['git'], { cwd: testDir });
+
+        // Try to move 'git' to 'calc sub'
+        // This should fail because 'calc' is capped (has run script)
+        await expect(
+            mv(['git'], ['calc', 'sub'], { cwd: testDir })
+        ).rejects.toThrow('Cannot nest command under capped command');
+    });
+
+    it('scaffold throws when trying to nest under a capped command', async () => {
+        // Create a capped command 'calc'
+        await scaffold(['calc'], { cwd: testDir });
+
+        // Try to scaffold 'calc sub'
+        await expect(
+            scaffold(['calc', 'sub'], { cwd: testDir })
+        ).rejects.toThrow('Cannot nest command under capped command');
+    });
+});

package/tests/lifecycle.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import path from 'path';
+import fs from 'fs-extra';
+import { createTestDir, cleanupTestDir } from './helpers';
+import { rm, mv, scaffold } from '../src/ctl';
+
+describe('ctl lifecycle (rm, mv)', () => {
+    let cwd: string;
+    beforeEach(async () => {
+        cwd = await createTestDir();
+    });
+    afterEach(async () => {
+        await cleanupTestDir(cwd);
+    });
+
+    it('rm: removes command logic', async () => {
+        await scaffold(['deploy'], { cwd });
+        const cmdDir = path.join(cwd, '.agentctl', 'deploy');
+        expect(await fs.pathExists(cmdDir)).toBe(true);
+
+        await rm(['deploy'], { cwd });
+        expect(await fs.pathExists(cmdDir)).toBe(false);
+    });
+
+    it('rm: removes group', async () => {
+        await scaffold(['dev', 'start'], { cwd });
+        const devDir = path.join(cwd, '.agentctl', 'dev');
+        expect(await fs.pathExists(devDir)).toBe(true);
+        expect(await fs.pathExists(path.join(devDir, 'start'))).toBe(true);
+
+        await rm(['dev'], { cwd });
+        expect(await fs.pathExists(devDir)).toBe(false);
+    });
+
+    it('mv: moves command and updates name', async () => {
+        await scaffold(['deploy'], { cwd });
+        const oldDir = path.join(cwd, '.agentctl', 'deploy');
+        const manifestPath = path.join(oldDir, 'manifest.json');
+        expect((await fs.readJson(manifestPath)).name).toBe('deploy');
+
+        // Move deploy -> release
+        await mv(['deploy'], ['release'], { cwd });
+
+        const newDir = path.join(cwd, '.agentctl', 'release');
+        expect(await fs.pathExists(oldDir)).toBe(false);
+        expect(await fs.pathExists(newDir)).toBe(true);
+
+        const newManifest = await fs.readJson(path.join(newDir, 'manifest.json'));
+        expect(newManifest.name).toBe('release');
+    });
+
+    it('mv: fails if destination exists', async () => {
+        await scaffold(['deploy'], { cwd });
+        await scaffold(['release'], { cwd });
+
+        await expect(mv(['deploy'], ['release'], { cwd }))
+            .rejects.toThrow(/already exists/);
+    });
+});

package/tests/manifest.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { isCappedManifest, Manifest } from '../src/manifest';
+
+describe('isCappedManifest', () => {
+    it('returns true when manifest has a run command', () => {
+        const m: Manifest = { name: 'test', run: './script.sh' };
+        expect(isCappedManifest(m)).toBe(true);
+    });
+
+    it('returns true when manifest type is scaffold', () => {
+        const m: Manifest = { name: 'test', type: 'scaffold' };
+        expect(isCappedManifest(m)).toBe(true);
+    });
+
+    it('returns true when manifest type is alias', () => {
+        const m: Manifest = { name: 'test', type: 'alias' };
+        expect(isCappedManifest(m)).toBe(true);
+    });
+
+    it('returns false when manifest is a plain group', () => {
+        const m: Manifest = { name: 'test', type: 'group' };
+        expect(isCappedManifest(m)).toBe(false);
+    });
+
+    it('returns false when manifest has no type and no run', () => {
+        const m: Manifest = { name: 'test' };
+        expect(isCappedManifest(m)).toBe(false);
+    });
+});

package/tests/resolve-priority.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs-extra';
+import path from 'path';
+import { createTestDir, cleanupTestDir } from './helpers';
+import { resolveCommand } from '../src/resolve';
+
+describe('resolve scope priority', () => {
+    let testDir: string;
+    let globalDir: string;
+
+    beforeEach(async () => {
+        testDir = await createTestDir();
+        globalDir = await createTestDir();
+        await fs.ensureDir(path.join(testDir, '.agentctl'));
+    });
+
+    afterEach(async () => {
+        await cleanupTestDir(testDir);
+        await cleanupTestDir(globalDir);
+    });
+
+    it('local group shadows global group at the same path', async () => {
+        // Create a group in both local and global with the same name
+        const localCmd = path.join(testDir, '.agentctl', 'tools');
+        await fs.ensureDir(localCmd);
+        await fs.writeJson(path.join(localCmd, 'manifest.json'), {
+            name: 'tools', type: 'group', description: 'local tools'
+        });
+
+        const globalCmd = path.join(globalDir, 'tools');
+        await fs.ensureDir(globalCmd);
+        await fs.writeJson(path.join(globalCmd, 'manifest.json'), {
+            name: 'tools', type: 'group', description: 'global tools'
+        });
+
+        const result = await resolveCommand(['tools'], { cwd: testDir, globalDir });
+        expect(result).not.toBeNull();
+        expect(result!.scope).toBe('local');
+        expect(result!.manifest.description).toBe('local tools');
+    });
+
+    it('local capped command shadows global capped command', async () => {
+        const localCmd = path.join(testDir, '.agentctl', 'deploy');
+        await fs.ensureDir(localCmd);
+        await fs.writeJson(path.join(localCmd, 'manifest.json'), {
+            name: 'deploy', type: 'scaffold', run: './local-deploy.sh'
+        });
+
+        const globalCmd = path.join(globalDir, 'deploy');
+        await fs.ensureDir(globalCmd);
+        await fs.writeJson(path.join(globalCmd, 'manifest.json'), {
+            name: 'deploy', type: 'scaffold', run: './global-deploy.sh'
+        });
+
+        const result = await resolveCommand(['deploy'], { cwd: testDir, globalDir });
+        expect(result).not.toBeNull();
+        expect(result!.scope).toBe('local');
+        expect(result!.manifest.run).toBe('./local-deploy.sh');
+    });
+
+    it('global command resolves when no local exists', async () => {
+        const globalCmd = path.join(globalDir, 'deploy');
+        await fs.ensureDir(globalCmd);
+        await fs.writeJson(path.join(globalCmd, 'manifest.json'), {
+            name: 'deploy', type: 'scaffold', run: './deploy.sh'
+        });
+
+        const result = await resolveCommand(['deploy'], { cwd: testDir, globalDir });
+        expect(result).not.toBeNull();
+        expect(result!.scope).toBe('global');
+    });
+});

package/tests/resolve.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import path from 'path';
+import fs from 'fs-extra';
+import { createTestDir, cleanupTestDir } from './helpers';
+import { resolveCommand } from '../src/resolve';
+import { scaffold } from '../src/ctl';
+
+describe('resolveCommand', () => {
+    let localRoot: string;
+    let globalRoot: string;
+    let baseDir: string;
+
+    beforeEach(async () => {
+        baseDir = await createTestDir();
+        localRoot = path.join(baseDir, 'local');
+        globalRoot = path.join(baseDir, 'global');
+        await fs.ensureDir(localRoot);
+        await fs.ensureDir(globalRoot);
+    });
+
+    afterEach(async () => {
+        await cleanupTestDir(baseDir);
+    });
+
+    it('resolves local command', async () => {
+        // Create local command 'deploy' in localRoot/.agentctl/deploy
+        await scaffold(['deploy'], { cwd: localRoot });
+
+        const result = await resolveCommand(['deploy'], { cwd: localRoot, globalDir: globalRoot });
+        expect(result).not.toBeNull();
+        expect(result!.manifest.name).toBe('deploy');
+        expect(result!.scope).toBe('local');
+        expect(result!.args).toEqual([]);
+    });
+
+    it('resolves global command', async () => {
+        // Create global alias 'gh' in globalRoot/gh
+        const cmdDir = path.join(globalRoot, 'gh');
+        await fs.ensureDir(cmdDir);
+        await fs.writeJson(path.join(cmdDir, 'manifest.json'), { name: 'gh', type: 'alias', run: 'gh' });
+
+        const result = await resolveCommand(['gh'], { cwd: localRoot, globalDir: globalRoot });
+        expect(result).not.toBeNull();
+        expect(result!.manifest.name).toBe('gh');
+        expect(result!.scope).toBe('global');
+    });
+
+    it('prioritizes local over global', async () => {
+        // Local 'deploy' (manifest type scaffold)
+        await scaffold(['deploy'], { cwd: localRoot });
+
+        // Global 'deploy' (manifest type alias)
+        const cmdDir = path.join(globalRoot, 'deploy');
+        await fs.ensureDir(cmdDir);
+        await fs.writeJson(path.join(cmdDir, 'manifest.json'), { name: 'deploy', type: 'alias', run: 'echo global' });
+
+        const result = await resolveCommand(['deploy'], { cwd: localRoot, globalDir: globalRoot });
+        expect(result).not.toBeNull();
+        expect(result!.scope).toBe('local');
+        // Ensure we got the scaffold manifest (which has type 'scaffold')
+        expect(result!.manifest.type).toBe('scaffold');
+    });
+
+    it('returns null if not found', async () => {
+        const result = await resolveCommand(['missing'], { cwd: localRoot, globalDir: globalRoot });
+        expect(result).toBeNull();
+    });
+
+    it('handles nested properties', async () => {
+        // Local group 'dev', command 'start'
+        await scaffold(['dev', 'start'], { cwd: localRoot });
+
+        const result = await resolveCommand(['dev', 'start'], { cwd: localRoot, globalDir: globalRoot });
+        expect(result).not.toBeNull();
+        expect(result!.manifest.name).toBe('start');
+        expect(result!.cmdPath).toBe('dev start'); // Should construct cmdPath?
+    });
+});

package/tests/scaffold.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import path from 'path';
+import fs from 'fs-extra';
+import { createTestDir, cleanupTestDir } from './helpers';
+import { scaffold } from '../src/ctl';
+
+describe('ctl scaffold', () => {
+    let cwd: string;
+
+    beforeEach(async () => {
+        cwd = await createTestDir();
+    });
+
+    afterEach(async () => {
+        await cleanupTestDir(cwd);
+    });
+
+    it('creates a capped command with manifest and script', async () => {
+        await scaffold(['deploy'], { cwd });
+
+        const cmdDir = path.join(cwd, '.agentctl', 'deploy');
+        expect(await fs.pathExists(cmdDir)).toBe(true);
+
+        const manifestPath = path.join(cmdDir, 'manifest.json');
+        expect(await fs.pathExists(manifestPath)).toBe(true);
+        const manifest = await fs.readJson(manifestPath);
+
+        expect(manifest).toEqual(expect.objectContaining({
+            name: 'deploy',
+            type: 'scaffold',
+            description: '',
+        }));
+
+        const scriptPath = path.join(cmdDir, manifest.run);
+        expect(await fs.pathExists(scriptPath)).toBe(true);
+
+        const scriptContent = await fs.readFile(scriptPath, 'utf-8');
+        if (process.platform === 'win32') {
+            expect(scriptContent).toContain('@echo off');
+        } else {
+            expect(scriptContent).toContain('#!/usr/bin/env');
+        }
+    });
+
+    it('creates nested commands implicitly creating groups', async () => {
+        await scaffold(['dev', 'start'], { cwd });
+
+        const groupDir = path.join(cwd, '.agentctl', 'dev');
+        expect(await fs.pathExists(groupDir)).toBe(true);
+
+        const cmdDir = path.join(groupDir, 'start');
+        expect(await fs.pathExists(cmdDir)).toBe(true);
+    });
+
+    it('fails if command already exists', async () => {
+        await scaffold(['deploy'], { cwd });
+
+        await expect(scaffold(['deploy'], { cwd }))
+            .rejects.toThrow(/already exists/);
+    });
+});

package/tests/scoping-guards.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs-extra';
+import path from 'path';
+import { createTestDir, cleanupTestDir } from './helpers';
+import { pushGlobal, pullLocal } from '../src/ctl';
+
+describe('scoping error guards', () => {
+    let testDir: string;
+    let globalDir: string;
+
+    beforeEach(async () => {
+        testDir = await createTestDir();
+        globalDir = await createTestDir();
+        // Create .agentctl so findLocalRoot works
+        await fs.ensureDir(path.join(testDir, '.agentctl'));
+    });
+
+    afterEach(async () => {
+        await cleanupTestDir(testDir);
+        await cleanupTestDir(globalDir);
+    });
+
+    it('pushGlobal throws if local command does not exist', async () => {
+        await expect(
+            pushGlobal(['nonexistent'], { cwd: testDir, globalDir })
+        ).rejects.toThrow('not found');
+    });
+
+    it('pullLocal throws if global command does not exist', async () => {
+        await expect(
+            pullLocal(['nonexistent'], { cwd: testDir, globalDir })
+        ).rejects.toThrow('not found');
+    });
+
+    it('pushGlobal throws if global command already exists', async () => {
+        // Create local command
+        const localCmd = path.join(testDir, '.agentctl', 'mycmd');
+        await fs.ensureDir(localCmd);
+        await fs.writeJson(path.join(localCmd, 'manifest.json'), {
+            name: 'mycmd', type: 'scaffold', run: './script.sh'
+        });
+
+        // Create conflicting global command
+        const globalCmd = path.join(globalDir, 'mycmd');
+        await fs.ensureDir(globalCmd);
+        await fs.writeJson(path.join(globalCmd, 'manifest.json'), {
+            name: 'mycmd', type: 'scaffold', run: './script.sh'
+        });
+
+        await expect(
+            pushGlobal(['mycmd'], { cwd: testDir, globalDir })
+        ).rejects.toThrow('already exists');
+    });
+
+    it('pullLocal throws if local command already exists', async () => {
+        // Create global command
+        const globalCmd = path.join(globalDir, 'mycmd');
+        await fs.ensureDir(globalCmd);
+        await fs.writeJson(path.join(globalCmd, 'manifest.json'), {
+            name: 'mycmd', type: 'scaffold', run: './script.sh'
+        });
+
+        // Create conflicting local command
+        const localCmd = path.join(testDir, '.agentctl', 'mycmd');
+        await fs.ensureDir(localCmd);
+        await fs.writeJson(path.join(localCmd, 'manifest.json'), {
+            name: 'mycmd', type: 'scaffold', run: './script.sh'
+        });
+
+        await expect(
+            pullLocal(['mycmd'], { cwd: testDir, globalDir })
+        ).rejects.toThrow('already exists');
+    });
+});

package/tests/scoping.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import path from 'path';
+import fs from 'fs-extra';
+import { createTestDir, cleanupTestDir } from './helpers';
+import { pushGlobal, pullLocal, scaffold } from '../src/ctl';
+
+describe('ctl scoping (global, local)', () => {
+    let localRoot: string;
+    let globalRoot: string;
+    let baseDir: string;
+
+    beforeEach(async () => {
+        baseDir = await createTestDir();
+        localRoot = path.join(baseDir, 'local');
+        globalRoot = path.join(baseDir, 'global');
+        await fs.ensureDir(localRoot);
+        await fs.ensureDir(globalRoot);
+    });
+
+    afterEach(async () => {
+        await cleanupTestDir(baseDir);
+    });
+
+    it('pushGlobal: copies local to global with --copy', async () => {
+        await scaffold(['deploy'], { cwd: localRoot });
+        const localPath = path.join(localRoot, '.agentctl', 'deploy');
+        const globalPath = path.join(globalRoot, 'deploy');
+
+        expect(await fs.pathExists(localPath)).toBe(true);
+        expect(await fs.pathExists(globalPath)).toBe(false);
+
+        await pushGlobal(['deploy'], { cwd: localRoot, globalDir: globalRoot, copy: true });
+
+        expect(await fs.pathExists(localPath)).toBe(true);
+        expect(await fs.pathExists(globalPath)).toBe(true);
+        const gManifest = await fs.readJson(path.join(globalPath, 'manifest.json'));
+        expect(gManifest.name).toBe('deploy');
+    });
+
+    it('pushGlobal: moves local to global with --move', async () => {
+        await scaffold(['deploy'], { cwd: localRoot });
+        const localPath = path.join(localRoot, '.agentctl', 'deploy');
+        const globalPath = path.join(globalRoot, 'deploy');
+
+        await pushGlobal(['deploy'], { cwd: localRoot, globalDir: globalRoot, move: true });
+
+        expect(await fs.pathExists(localPath)).toBe(false);
+        expect(await fs.pathExists(globalPath)).toBe(true);
+    });
+
+    it('pullLocal: moves global to local', async () => {
+        // Setup global manually
+        const globalPath = path.join(globalRoot, 'deploy');
+        await fs.ensureDir(globalPath);
+        await fs.writeJson(path.join(globalPath, 'manifest.json'), { name: 'deploy', type: 'scaffold' });
+
+        // Ensure local .agentctl exists
+        await fs.ensureDir(path.join(localRoot, '.agentctl'));
+        const localPath = path.join(localRoot, '.agentctl', 'deploy');
+
+        await pullLocal(['deploy'], { cwd: localRoot, globalDir: globalRoot, move: true });
+
+        expect(await fs.pathExists(globalPath)).toBe(false);
+        expect(await fs.pathExists(localPath)).toBe(true);
+    });
+});