macro-agent 0.2.4 → 0.2.6

package/src/agent-detection/__tests__/registry.test.ts

@@ -1,254 +0,0 @@
-/**
- * Agent Registry Tests
- */
-
-import { describe, it, expect } from "vitest";
-
-import {
-  AgentRegistry,
-  createAgentRegistry,
-  BUILTIN_AGENTS,
-} from "../registry.js";
-import type { CLIAgentDefinition } from "../types.js";
-
-describe("AgentRegistry", () => {
-  // ===========================================================================
-  // Built-in Agents
-  // ===========================================================================
-
-  describe("BUILTIN_AGENTS", () => {
-    it("contains all 6 known agents", () => {
-      expect(BUILTIN_AGENTS).toHaveLength(6);
-    });
-
-    it("includes claude-code", () => {
-      const agent = BUILTIN_AGENTS.find((a) => a.id === "claude-code");
-      expect(agent).toBeDefined();
-      expect(agent!.binary).toBe("claude");
-      expect(agent!.vendor).toBe("Anthropic");
-    });
-
-    it("includes codex", () => {
-      const agent = BUILTIN_AGENTS.find((a) => a.id === "codex");
-      expect(agent).toBeDefined();
-      expect(agent!.binary).toBe("codex");
-      expect(agent!.vendor).toBe("OpenAI");
-    });
-
-    it("includes gemini-cli", () => {
-      const agent = BUILTIN_AGENTS.find((a) => a.id === "gemini-cli");
-      expect(agent).toBeDefined();
-      expect(agent!.binary).toBe("gemini");
-      expect(agent!.vendor).toBe("Google");
-    });
-
-    it("includes opencode", () => {
-      const agent = BUILTIN_AGENTS.find((a) => a.id === "opencode");
-      expect(agent).toBeDefined();
-      expect(agent!.binary).toBe("opencode");
-      expect(agent!.vendor).toBe("Anomaly");
-    });
-
-    it("includes aider", () => {
-      const agent = BUILTIN_AGENTS.find((a) => a.id === "aider");
-      expect(agent).toBeDefined();
-      expect(agent!.binary).toBe("aider");
-      expect(agent!.vendor).toBe("Aider");
-    });
-
-    it("includes goose", () => {
-      const agent = BUILTIN_AGENTS.find((a) => a.id === "goose");
-      expect(agent).toBeDefined();
-      expect(agent!.binary).toBe("goose");
-      expect(agent!.vendor).toBe("Block");
-    });
-
-    it("all agents have required fields", () => {
-      for (const agent of BUILTIN_AGENTS) {
-        expect(agent.id).toBeTruthy();
-        expect(agent.name).toBeTruthy();
-        expect(agent.description).toBeTruthy();
-        expect(agent.binary).toBeTruthy();
-        expect(agent.versionArgs).toBeDefined();
-        expect(agent.versionArgs.length).toBeGreaterThan(0);
-        expect(agent.headless).toBeDefined();
-        expect(agent.headless.promptFlag).toBeDefined();
-        expect(agent.vendor).toBeTruthy();
-      }
-    });
-  });
-
-  // ===========================================================================
-  // Registry Operations
-  // ===========================================================================
-
-  describe("constructor", () => {
-    it("creates registry with built-in agents", () => {
-      const registry = new AgentRegistry();
-      expect(registry.size).toBe(6);
-    });
-
-    it("creates registry with additional custom agents", () => {
-      const custom: CLIAgentDefinition = {
-        id: "custom-agent",
-        name: "Custom Agent",
-        description: "A custom agent",
-        binary: "custom",
-        versionArgs: ["--version"],
-        headless: { promptFlag: "--prompt" },
-        vendor: "Custom",
-      };
-      const registry = new AgentRegistry([custom]);
-      expect(registry.size).toBe(7);
-      expect(registry.get("custom-agent")).toEqual(custom);
-    });
-
-    it("custom agents can override built-in agents", () => {
-      const override: CLIAgentDefinition = {
-        id: "claude-code",
-        name: "Custom Claude",
-        description: "Overridden",
-        binary: "custom-claude",
-        versionArgs: ["--version"],
-        headless: { promptFlag: "-p" },
-        vendor: "Custom",
-      };
-      const registry = new AgentRegistry([override]);
-      expect(registry.get("claude-code")!.binary).toBe("custom-claude");
-    });
-  });
-
-  describe("get()", () => {
-    it("returns agent definition by ID", () => {
-      const registry = new AgentRegistry();
-      const agent = registry.get("claude-code");
-      expect(agent).toBeDefined();
-      expect(agent!.id).toBe("claude-code");
-    });
-
-    it("returns undefined for unknown ID", () => {
-      const registry = new AgentRegistry();
-      expect(registry.get("nonexistent")).toBeUndefined();
-    });
-  });
-
-  describe("has()", () => {
-    it("returns true for existing agent", () => {
-      const registry = new AgentRegistry();
-      expect(registry.has("claude-code")).toBe(true);
-    });
-
-    it("returns false for unknown agent", () => {
-      const registry = new AgentRegistry();
-      expect(registry.has("nonexistent")).toBe(false);
-    });
-  });
-
-  describe("register()", () => {
-    it("adds a new agent definition", () => {
-      const registry = new AgentRegistry();
-      const custom: CLIAgentDefinition = {
-        id: "new-agent",
-        name: "New Agent",
-        description: "Newly added",
-        binary: "new",
-        versionArgs: ["--version"],
-        headless: { promptFlag: "--prompt" },
-        vendor: "New",
-      };
-      registry.register(custom);
-      expect(registry.has("new-agent")).toBe(true);
-      expect(registry.get("new-agent")).toEqual(custom);
-    });
-
-    it("overrides existing agent definition", () => {
-      const registry = new AgentRegistry();
-      const override: CLIAgentDefinition = {
-        id: "claude-code",
-        name: "Custom Claude",
-        description: "Overridden",
-        binary: "custom",
-        versionArgs: ["--version"],
-        headless: { promptFlag: "-p" },
-        vendor: "Custom",
-      };
-      registry.register(override);
-      expect(registry.get("claude-code")!.name).toBe("Custom Claude");
-    });
-  });
-
-  describe("remove()", () => {
-    it("removes an existing agent definition", () => {
-      const registry = new AgentRegistry();
-      expect(registry.remove("claude-code")).toBe(true);
-      expect(registry.has("claude-code")).toBe(false);
-      expect(registry.size).toBe(5);
-    });
-
-    it("returns false for non-existent agent", () => {
-      const registry = new AgentRegistry();
-      expect(registry.remove("nonexistent")).toBe(false);
-    });
-  });
-
-  describe("list()", () => {
-    it("returns all registered agents", () => {
-      const registry = new AgentRegistry();
-      const agents = registry.list();
-      expect(agents).toHaveLength(6);
-      const ids = agents.map((a) => a.id);
-      expect(ids).toContain("claude-code");
-      expect(ids).toContain("codex");
-      expect(ids).toContain("gemini-cli");
-      expect(ids).toContain("opencode");
-      expect(ids).toContain("aider");
-      expect(ids).toContain("goose");
-    });
-  });
-
-  describe("listEnabled()", () => {
-    it("returns all agents when no disabled list", () => {
-      const registry = new AgentRegistry();
-      expect(registry.listEnabled()).toHaveLength(6);
-    });
-
-    it("returns all agents when disabled list is empty", () => {
-      const registry = new AgentRegistry();
-      expect(registry.listEnabled([])).toHaveLength(6);
-    });
-
-    it("excludes disabled agents", () => {
-      const registry = new AgentRegistry();
-      const enabled = registry.listEnabled(["goose", "aider"]);
-      expect(enabled).toHaveLength(4);
-      const ids = enabled.map((a) => a.id);
-      expect(ids).not.toContain("goose");
-      expect(ids).not.toContain("aider");
-    });
-  });
-
-  // ===========================================================================
-  // Factory
-  // ===========================================================================
-
-  describe("createAgentRegistry()", () => {
-    it("creates registry with defaults", () => {
-      const registry = createAgentRegistry();
-      expect(registry.size).toBe(6);
-    });
-
-    it("creates registry with additional agents", () => {
-      const custom: CLIAgentDefinition = {
-        id: "extra",
-        name: "Extra",
-        description: "Extra agent",
-        binary: "extra",
-        versionArgs: ["--version"],
-        headless: { promptFlag: "--prompt" },
-        vendor: "Extra",
-      };
-      const registry = createAgentRegistry([custom]);
-      expect(registry.size).toBe(7);
-    });
-  });
-});

package/src/agent-detection/command-builder.ts

@@ -1,90 +0,0 @@
-/**
- * Command Builder
- *
- * Constructs headless invocation commands for CLI coding agents
- * based on their definitions.
- */
-
-import type {
-  CLIAgentDefinition,
-  SpawnCommand,
-  SpawnCommandOptions,
-} from "./types.js";
-import { AgentDetectionError } from "./types.js";
-
-/**
- * Build a headless spawn command for a CLI agent.
- *
- * Constructs the command and arguments array based on the agent definition's
- * headless configuration, model flag, and working directory flag.
- *
- * @param definition - The CLI agent definition
- * @param task - The prompt/task to pass to the agent
- * @param options - Optional model and cwd overrides
- * @returns The command and args array ready for child_process.spawn()
- *
- * @example
- * ```ts
- * const cmd = buildSpawnCommand(claudeCode, "Fix the auth bug", { model: "claude-sonnet-4-5" });
- * // { command: "claude", args: ["-p", "Fix the auth bug", "--output-format", "stream-json", "--model", "claude-sonnet-4-5"] }
- * ```
- */
-export function buildSpawnCommand(
-  definition: CLIAgentDefinition,
-  task: string,
-  options?: SpawnCommandOptions
-): SpawnCommand {
-  if (!task) {
-    throw new AgentDetectionError(
-      "Task prompt is required",
-      "DETECTION_FAILED"
-    );
-  }
-
-  const args: string[] = [];
-
-  // 1. Subcommand (e.g., "exec", "run")
-  if (definition.headless.subcommand) {
-    args.push(definition.headless.subcommand);
-  }
-
-  // 2. Default flags (e.g., "--full-auto", "--yes")
-  if (definition.headless.defaultFlags) {
-    args.push(...definition.headless.defaultFlags);
-  }
-
-  // 3. Model flag
-  if (options?.model && definition.modelFlag) {
-    args.push(definition.modelFlag, options.model);
-  }
-
-  // 4. Working directory flag
-  if (options?.cwd && definition.cwdFlag) {
-    args.push(definition.cwdFlag, options.cwd);
-  }
-
-  // 5. Prompt (flag-based or positional)
-  if (definition.headless.promptFlag) {
-    args.push(definition.headless.promptFlag, task);
-  } else {
-    args.push(task);
-  }
-
-  return { command: definition.binary, args };
-}
-
-/**
- * Format a spawn command as a single shell string (for display/logging).
- */
-export function formatSpawnCommand(spawnCommand: SpawnCommand): string {
-  const parts = [spawnCommand.command];
-  for (const arg of spawnCommand.args) {
-    // Quote arguments that contain spaces
-    if (arg.includes(" ")) {
-      parts.push(`"${arg}"`);
-    } else {
-      parts.push(arg);
-    }
-  }
-  return parts.join(" ");
-}

package/src/agent-detection/detector.ts

@@ -1,307 +0,0 @@
-/**
- * CLI Agent Detector
- *
- * Detects installed CLI coding agents by checking PATH availability
- * and querying version information. Results are cached with configurable TTL.
- */
-
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-
-import type {
-  CLIAgentDefinition,
-  DetectedAgent,
-  DetectionResult,
-  AgentDetectionConfig,
-} from "./types.js";
-import { AgentDetectionError } from "./types.js";
-import { AgentRegistry, createAgentRegistry } from "./registry.js";
-
-const execFileAsync = promisify(execFile);
-
-// =============================================================================
-// Constants
-// =============================================================================
-
-const DEFAULT_CACHE_TTL_MS = 60_000;
-const DEFAULT_WHICH_TIMEOUT_MS = 5_000;
-const DEFAULT_VERSION_TIMEOUT_MS = 10_000;
-
-/** Regex to parse version strings like "1.2.3", "0.82.1-beta", etc. */
-const VERSION_REGEX = /\d+\.\d+[\.\d]*/;
-
-// =============================================================================
-// Agent Detector
-// =============================================================================
-
-/**
- * Detects installed CLI coding agents on the system.
- *
- * Runs binary lookups and version checks in parallel, caches results,
- * and provides query methods for available agents.
- */
-export class AgentDetector {
-  private readonly registry: AgentRegistry;
-  private readonly cacheTtlMs: number;
-  private readonly whichTimeoutMs: number;
-  private readonly versionTimeoutMs: number;
-  private readonly disabledAgents: Set<string>;
-
-  private cachedResult: DetectionResult | null = null;
-  private detectionInProgress: Promise<DetectionResult> | null = null;
-
-  constructor(config?: AgentDetectionConfig) {
-    this.cacheTtlMs = config?.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
-    this.whichTimeoutMs = config?.whichTimeoutMs ?? DEFAULT_WHICH_TIMEOUT_MS;
-    this.versionTimeoutMs =
-      config?.versionTimeoutMs ?? DEFAULT_VERSION_TIMEOUT_MS;
-    this.disabledAgents = new Set(config?.disabledAgents ?? []);
-
-    this.registry = createAgentRegistry(config?.additionalAgents);
-  }
-
-  /**
-   * Get the underlying agent registry.
-   */
-  getRegistry(): AgentRegistry {
-    return this.registry;
-  }
-
-  /**
-   * Detect all installed agents.
-   *
-   * Returns cached results if available and not expired.
-   * If a detection is already in progress, returns its promise.
-   */
-  async detect(options?: { refresh?: boolean }): Promise<DetectionResult> {
-    // Return cached result if valid
-    if (!options?.refresh && this.cachedResult && !this.isCacheExpired()) {
-      return this.cachedResult;
-    }
-
-    // If detection is already running, return the in-progress promise
-    if (this.detectionInProgress) {
-      return this.detectionInProgress;
-    }
-
-    // Start a new detection scan
-    this.detectionInProgress = this.runDetection();
-
-    try {
-      const result = await this.detectionInProgress;
-      this.cachedResult = result;
-      return result;
-    } finally {
-      this.detectionInProgress = null;
-    }
-  }
-
-  /**
-   * Get available agents (installed only by default).
-   */
-  async getAvailableAgents(options?: {
-    refresh?: boolean;
-    includeNotInstalled?: boolean;
-  }): Promise<DetectionResult> {
-    const result = await this.detect({ refresh: options?.refresh });
-
-    if (options?.includeNotInstalled) {
-      return result;
-    }
-
-    return {
-      ...result,
-      agents: result.agents.filter((a) => a.installed),
-    };
-  }
-
-  /**
-   * Get a specific detected agent by ID.
-   */
-  async getAgent(id: string): Promise<DetectedAgent | undefined> {
-    const result = await this.detect();
-    return result.agents.find((a) => a.id === id);
-  }
-
-  /**
-   * Check if a specific agent is installed.
-   */
-  async isInstalled(id: string): Promise<boolean> {
-    const agent = await this.getAgent(id);
-    return agent?.installed ?? false;
-  }
-
-  /**
-   * Get the definition for an agent, throwing if not found.
-   */
-  getDefinition(id: string): CLIAgentDefinition {
-    const def = this.registry.get(id);
-    if (!def) {
-      throw new AgentDetectionError(
-        `Unknown agent backend: ${id}`,
-        "UNKNOWN_AGENT",
-        id
-      );
-    }
-    return def;
-  }
-
-  /**
-   * Invalidate the detection cache.
-   */
-  invalidateCache(): void {
-    this.cachedResult = null;
-  }
-
-  /**
-   * Get partial results if detection is in progress, or cached results.
-   * Returns null if no results are available yet.
-   */
-  getCachedResult(): DetectionResult | null {
-    return this.cachedResult;
-  }
-
-  /**
-   * Whether a detection scan is currently running.
-   */
-  isDetecting(): boolean {
-    return this.detectionInProgress !== null;
-  }
-
-  // ===========================================================================
-  // Private
-  // ===========================================================================
-
-  private isCacheExpired(): boolean {
-    if (!this.cachedResult) return true;
-    const maxAge = Math.max(...this.cachedResult.agents.map((a) => a.detectedAt));
-    return Date.now() - maxAge > this.cacheTtlMs;
-  }
-
-  private async runDetection(): Promise<DetectionResult> {
-    const definitions = this.registry.listEnabled(
-      Array.from(this.disabledAgents)
-    );
-    const startTime = Date.now();
-
-    const results = await Promise.allSettled(
-      definitions.map((def) => this.detectAgent(def))
-    );
-
-    const agents: DetectedAgent[] = results.map((result, i) => {
-      if (result.status === "fulfilled") {
-        return result.value;
-      }
-      // On failure, return a not-installed entry
-      return {
-        id: definitions[i].id,
-        name: definitions[i].name,
-        installed: false,
-        definition: definitions[i],
-        detectedAt: Date.now(),
-      };
-    });
-
-    return {
-      agents,
-      scanned: definitions.length,
-      durationMs: Date.now() - startTime,
-    };
-  }
-
-  private async detectAgent(
-    definition: CLIAgentDefinition
-  ): Promise<DetectedAgent> {
-    const detectedAt = Date.now();
-
-    // Step 1: Check if binary exists on PATH
-    const binaryPath = await this.findBinary(definition.binary);
-
-    if (!binaryPath) {
-      return {
-        id: definition.id,
-        name: definition.name,
-        installed: false,
-        definition,
-        detectedAt,
-      };
-    }
-
-    // Step 2: Get version string
-    const version = await this.getVersion(definition);
-
-    return {
-      id: definition.id,
-      name: definition.name,
-      installed: true,
-      version: version ?? undefined,
-      path: binaryPath,
-      definition,
-      detectedAt,
-    };
-  }
-
-  private async findBinary(binary: string): Promise<string | null> {
-    try {
-      const { stdout } = await execFileAsync("which", [binary], {
-        timeout: this.whichTimeoutMs,
-      });
-      const path = stdout.trim();
-      return path || null;
-    } catch {
-      // Binary not found or which failed
-      try {
-        // Fallback to command -v
-        const { stdout } = await execFileAsync(
-          "/bin/sh",
-          ["-c", `command -v ${binary}`],
-          { timeout: this.whichTimeoutMs }
-        );
-        const path = stdout.trim();
-        return path || null;
-      } catch {
-        return null;
-      }
-    }
-  }
-
-  private async getVersion(
-    definition: CLIAgentDefinition
-  ): Promise<string | null> {
-    try {
-      const { stdout, stderr } = await execFileAsync(
-        definition.binary,
-        definition.versionArgs,
-        { timeout: this.versionTimeoutMs }
-      );
-
-      // Some tools output version to stderr
-      const output = stdout || stderr;
-      return parseVersion(output);
-    } catch {
-      return null;
-    }
-  }
-}
-
-// =============================================================================
-// Helpers
-// =============================================================================
-
-/**
- * Parse a version string from command output.
- * Extracts the first semver-like pattern (e.g., "1.2.3").
- */
-export function parseVersion(output: string): string | null {
-  const match = output.match(VERSION_REGEX);
-  return match ? match[0] : null;
-}
-
-/**
- * Create a new AgentDetector with the given configuration.
- */
-export function createAgentDetector(
-  config?: AgentDetectionConfig
-): AgentDetector {
-  return new AgentDetector(config);
-}

package/src/agent-detection/index.ts

@@ -1,36 +0,0 @@
-/**
- * CLI Agent Auto-Detection Module
- *
- * Detects installed CLI coding agents, exposes them via a registry,
- * and provides command construction for headless invocation.
- */
-
-// Types
-export type {
-  CLIAgentDefinition,
-  HeadlessConfig,
-  DetectedAgent,
-  DetectionResult,
-  SpawnCommand,
-  SpawnCommandOptions,
-  AgentDetectionConfig,
-  AgentDetectionErrorCode,
-} from "./types.js";
-export { AgentDetectionError } from "./types.js";
-
-// Registry
-export {
-  AgentRegistry,
-  createAgentRegistry,
-  BUILTIN_AGENTS,
-} from "./registry.js";
-
-// Detector
-export {
-  AgentDetector,
-  createAgentDetector,
-  parseVersion,
-} from "./detector.js";
-
-// Command builder
-export { buildSpawnCommand, formatSpawnCommand } from "./command-builder.js";