all-hands-cli 0.1.0

package/.allhands/harness/src/mcp/__tests__/index.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Tests for MCP Server Registry
+ */
+
+import { describe, expect, it } from 'vitest';
+import { discoverServers, getServer, listServerNames } from '../index.js';
+
+describe('MCP Server Registry', () => {
+  it('discovers servers from directory', async () => {
+    const servers = await discoverServers();
+
+    // Returns a Map (may be empty if no servers configured)
+    expect(servers).toBeInstanceOf(Map);
+  });
+
+  it('getServer returns undefined for unknown name', async () => {
+    const config = await getServer('nonexistent-server');
+    expect(config).toBeUndefined();
+  });
+
+  it('listServerNames returns array', async () => {
+    const names = await listServerNames();
+
+    expect(names).toBeInstanceOf(Array);
+
+    // If there are names, they should be sorted
+    if (names.length > 0) {
+      const sorted = [...names].sort();
+      expect(names).toEqual(sorted);
+    }
+  });
+
+  it('server configs have required fields when present', async () => {
+    const servers = await discoverServers();
+
+    for (const [name, config] of servers) {
+      expect(config.name).toBe(name);
+      expect(config.description).toBeTruthy();
+
+      // Should have either command (stdio) or url (http/sse)
+      const hasCommand = config.command !== undefined;
+      const hasUrl = config.url !== undefined;
+      expect(hasCommand || hasUrl).toBe(true);
+    }
+  });
+});

package/.allhands/harness/src/mcp/_template.ts

@@ -0,0 +1,47 @@
+/**
+ * MCP Server Template
+ *
+ * Copy this file to create a new MCP server integration:
+ *   cp _template.ts my-server.ts
+ *
+ * Then edit the config to match your server's requirements.
+ * The server will be automatically discovered by `ah tools`.
+ */
+
+import type { McpServerConfig } from '../lib/mcp-runtime.js';
+
+export const config: McpServerConfig = {
+  // Unique name for this server (used in CLI: ah tools <name>:tool)
+  name: 'template',
+
+  // Human-readable description
+  description: 'Template MCP server - copy and customize',
+
+  // Transport type: 'stdio' (default), 'http', or 'sse'
+  type: 'stdio',
+
+  // For stdio transport: command to execute
+  command: 'npx',
+  args: ['-y', '@example/mcp-server'],
+
+  // Environment variables - use ${VAR_NAME} for values from .env.ai
+  env: {
+    // EXAMPLE_API_KEY: '${EXAMPLE_API_KEY}',
+  },
+
+  // For http/sse transport: URL endpoint (instead of command/args)
+  // url: 'https://api.example.com/mcp',
+
+  // HTTP headers for http/sse transport
+  // headers: {
+  //   Authorization: 'Bearer ${API_TOKEN}',
+  // },
+
+  // Tools to hide from discovery (optional)
+  // hiddenTools: ['dangerous_tool', 'internal_tool'],
+
+  // Extra hints for specific tools (shown in --help)
+  // toolHints: {
+  //   my_tool: 'Use this when you need to do X. Prefer Y for Z.',
+  // },
+};

package/.allhands/harness/src/mcp/filesystem.ts

@@ -0,0 +1,33 @@
+/**
+ * Filesystem MCP Server - File system operations
+ *
+ * Provides file reading and directory listing capabilities.
+ * Stateless - each call is independent.
+ *
+ * Source: https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem
+ *
+ * No API key required.
+ */
+
+import type { McpServerConfig } from '../lib/mcp-runtime.js';
+
+export const config: McpServerConfig = {
+  name: 'filesystem',
+
+  description: 'File system operations - read files, list directories',
+
+  type: 'stdio',
+
+  command: 'npx',
+  // The path argument is the allowed directory - using current working directory
+  args: ['-y', '@modelcontextprotocol/server-filesystem', '.'],
+
+  // Stateless - no session persistence needed
+  stateful: false,
+
+  toolHints: {
+    read_file: 'Read the contents of a file at the given path.',
+    list_directory: 'List contents of a directory.',
+    write_file: 'Write content to a file.',
+  },
+};

package/.allhands/harness/src/mcp/index.ts

@@ -0,0 +1,69 @@
+/**
+ * MCP Server Registry
+ *
+ * Auto-discovers MCP server configs from this directory.
+ * Each .ts file (except index.ts and _template.ts) should export
+ * a `config` object of type McpServerConfig.
+ */
+
+import { readdirSync, statSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import type { McpServerConfig } from '../lib/mcp-runtime.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export interface McpServerModule {
+  config: McpServerConfig;
+}
+
+/**
+ * Discover and load all MCP server configs.
+ */
+export async function discoverServers(): Promise<Map<string, McpServerConfig>> {
+  const servers = new Map<string, McpServerConfig>();
+  const entries = readdirSync(__dirname);
+
+  for (const entry of entries) {
+    // Skip index and template
+    if (entry === 'index.ts' || entry === '_template.ts') continue;
+
+    const entryPath = join(__dirname, entry);
+    const stat = statSync(entryPath);
+
+    // Only .ts files
+    if (stat.isDirectory()) continue;
+    if (!entry.endsWith('.ts')) continue;
+
+    const moduleName = entry.replace('.ts', '');
+    const importPath = `./${moduleName}.js`;
+
+    try {
+      const module = (await import(importPath)) as McpServerModule;
+      if (module.config && typeof module.config === 'object') {
+        servers.set(module.config.name, module.config);
+      }
+    } catch (e) {
+      // Log but don't fail - allow partial discovery
+      console.error(`Warning: Could not load MCP server ${moduleName}: ${e}`);
+    }
+  }
+
+  return servers;
+}
+
+/**
+ * Get a specific server config by name.
+ */
+export async function getServer(name: string): Promise<McpServerConfig | undefined> {
+  const servers = await discoverServers();
+  return servers.get(name);
+}
+
+/**
+ * List all available server names.
+ */
+export async function listServerNames(): Promise<string[]> {
+  const servers = await discoverServers();
+  return Array.from(servers.keys()).sort();
+}

package/.allhands/harness/src/mcp/playwright.ts

@@ -0,0 +1,34 @@
+/**
+ * Playwright MCP Server - Browser automation via Microsoft Playwright
+ *
+ * Provides browser automation using Playwright's accessibility tree.
+ * LLM-friendly - operates on structured data, no vision models needed.
+ *
+ * Source: https://github.com/microsoft/playwright-mcp
+ *
+ * No API key required.
+ */
+
+import type { McpServerConfig } from '../lib/mcp-runtime.js';
+
+export const config: McpServerConfig = {
+  name: 'playwright',
+
+  description: 'Browser automation - navigate, click, fill forms, take screenshots',
+
+  type: 'stdio',
+
+  command: 'npx',
+  args: ['-y', '@playwright/mcp@latest'],
+
+  // Stateful - browser session persists between calls
+  stateful: true,
+
+  toolHints: {
+    browser_navigate: 'Navigate to a URL. First step for any browser interaction.',
+    browser_snapshot: 'Get accessibility snapshot of the page. Use to understand page structure.',
+    browser_click: 'Click an element by reference from snapshot.',
+    browser_type: 'Type text into a focused element.',
+    browser_screenshot: 'Take a screenshot. Returns base64 PNG.',
+  },
+};

package/.allhands/harness/src/mcp/xcodebuild.ts

@@ -0,0 +1,29 @@
+import type { McpServerConfig } from '../lib/mcp-runtime.js';
+
+export const config: McpServerConfig = {
+  name: 'xcodebuild',
+  description: 'Xcode build, test, deploy, UI automation, debugging, and simulator management',
+  type: 'stdio',
+  command: 'npx',
+  args: ['-y', 'xcodebuildmcp@latest'],
+  stateful: true,
+  stateful_session_timeout: 600000, // 10 min — builds are slow
+  toolHints: {
+    discover_projs: 'First step — find workspace/project files in a directory.',
+    list_schemes: 'List available build schemes for a project.',
+    'session-set-defaults': 'Set workspace, scheme, simulator for all subsequent calls. Use workspacePath for CocoaPods projects. Do this early.',
+    build_sim: 'Build for iOS simulator.',
+    build_run_sim: 'Build, install, and launch on simulator in one step.',
+    list_sims: 'List available simulators with UDIDs.',
+    boot_sim: 'Boot a simulator by name or UDID.',
+    describe_ui: 'Get view hierarchy with precise frame coordinates for all visible elements. Use before UI interactions.',
+    screenshot: 'Capture simulator screenshot as PNG.',
+    tap: 'Tap an element by coordinates from describe_ui.',
+    type_text: 'Type text into the focused element.',
+    start_sim_log_cap: 'Start capturing simulator logs. Requires bundleId.',
+    stop_sim_log_cap: 'Stop log capture and retrieve logs. Requires logSessionId.',
+    record_sim_video: 'Record simulator screen video.',
+    clean: 'Clean build products.',
+    doctor: 'Check environment health (Xcode, simulators, tools).',
+  },
+};

package/.allhands/harness/src/schemas/docs.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Documentation Configuration",
+  "description": "Configuration for the documentation flow. If domains are not specified, the agent will infer them from codebase structure.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "domains": {
+      "type": "array",
+      "description": "Main domains to document. Each domain becomes a top-level folder in docs/. If empty or missing, agent will auto-detect and ask for confirmation.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Domain identifier used for docs folder naming"
+          },
+          "path": {
+            "type": "string",
+            "description": "Path to the source code for this domain"
+          },
+          "description": {
+            "type": "string",
+            "description": "Brief description of what this domain contains"
+          }
+        },
+        "required": ["name", "path"],
+        "additionalProperties": false
+      }
+    },
+    "exclude": {
+      "type": "array",
+      "description": "Glob patterns for files and directories to exclude from documentation. Matched relative to project root. Excluded paths are filtered out before discovery agents scan the codebase.",
+      "items": {
+        "type": "string",
+        "description": "Glob pattern (e.g., \"**/test/**\", \"src/generated/**\", \"**/*.spec.ts\")"
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/.allhands/harness/src/schemas/settings.schema.json

@@ -0,0 +1,214 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://allhands.dev/schemas/settings.schema.json",
+  "title": "All-Hands Project Settings",
+  "description": "Repository-specific configuration for the all-hands harness",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "git": {
+      "type": "object",
+      "description": "Git-related settings",
+      "properties": {
+        "baseBranch": {
+          "type": "string",
+          "default": "main",
+          "description": "Base branch for diff comparisons (main, master, develop, etc.)"
+        }
+      }
+    },
+    "tldr": {
+      "type": "object",
+      "description": "TLDR semantic indexing settings",
+      "properties": {
+        "enableForHarness": {
+          "type": "boolean",
+          "default": false,
+          "description": "Index .allhands directory alongside the project root. Useful for harness development."
+        }
+      }
+    },
+    "validation": {
+      "type": "object",
+      "description": "Validation and quality settings",
+      "properties": {
+        "format": {
+          "type": "object",
+          "description": "Auto-format configuration for edited files",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "Enable auto-formatting after Write/Edit tool use"
+            },
+            "command": {
+              "type": "string",
+              "description": "Default format command (e.g., 'pnpm format', 'bun run format')"
+            },
+            "patterns": {
+              "type": "array",
+              "description": "File-specific format commands",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "match": {
+                    "type": "string",
+                    "description": "Glob pattern to match files (e.g., '*.py', 'src/**/*.ts')"
+                  },
+                  "command": {
+                    "type": "string",
+                    "description": "Format command for matched files"
+                  }
+                },
+                "required": ["match", "command"]
+              }
+            }
+          }
+        }
+      }
+    },
+    "knowledge": {
+      "type": "object",
+      "description": "Knowledge search and indexing settings",
+      "properties": {
+        "similarityThreshold": {
+          "type": "number",
+          "default": 0.65,
+          "description": "Minimum similarity score for knowledge search results (0.0-1.0)"
+        },
+        "fullContextSimilarityThreshold": {
+          "type": "number",
+          "default": 0.82,
+          "description": "Similarity threshold above which full file contents are included in results (0.0-1.0)"
+        },
+        "contextTokenLimit": {
+          "type": "integer",
+          "default": 5000,
+          "description": "Maximum cumulative token budget for search results"
+        }
+      }
+    },
+    "oracle": {
+      "type": "object",
+      "description": "Oracle inference settings",
+      "properties": {
+        "defaultProvider": {
+          "type": "string",
+          "enum": ["gemini", "openai"],
+          "default": "gemini",
+          "description": "Default LLM provider for oracle/inference calls"
+        },
+        "compactionProvider": {
+          "type": "string",
+          "enum": ["gemini", "openai"],
+          "default": "gemini",
+          "description": "LLM provider for compaction analysis (defaults to gemini for large context window)"
+        }
+      }
+    },
+    "opencodeSdk": {
+      "type": "object",
+      "description": "OpenCode SDK agent execution settings",
+      "properties": {
+        "model": {
+          "type": "string",
+          "description": "Model identifier for agent execution (e.g., 'opencode/grok-code')"
+        },
+        "codesearchToolBudget": {
+          "type": "integer",
+          "default": 12,
+          "description": "Soft tool budget hint for codesearch agent"
+        }
+      }
+    },
+    "spawn": {
+      "type": "object",
+      "description": "Agent spawn settings",
+      "properties": {
+        "maxParallelPrompts": {
+          "type": "integer",
+          "default": 3,
+          "minimum": 1,
+          "maximum": 10,
+          "description": "Maximum concurrent executor agents when parallel mode is enabled"
+        },
+        "promptScopedAutocompactAt": {
+          "type": "integer",
+          "default": 65,
+          "description": "Autocompact threshold percentage for prompt-scoped agents"
+        }
+      }
+    },
+    "emergent": {
+      "type": "object",
+      "description": "Emergent work settings (default domain pool for emergent planner)",
+      "properties": {
+        "hypothesisDomains": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Default pool of hypothesis domains available to the emergent planner. Agents diversify across these to discover valuable improvements.",
+          "examples": [
+            ["testing", "stability", "performance", "feature", "ux", "integration"],
+            ["reproduction", "diagnosis", "stability", "testing"]
+          ]
+        }
+      }
+    },
+    "daemon": {
+      "type": "object",
+      "description": "Background daemon settings",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Enable the MCP daemon for background services"
+        }
+      }
+    },
+    "eventLoop": {
+      "type": "object",
+      "description": "Event loop timing settings",
+      "properties": {
+        "tickIntervalMs": {
+          "type": "integer",
+          "default": 5000,
+          "minimum": 1000,
+          "description": "Main event loop tick interval in milliseconds"
+        }
+      }
+    },
+    "prReview": {
+      "type": "object",
+      "description": "PR review detection and triggering settings",
+      "properties": {
+        "reviewMatchPattern": {
+          "type": "string",
+          "default": "greptile",
+          "description": "Pattern to match against PR comment author name and body to detect a review (case-insensitive)"
+        },
+        "rerunComment": {
+          "type": "string",
+          "default": "@greptile",
+          "description": "Comment to post on PR to trigger a re-review"
+        },
+        "checkFrequency": {
+          "type": "integer",
+          "default": 3,
+          "minimum": 1,
+          "description": "Check for PR reviews every N event loop ticks"
+        }
+      }
+    },
+    "disabledHooks": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": [],
+      "description": "Hook names to disable (pass through without executing). Format: 'category hookname' e.g. 'context signature', 'enforcement research-fetch'."
+    }
+  }
+}