all-hands-cli 0.1.8 → 0.1.9

package/.allhands/flows/shared/EXTERNAL_TECH_GUIDANCE.md

@@ -37,42 +37,26 @@ For proprietary domains with documentation pages:
 - Extract API patterns, configuration examples
 - Note version-specific behaviors
 
-### Open Source Inspiration (Clone & Browse)
-
-For exploring GitHub repositories locally:
-
-1. **Search for repositories**:
-   ```bash
-   gh search repos "<query>" --limit 5
-   ```
-
-2. **Clone to local research folder**:
-   ```bash
-   # Clone into .reposearch folder (gitignored)
-   mkdir -p .reposearch
-   git clone --depth 1 <repo-url> .reposearch/<repo-name>
-   ```
-
-   Note: Ensure `.reposearch/` is in the project's `.gitignore`.
-
-3. **Browse locally with standard tooling**:
-   - Use `Glob` to find files by pattern
-   - Use `Grep` to search code content
-   - Use `Read` to examine specific files
-   - Use `ls` to explore directory structure
-
-4. **Clean up when done** (optional):
-   ```bash
-   rm -rf .reposearch/<repo-name>
-   ```
-
-This approach leverages the agent's superior local file navigation capabilities:
-- Full regex search across the codebase
-- Fast pattern matching and file discovery
-- Direct file reading without API encoding issues
-- Study implementation patterns in similar projects
-- Extract architectural decisions
-- Note how libraries handle similar problems
+### Open Source Inspiration (`ah spawn reposearch`)
+
+Use `ah spawn reposearch` to clone external GitHub repos and delegate research to an AI agent that searches across both the current project and external codebases.
+
+**OSS codebase answers** — ask how a specific project handles something:
+```bash
+ah spawn reposearch "How does this project handle authentication?" --repos https://github.com/org/project
+```
+
+**Cross-repo comparison** — compare our implementation vs an external project:
+```bash
+ah spawn reposearch "Compare our error handling approach vs theirs" --repos https://github.com/org/project
+```
+
+**Multi-framework comparison** — check out 2+ repos, compare approaches side-by-side:
+```bash
+ah spawn reposearch "How do these projects handle routing?" --repos https://github.com/a/repo,https://github.com/b/repo
+```
+
+Re-running the same command with the same repos is fast — repos are cached locally between invocations.
 
 ### Parallel Exploration
 

package/.allhands/harness/src/commands/spawn.ts

@@ -3,13 +3,15 @@
  *
  * Commands:
  *   ah spawn codesearch "<query>" [--budget <n>] [--steps <n>]
+ *   ah spawn reposearch "<query>" --repos <url1,url2,...> [--steps <n>]
  */
 
 import { Command } from "commander";
-import { readFileSync } from "fs";
-import { dirname, join } from "path";
+import { existsSync, mkdirSync, readFileSync } from "fs";
+import { dirname, join, basename } from "path";
 import { fileURLToPath } from "url";
-import { AgentRunner, withDebugInfo } from "../lib/opencode/index.js";
+import { execFileSync } from "child_process";
+import { AgentRunner, withDebugInfo, type ReposearchOutput } from "../lib/opencode/index.js";
 import { BaseCommand, type CommandResult } from "../lib/base-command.js";
 import { loadProjectSettings } from "../hooks/shared.js";
 
@@ -19,15 +21,23 @@ const getProjectRoot = (): string => {
   return process.env.PROJECT_ROOT || process.cwd();
 };
 
-// Load prompt
+// Load prompts
 const CODESEARCH_PROMPT_PATH = join(__dirname, "../lib/opencode/prompts/codesearch.md");
 const getCodesearchPrompt = (): string => readFileSync(CODESEARCH_PROMPT_PATH, "utf-8");
 
-// Defaults
+const REPOSEARCH_PROMPT_PATH = join(__dirname, "../lib/opencode/prompts/reposearch.md");
+const getReposearchPrompt = (): string => readFileSync(REPOSEARCH_PROMPT_PATH, "utf-8");
+
+// Codesearch defaults
 const DEFAULT_TOOL_BUDGET = 12;
 const DEFAULT_STEPS_LIMIT = 20;
 const DEFAULT_TIMEOUT_MS = 120000; // 2 min
 
+// Reposearch defaults
+const DEFAULT_REPOSEARCH_STEPS = 30;
+const DEFAULT_REPOSEARCH_TIMEOUT_MS = 180000; // 3 min
+const DEFAULT_REPOSEARCH_TOOL_BUDGET = 20;
+
 // Output types
 interface CodeResult {
   file: string;
@@ -125,6 +135,165 @@ Respond with JSON matching the required schema.`;
   }
 }
 
+/**
+ * Derive a directory name from a GitHub URL.
+ * e.g. "https://github.com/org/repo" -> "org--repo"
+ */
+function repoDirName(url: string): string {
+  try {
+    const parsed = new URL(url);
+    // Remove .git suffix and leading slash, replace / with --
+    const path = parsed.pathname.replace(/\.git$/, "").replace(/^\//, "");
+    return path.replace(/\//g, "--");
+  } catch {
+    // Fallback: use basename-like extraction
+    return basename(url).replace(/\.git$/, "") || "repo";
+  }
+}
+
+/**
+ * Clone or pull a repo into the .reposearch directory.
+ * Returns the local directory path, or null on failure.
+ */
+function cloneOrPullRepo(reposearchDir: string, repoUrl: string): string | null {
+  const dirName = repoDirName(repoUrl);
+  const repoDir = join(reposearchDir, dirName);
+
+  try {
+    if (existsSync(join(repoDir, ".git"))) {
+      // Repo already cloned — pull latest
+      execFileSync("git", ["pull", "--ff-only"], {
+        cwd: repoDir,
+        stdio: "pipe",
+        timeout: 60000,
+      });
+    } else {
+      // Fresh clone (shallow)
+      mkdirSync(reposearchDir, { recursive: true });
+      execFileSync("git", ["clone", "--depth", "1", repoUrl, repoDir], {
+        stdio: "pipe",
+        timeout: 120000,
+      });
+    }
+    return repoDir;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Warning: Failed to clone/pull ${repoUrl}: ${message}`);
+    return null;
+  }
+}
+
+/**
+ * Reposearch command - spawn research agent that searches across current project and external repos.
+ */
+class ReposearchCommand extends BaseCommand {
+  readonly name = "reposearch";
+  readonly description = "Research code across the current project and external GitHub repositories";
+
+  defineArguments(cmd: Command): void {
+    cmd
+      .argument("<query>", "Research query (natural language)")
+      .requiredOption("--repos <urls>", "Comma-separated GitHub repo URLs to search")
+      .option("--steps <n>", "Hard step limit for agent iterations", String(DEFAULT_REPOSEARCH_STEPS))
+      .option("--debug", "Include agent debug metadata (model, timing, fallback) in output");
+  }
+
+  async execute(args: Record<string, unknown>): Promise<CommandResult> {
+    const query = args.query as string;
+    const reposRaw = args.repos as string;
+    const stepsLimit = parseInt((args.steps as string) ?? String(DEFAULT_REPOSEARCH_STEPS), 10);
+    const debug = !!args.debug;
+
+    if (!query) {
+      return this.error("validation_error", "query is required");
+    }
+    if (!reposRaw) {
+      return this.error("validation_error", "--repos is required (comma-separated GitHub URLs)");
+    }
+
+    const repoUrls = reposRaw.split(",").map((u) => u.trim()).filter(Boolean);
+    if (repoUrls.length === 0) {
+      return this.error("validation_error", "No valid repo URLs provided");
+    }
+
+    const projectRoot = getProjectRoot();
+    const reposearchDir = join(projectRoot, ".reposearch");
+
+    // Clone or pull each repo
+    const repoDirectories: Array<{ url: string; dir: string }> = [];
+    const warnings: string[] = [];
+
+    for (const url of repoUrls) {
+      const dir = cloneOrPullRepo(reposearchDir, url);
+      if (dir) {
+        repoDirectories.push({ url, dir });
+      } else {
+        warnings.push(`Failed to clone/pull: ${url}`);
+      }
+    }
+
+    if (repoDirectories.length === 0) {
+      return this.error("clone_error", "All repo clones/pulls failed. Check URLs and network.");
+    }
+
+    const runner = new AgentRunner(projectRoot);
+
+    // Build directory listing for the agent
+    const repoListing = repoDirectories
+      .map((r) => `- ${r.url} → ${r.dir}`)
+      .join("\n");
+
+    const userMessage = `## Research Query
+${query}
+
+## Directories to Search
+
+### Current Project
+- Root: ${projectRoot}
+
+### External Repositories
+${repoListing}
+
+## Budget
+- Tool budget (soft): ${DEFAULT_REPOSEARCH_TOOL_BUDGET} tool calls
+- Available tools: grep (text search), glob (file patterns), read (file content), lsp (if available)
+- Search all relevant directories to answer the query
+
+${warnings.length > 0 ? `## Warnings\n${warnings.map((w) => `- ${w}`).join("\n")}\n\n` : ""}Respond with JSON matching the required schema.`;
+
+    try {
+      const result = await runner.run<ReposearchOutput>(
+        {
+          name: "reposearch",
+          systemPrompt: getReposearchPrompt(),
+          timeoutMs: DEFAULT_REPOSEARCH_TIMEOUT_MS,
+          steps: stepsLimit,
+        },
+        userMessage
+      );
+
+      if (!result.success) {
+        return this.error("agent_error", result.error ?? "Unknown agent error");
+      }
+
+      const data = result.data!;
+
+      return this.success(withDebugInfo({
+        query,
+        repos_requested: repoUrls,
+        repos_analyzed: data.repos_analyzed,
+        analysis: data.analysis,
+        code_references: data.code_references,
+        warnings,
+        metadata: result.metadata,
+      }, result, debug));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return this.error("spawn_error", message);
+    }
+  }
+}
+
 /**
  * Register spawn commands on the given commander program.
  */
@@ -133,19 +302,35 @@ export function register(program: Command): void {
     .command("spawn")
     .description("Spawn sub-agents for specialized tasks");
 
+  // Register codesearch
   const codesearch = new CodesearchCommand();
-  const cmd = spawnCmd.command(codesearch.name).description(codesearch.description);
-  codesearch.defineArguments(cmd);
-  cmd.action(async (...args) => {
+  const codesearchCmd = spawnCmd.command(codesearch.name).description(codesearch.description);
+  codesearch.defineArguments(codesearchCmd);
+  codesearchCmd.action(async (...args) => {
     const opts = args[args.length - 2] as Record<string, unknown>;
     const cmdObj = args[args.length - 1] as Command;
     const positionalArgs = cmdObj.args;
 
-    // Map positional args to named args based on command definition
     const namedArgs: Record<string, unknown> = { ...opts };
     if (positionalArgs[0]) namedArgs.query = positionalArgs[0];
 
     const result = await codesearch.execute(namedArgs);
     console.log(JSON.stringify(result, null, 2));
   });
+
+  // Register reposearch
+  const reposearch = new ReposearchCommand();
+  const reposearchCmd = spawnCmd.command(reposearch.name).description(reposearch.description);
+  reposearch.defineArguments(reposearchCmd);
+  reposearchCmd.action(async (...args) => {
+    const opts = args[args.length - 2] as Record<string, unknown>;
+    const cmdObj = args[args.length - 1] as Command;
+    const positionalArgs = cmdObj.args;
+
+    const namedArgs: Record<string, unknown> = { ...opts };
+    if (positionalArgs[0]) namedArgs.query = positionalArgs[0];
+
+    const result = await reposearch.execute(namedArgs);
+    console.log(JSON.stringify(result, null, 2));
+  });
 }

package/.allhands/harness/src/lib/opencode/index.ts

@@ -101,6 +101,22 @@ export interface AggregatorOutput {
   design_notes?: string[];
 }
 
+// Reposearch output types
+export interface RepoCodeReference {
+  repo: string;        // "current" or the GitHub URL
+  file: string;        // relative path within the repo
+  line_start: number;
+  line_end: number;
+  code: string;
+  context: string;
+}
+
+export interface ReposearchOutput {
+  analysis: string;              // markdown research findings
+  code_references: RepoCodeReference[];
+  repos_analyzed: string[];
+}
+
 export { AgentRunner } from "./runner.js";
 
 // Debug metadata for agent results (included when --debug flag is passed)

package/.allhands/harness/src/lib/opencode/prompts/reposearch.md

@@ -0,0 +1,115 @@
+# Repo Search Agent
+
+You research code across a current project and one or more external GitHub repositories. You search all provided directories to answer questions, compare implementations, and analyze patterns across codebases. Return structured JSON with your findings.
+
+## Context
+
+You will receive:
+- **Project root directory**: The current project's codebase
+- **External repo directories**: One or more cloned GitHub repos under `.reposearch/`
+- **Research query**: What to investigate across these codebases
+
+## Available Tools
+
+**grep** - Text search via ripgrep
+- Search across any of the provided directories
+- Best for: string literals, identifiers, patterns, comments
+
+**glob** - File pattern matching
+- Discover files by extension or name pattern in any repo
+- Scope searches to specific directories
+
+**read** - File content retrieval
+- Read specific files from any repo after finding them
+- Specify line ranges when possible to minimize output
+
+**lsp** (if available) - Language Server Protocol
+- goToDefinition, findReferences, hover
+- Works on the current project; may not be available for external repos
+
+## Search Strategy
+
+1. **Understand the query**: Determine if it's about a single repo, a comparison, or a pattern search
+2. **Parallel discovery**: Search relevant directories simultaneously using grep/glob
+3. **Targeted reads**: Read specific files to understand implementations
+4. **Cross-reference**: Compare findings between repos to answer the query
+5. **Synthesize**: Combine findings into a coherent analysis
+
+## Budget Awareness
+
+You have a soft tool budget. Stay efficient:
+- Use grep/glob to narrow down before reading files
+- Don't read entire files when a section suffices
+- Avoid redundant searches across repos
+- Focus on the most relevant code to the query
+
+## Output Format
+
+Return ONLY valid JSON:
+
+```json
+{
+  "analysis": "## Findings\n\nMarkdown analysis of research findings...",
+  "code_references": [
+    {
+      "repo": "current",
+      "file": "src/auth/handler.ts",
+      "line_start": 10,
+      "line_end": 25,
+      "code": "function handleAuth() { ... }",
+      "context": "Current project's auth handler using JWT"
+    },
+    {
+      "repo": "https://github.com/org/project",
+      "file": "lib/auth.py",
+      "line_start": 45,
+      "line_end": 60,
+      "code": "class AuthMiddleware: ...",
+      "context": "External project uses middleware-based auth"
+    }
+  ],
+  "repos_analyzed": ["current", "https://github.com/org/project"]
+}
+```
+
+## Field Guidelines
+
+**analysis** (markdown string):
+- Structured markdown answering the research query
+- Include headings, comparisons, and key observations
+- Reference specific code when making claims
+- Keep focused on the query — don't summarize everything
+
+**code_references** (array, max 15):
+- `repo`: "current" for the project, or the GitHub URL for external repos
+- `file`: Relative path within the repo
+- `line_start` / `line_end`: 1-indexed line range
+- `code`: Actual code snippet (keep concise, 1-20 lines)
+- `context`: Why this reference is relevant (1 sentence)
+
+**repos_analyzed** (array):
+- List of repos that were actually searched
+- "current" for the project root
+- GitHub URLs for external repos
+
+## Use Cases
+
+**OSS Q&A**: "How does project X handle authentication?"
+- Focus on the external repo, search for auth-related patterns
+- Provide concrete code examples with explanation
+
+**Cross-repo comparison**: "Compare our error handling vs project X"
+- Search both repos for error handling patterns
+- Highlight similarities and differences in the analysis
+
+**Multi-framework comparison**: "How do projects A and B handle routing?"
+- Search multiple external repos
+- Compare approaches side-by-side in the analysis
+
+## Anti-patterns
+
+- Returning entire files instead of relevant sections
+- Analysis not grounded in actual code found
+- Missing cross-references when comparison was requested
+- Exceeding tool budget with redundant searches
+- Not searching all provided repos when the query requires it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "all-hands-cli",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Agentic harness for model-first software development",
   "type": "module",
   "bin": {