all-hands-cli 0.1.0

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

@@ -0,0 +1,73 @@
+/**
+ * Schema Command (Agent-Facing)
+ *
+ * Outputs schema definitions for file types.
+ * Agents use this to understand how to write valid files.
+ *
+ * Usage: ah schema <type> [property]
+ */
+
+import { Command } from 'commander';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { parse, stringify } from 'yaml';
+import { tracedAction } from '../lib/base-command.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export function register(program: Command): void {
+  program
+    .command('schema <type> [property]')
+    .description('Output schema for a file type (prompt, alignment, spec, documentation). Optionally specify a top-level property to inspect.')
+    .option('--json', 'Output as JSON instead of YAML')
+    .action(tracedAction('schema', async (type: string, property: string | undefined, options: { json?: boolean }) => {
+      // Path: harness/src/commands/ -> harness/src/ -> harness/ -> .allhands/ -> schemas/
+      const schemaDir = join(__dirname, '..', '..', '..', 'schemas');
+      const schemaPath = join(schemaDir, `${type}.yaml`);
+
+      if (!existsSync(schemaPath)) {
+        const available = getAvailableSchemas(schemaDir);
+        console.error(`Schema not found: ${type}`);
+        console.error(`Available schemas: ${available.join(', ')}`);
+        process.exit(1);
+      }
+
+      const content = readFileSync(schemaPath, 'utf-8');
+      const parsed = parse(content);
+
+      // If a property is specified, extract only that top-level property
+      if (property) {
+        if (!(property in parsed)) {
+          const availableProps = Object.keys(parsed);
+          console.warn(`Warning: Property '${property}' not found in schema '${type}'`);
+          console.warn(`Available top-level properties: ${availableProps.join(', ')}`);
+          process.exit(1);
+        }
+
+        const subset = { [property]: parsed[property] };
+        if (options.json) {
+          console.log(JSON.stringify(subset, null, 2));
+        } else {
+          console.log(stringify(subset));
+        }
+        return;
+      }
+
+      // Output full schema
+      if (options.json) {
+        console.log(JSON.stringify(parsed, null, 2));
+      } else {
+        console.log(content);
+      }
+    }));
+}
+
+function getAvailableSchemas(schemaDir: string): string[] {
+  if (!existsSync(schemaDir)) return [];
+
+  return readdirSync(schemaDir)
+    .filter((f) => f.endsWith('.yaml'))
+    .map((f) => f.replace('.yaml', ''));
+}

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

@@ -0,0 +1,128 @@
+/**
+ * Skills Command (Agent-Facing)
+ *
+ * Lists and discovers skills for domain expertise.
+ * Agents use this to find relevant skills for their tasks.
+ *
+ * Usage: ah skills list
+ */
+
+import { Command } from 'commander';
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { parse as parseYaml } from 'yaml';
+import { tracedAction } from '../lib/base-command.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+interface SkillFrontmatter {
+  name: string;
+  description: string;
+  globs: string[];
+  version?: string;
+  license?: string;
+}
+
+interface SkillEntry {
+  name: string;
+  description: string;
+  globs: string[];
+  file: string;
+}
+
+/**
+ * Extract frontmatter from markdown content
+ */
+function extractFrontmatter(content: string): Record<string, unknown> | null {
+  const frontmatterRegex = /^---\n([\s\S]*?)\n---/;
+  const match = content.match(frontmatterRegex);
+
+  if (!match) {
+    return null;
+  }
+
+  try {
+    return parseYaml(match[1]) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the skills directory path
+ * Path: harness/src/commands/ -> harness/src/ -> harness/ -> .allhands/ -> skills/
+ */
+function getSkillsDir(): string {
+  return join(__dirname, '..', '..', '..', 'skills');
+}
+
+/**
+ * List all skills by reading SKILL.md files and extracting frontmatter
+ */
+function listSkills(): SkillEntry[] {
+  const dir = getSkillsDir();
+
+  if (!existsSync(dir)) {
+    return [];
+  }
+
+  const entries = readdirSync(dir);
+  const skills: SkillEntry[] = [];
+
+  for (const entry of entries) {
+    const entryPath = join(dir, entry);
+    const stat = statSync(entryPath);
+
+    // Skip non-directories
+    if (!stat.isDirectory()) continue;
+
+    // Look for SKILL.md in the directory
+    const skillFile = join(entryPath, 'SKILL.md');
+    if (!existsSync(skillFile)) continue;
+
+    const content = readFileSync(skillFile, 'utf-8');
+    const frontmatter = extractFrontmatter(content) as SkillFrontmatter | null;
+
+    if (frontmatter && frontmatter.name && frontmatter.description && frontmatter.globs) {
+      skills.push({
+        name: frontmatter.name,
+        description: frontmatter.description,
+        globs: frontmatter.globs,
+        file: `.allhands/skills/${entry}/SKILL.md`,
+      });
+    }
+  }
+
+  return skills;
+}
+
+export function register(program: Command): void {
+  const cmd = program
+    .command('skills')
+    .description('Discover and list skills for domain expertise');
+
+  cmd
+    .command('list')
+    .description('List all skills with their descriptions and glob patterns')
+    .option('--json', 'Output as JSON (default)')
+    .action(tracedAction('skills list', async () => {
+      const skills = listSkills();
+
+      if (skills.length === 0) {
+        console.log(JSON.stringify({
+          success: true,
+          skills: [],
+          message: 'No skills found. Create skills in .allhands/skills/<name>/SKILL.md using `ah schema skill` for the file structure.',
+        }, null, 2));
+        return;
+      }
+
+      console.log(JSON.stringify({
+        success: true,
+        skills,
+        count: skills.length,
+      }, null, 2));
+    }));
+}

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

@@ -0,0 +1,353 @@
+/**
+ * Solutions Command (Agent-Facing)
+ *
+ * Grep-based search for documented solutions in docs/solutions/.
+ * Uses frontmatter fields (tags, module, component, symptoms) for precise matching.
+ *
+ * Usage:
+ *   ah solutions search <query>           Search solutions by keywords
+ *   ah solutions search <query> --full    Include full content of matches
+ *   ah solutions list                     List all solution categories
+ *   ah solutions list <category>          List solutions in a category
+ */
+
+import { Command } from 'commander';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { basename, join } from 'path';
+import { parse } from 'yaml';
+import { tracedAction } from '../lib/base-command.js';
+
+const getProjectRoot = (): string => {
+  return process.env.PROJECT_ROOT || process.cwd();
+};
+
+const getSolutionsDir = (): string => {
+  return join(getProjectRoot(), 'docs', 'solutions');
+};
+
+interface SolutionFrontmatter {
+  title: string;
+  date: string;
+  spec?: string;
+  problem_type: string;
+  component: string;
+  symptoms: string[];
+  root_cause: string;
+  severity: string;
+  tags: string[];
+  source?: string;
+}
+
+interface SolutionMatch {
+  path: string;
+  frontmatter: SolutionFrontmatter;
+  score: number;
+  matchedFields: string[];
+}
+
+/**
+ * Extract keywords from a search query.
+ * Handles quoted phrases and splits on whitespace.
+ */
+function extractKeywords(query: string): string[] {
+  const keywords: string[] = [];
+
+  // Extract quoted phrases first
+  const quotedRegex = /"([^"]+)"/g;
+  let match;
+  while ((match = quotedRegex.exec(query)) !== null) {
+    keywords.push(match[1].toLowerCase());
+  }
+
+  // Remove quoted phrases and split remaining on whitespace
+  const remaining = query.replace(quotedRegex, '').trim();
+  if (remaining) {
+    keywords.push(...remaining.toLowerCase().split(/\s+/).filter(k => k.length > 0));
+  }
+
+  return keywords;
+}
+
+/**
+ * Parse YAML frontmatter from a markdown file.
+ */
+function parseFrontmatter(filePath: string): SolutionFrontmatter | null {
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!fmMatch) return null;
+
+    const parsed = parse(fmMatch[1]) as SolutionFrontmatter;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Score how well a solution matches the search keywords.
+ */
+function scoreSolution(fm: SolutionFrontmatter, keywords: string[]): { score: number; matchedFields: string[] } {
+  let score = 0;
+  const matchedFields: string[] = [];
+
+  for (const keyword of keywords) {
+    // Title match (high weight)
+    if (fm.title?.toLowerCase().includes(keyword)) {
+      score += 3;
+      if (!matchedFields.includes('title')) matchedFields.push('title');
+    }
+
+    // Tags match (high weight)
+    if (fm.tags?.some(t => t.toLowerCase().includes(keyword))) {
+      score += 3;
+      if (!matchedFields.includes('tags')) matchedFields.push('tags');
+    }
+
+    // Component match (medium weight)
+    if (fm.component?.toLowerCase().includes(keyword)) {
+      score += 2;
+      if (!matchedFields.includes('component')) matchedFields.push('component');
+    }
+
+    // Symptoms match (medium weight)
+    if (fm.symptoms?.some(s => s.toLowerCase().includes(keyword))) {
+      score += 2;
+      if (!matchedFields.includes('symptoms')) matchedFields.push('symptoms');
+    }
+
+    // Problem type match (low weight)
+    if (fm.problem_type?.toLowerCase().includes(keyword)) {
+      score += 1;
+      if (!matchedFields.includes('problem_type')) matchedFields.push('problem_type');
+    }
+
+    // Root cause match (low weight)
+    if (fm.root_cause?.toLowerCase().replace(/_/g, ' ').includes(keyword)) {
+      score += 1;
+      if (!matchedFields.includes('root_cause')) matchedFields.push('root_cause');
+    }
+  }
+
+  return { score, matchedFields };
+}
+
+/**
+ * Find all solution files in the solutions directory.
+ */
+function findSolutionFiles(dir: string): string[] {
+  const files: string[] = [];
+
+  if (!existsSync(dir)) return files;
+
+  const entries = readdirSync(dir);
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      files.push(...findSolutionFiles(fullPath));
+    } else if (entry.endsWith('.md') && !entry.startsWith('README')) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Get all category directories.
+ */
+function getCategories(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+
+  return readdirSync(dir)
+    .filter(entry => {
+      const fullPath = join(dir, entry);
+      return statSync(fullPath).isDirectory();
+    })
+    .sort();
+}
+
+/**
+ * Search for solutions matching the query.
+ */
+function searchSolutions(query: string, limit: number = 10): SolutionMatch[] {
+  const solutionsDir = getSolutionsDir();
+  const keywords = extractKeywords(query);
+
+  if (keywords.length === 0) {
+    return [];
+  }
+
+  const files = findSolutionFiles(solutionsDir);
+  const matches: SolutionMatch[] = [];
+
+  for (const file of files) {
+    const frontmatter = parseFrontmatter(file);
+    if (!frontmatter) continue;
+
+    const { score, matchedFields } = scoreSolution(frontmatter, keywords);
+
+    if (score > 0) {
+      // Make path relative to project root
+      const relativePath = file.replace(getProjectRoot() + '/', '');
+      matches.push({
+        path: relativePath,
+        frontmatter,
+        score,
+        matchedFields,
+      });
+    }
+  }
+
+  // Sort by score descending
+  matches.sort((a, b) => b.score - a.score);
+
+  return matches.slice(0, limit);
+}
+
+/**
+ * Get full content of a solution file (without frontmatter).
+ */
+function getSolutionContent(filePath: string): string | null {
+  try {
+    const fullPath = filePath.startsWith('/') ? filePath : join(getProjectRoot(), filePath);
+    const content = readFileSync(fullPath, 'utf-8');
+    // Remove frontmatter
+    return content.replace(/^---\n[\s\S]*?\n---\n/, '').trim();
+  } catch {
+    return null;
+  }
+}
+
+export function register(program: Command): void {
+  const solutionsCmd = program
+    .command('solutions')
+    .description('Search and browse documented solutions');
+
+  // Search command
+  solutionsCmd
+    .command('search <query>')
+    .description('Search solutions by keywords (searches title, tags, component, symptoms)')
+    .option('--full', 'Include full content of matched solutions')
+    .option('--limit <n>', 'Maximum number of results', '10')
+    .action(tracedAction('solutions search', async (query: string, options: { full?: boolean; limit?: string }) => {
+      const limit = parseInt(options.limit || '10', 10);
+      const matches = searchSolutions(query, limit);
+
+      if (matches.length === 0) {
+        console.log(JSON.stringify({
+          success: true,
+          query,
+          keywords: extractKeywords(query),
+          results: [],
+          message: 'No matching solutions found',
+        }, null, 2));
+        return;
+      }
+
+      // Format output
+      const results = matches.map(match => {
+        const result: Record<string, unknown> = {
+          path: match.path,
+          title: match.frontmatter.title,
+          score: match.score,
+          matched_fields: match.matchedFields,
+          severity: match.frontmatter.severity,
+          problem_type: match.frontmatter.problem_type,
+          component: match.frontmatter.component,
+          tags: match.frontmatter.tags,
+        };
+
+        if (options.full) {
+          result.content = getSolutionContent(match.path);
+        }
+
+        return result;
+      });
+
+      console.log(JSON.stringify({
+        success: true,
+        query,
+        keywords: extractKeywords(query),
+        result_count: results.length,
+        results,
+      }, null, 2));
+    }));
+
+  // List command
+  solutionsCmd
+    .command('list [category]')
+    .description('List solution categories or solutions in a category')
+    .action(tracedAction('solutions list', async (category?: string) => {
+      const solutionsDir = getSolutionsDir();
+
+      if (!category) {
+        // List all categories
+        const categories = getCategories(solutionsDir);
+
+        if (categories.length === 0) {
+          console.log(JSON.stringify({
+            success: true,
+            message: 'No solution categories found. Create docs/solutions/<category>/ directories.',
+            categories: [],
+          }, null, 2));
+          return;
+        }
+
+        // Count solutions in each category
+        const categoryCounts = categories.map(cat => {
+          const catDir = join(solutionsDir, cat);
+          const files = findSolutionFiles(catDir);
+          return { category: cat, count: files.length };
+        });
+
+        console.log(JSON.stringify({
+          success: true,
+          categories: categoryCounts,
+        }, null, 2));
+        return;
+      }
+
+      // List solutions in specific category
+      const categoryDir = join(solutionsDir, category);
+
+      if (!existsSync(categoryDir)) {
+        const available = getCategories(solutionsDir);
+        console.log(JSON.stringify({
+          success: false,
+          error: `Category not found: ${category}`,
+          available_categories: available,
+        }, null, 2));
+        process.exit(1);
+      }
+
+      const files = findSolutionFiles(categoryDir);
+      const solutions = files.map(file => {
+        const fm = parseFrontmatter(file);
+        const relativePath = file.replace(getProjectRoot() + '/', '');
+        return {
+          path: relativePath,
+          title: fm?.title || basename(file, '.md'),
+          date: fm?.date,
+          severity: fm?.severity,
+          tags: fm?.tags || [],
+        };
+      });
+
+      // Sort by date descending
+      solutions.sort((a, b) => {
+        if (!a.date) return 1;
+        if (!b.date) return -1;
+        return b.date.localeCompare(a.date);
+      });
+
+      console.log(JSON.stringify({
+        success: true,
+        category,
+        solution_count: solutions.length,
+        solutions,
+      }, null, 2));
+    }));
+}

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

@@ -0,0 +1,158 @@
+/**
+ * Spawn commands - agent spawning via OpenCode SDK.
+ *
+ * Commands:
+ *   ah spawn codesearch "<query>" [--budget <n>] [--steps <n>]
+ */
+
+import { Command } from "commander";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { AgentRunner } from "../lib/opencode/index.js";
+import { BaseCommand, type CommandResult } from "../lib/base-command.js";
+import { loadProjectSettings } from "../hooks/shared.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const getProjectRoot = (): string => {
+  return process.env.PROJECT_ROOT || process.cwd();
+};
+
+// Load prompt
+const CODESEARCH_PROMPT_PATH = join(__dirname, "../lib/opencode/prompts/codesearch.md");
+const getCodesearchPrompt = (): string => readFileSync(CODESEARCH_PROMPT_PATH, "utf-8");
+
+// Defaults
+const DEFAULT_TOOL_BUDGET = 12;
+const DEFAULT_STEPS_LIMIT = 20;
+const DEFAULT_TIMEOUT_MS = 120000; // 2 min
+
+// Output types
+interface CodeResult {
+  file: string;
+  line_start: number;
+  line_end: number;
+  code: string;
+  relevance: "high" | "medium" | "low";
+  match_type: "structural" | "text" | "semantic";
+  context?: string;
+}
+
+interface CodesearchOutput {
+  results: CodeResult[];
+  warnings: string[];
+  dev_notes: {
+    tool_budget_used: number;
+    tools_invoked: string[];
+    tools_failed: string[];
+  };
+}
+
+/**
+ * Codesearch command - spawn code search agent with ast-grep, ripgrep, and LSP.
+ */
+class CodesearchCommand extends BaseCommand {
+  readonly name = "codesearch";
+  readonly description = "AI code search with structural (ast-grep), text (ripgrep), and semantic (LSP) tools";
+
+  defineArguments(cmd: Command): void {
+    cmd
+      .argument("<query>", "Code search query (natural language or pattern)")
+      .option("--budget <n>", "Soft tool budget hint for the agent", String(DEFAULT_TOOL_BUDGET))
+      .option("--steps <n>", "Hard step limit for agent iterations", String(DEFAULT_STEPS_LIMIT));
+  }
+
+  async execute(args: Record<string, unknown>): Promise<CommandResult> {
+    const query = args.query as string;
+    const settings = loadProjectSettings();
+    const toolBudget = parseInt(
+      (args.budget as string) ??
+        String(settings?.opencodeSdk?.codesearchToolBudget ?? DEFAULT_TOOL_BUDGET),
+      10
+    );
+    const stepsLimit = parseInt((args.steps as string) ?? String(DEFAULT_STEPS_LIMIT), 10);
+
+    if (!query) {
+      return this.error("validation_error", "query is required");
+    }
+
+    const projectRoot = getProjectRoot();
+    const runner = new AgentRunner(projectRoot);
+
+    // Build user message with budget context
+    const userMessage = `## Search Query
+${query}
+
+## Budget
+- Tool budget (soft): ${toolBudget} tool calls
+- Available tools: ast-grep MCP (structural), grep (text), read, lsp, glob
+- Prioritize structural matches (ast-grep) for code patterns, text (grep) for literals/comments
+
+Respond with JSON matching the required schema.`;
+
+    try {
+      const result = await runner.run<CodesearchOutput>(
+        {
+          name: "codesearch",
+          systemPrompt: getCodesearchPrompt(),
+          timeoutMs: DEFAULT_TIMEOUT_MS,
+          steps: stepsLimit,
+          // MCP servers can be configured via environment or passed explicitly
+          // mcp: {
+          //   "ast-grep": {
+          //     type: "local",
+          //     command: ["uvx", "--from", "ast-grep-mcp", "ast-grep-mcp"],
+          //   },
+          // },
+        },
+        userMessage
+      );
+
+      if (!result.success) {
+        return this.error("agent_error", result.error ?? "Unknown agent error");
+      }
+
+      const data = result.data!;
+
+      // Warnings are included in the response data
+
+      return this.success({
+        query,
+        result_count: data.results.length,
+        results: data.results,
+        warnings: data.warnings,
+        dev_notes: data.dev_notes,
+        metadata: result.metadata,
+      });
+    } 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.
+ */
+export function register(program: Command): void {
+  const spawnCmd = program
+    .command("spawn")
+    .description("Spawn sub-agents for specialized tasks");
+
+  const codesearch = new CodesearchCommand();
+  const cmd = spawnCmd.command(codesearch.name).description(codesearch.description);
+  codesearch.defineArguments(cmd);
+  cmd.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));
+  });
+}