all-hands-cli 0.1.0

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

@@ -0,0 +1,61 @@
+/**
+ * Notification Commands
+ *
+ * Desktop notifications via jamf/Notifier (macOS).
+ * For direct CLI notification sending.
+ *
+ * Commands:
+ * - ah notify send <title> <message>    - Send a notification
+ *
+ * For hook-based notifications (idle, elicitation), see:
+ *   ah hooks notification --help
+ *
+ * Requires: https://github.com/jamf/Notifier
+ * Install: brew install --cask notifier
+ */
+
+import { Command } from 'commander';
+import { sendNotification } from '../lib/notification.js';
+import { tracedAction } from '../lib/base-command.js';
+
+export function register(program: Command): void {
+  const notify = program
+    .command('notify')
+    .description('Desktop notifications (direct CLI use)');
+
+  // ah notify send <title> <message>
+  notify
+    .command('send <title> <message>')
+    .description('Send a system notification')
+    .option('--sound <name>', 'Sound name (macOS system sounds)')
+    .option('-t, --type <type>', 'Notification type: banner or alert', 'banner')
+    .option('--json', 'Output as JSON')
+    .action(
+      tracedAction('notify send', async (
+        title: string,
+        message: string,
+        options: { sound?: string; type?: string; json?: boolean }
+      ) => {
+        const type = options.type as 'banner' | 'alert' | undefined;
+        const sent = sendNotification({
+          title,
+          message,
+          sound: options.sound,
+          type,
+        });
+
+        const result = sent
+          ? { success: true, sent: true, title, message }
+          : { success: false, sent: false, reason: 'notifier not available or failed' };
+
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else if (sent) {
+          console.log(`Notification sent: ${title}`);
+        } else {
+          console.error('Failed to send notification (notifier not installed?)');
+          process.exit(1);
+        }
+      })
+    );
+}

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

@@ -0,0 +1,158 @@
+/**
+ * Oracle Commands (Agent-Facing)
+ *
+ * Multi-provider LLM inference for agent tasks.
+ * Uses the standardized oracle library for provider integration.
+ *
+ * Commands:
+ * - ah oracle ask <query> - Raw LLM inference with file context
+ * - ah oracle pr-build [--branch] [--dry-run] - Create PR with generated description
+ *
+ */
+
+import { Command } from 'commander';
+import { tracedAction } from '../lib/base-command.js';
+import {
+  ask,
+  getDefaultProvider,
+  PROVIDERS,
+  type ProviderName,
+} from '../lib/llm.js';
+import { buildPR } from '../lib/oracle.js';
+
+export function register(program: Command): void {
+  const oracle = program
+    .command('oracle')
+    .description('Multi-provider LLM inference');
+
+  // ah oracle ask
+  oracle
+    .command('ask <query>')
+    .description('Raw LLM inference with optional file context')
+    .option('--provider <provider>', 'LLM provider (gemini | openai)', getDefaultProvider())
+    .option('--model <model>', 'Override default model')
+    .option('--files <files...>', 'Files to include as context')
+    .option('--context <context>', 'Additional context')
+    .option('--json', 'Output as JSON')
+    .action(tracedAction('oracle ask', async (query: string, options: {
+      provider: ProviderName;
+      model?: string;
+      files?: string[];
+      context?: string;
+      json?: boolean;
+    }) => {
+      // Validate provider
+      if (!PROVIDERS[options.provider]) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: 'Invalid provider. Use: gemini, openai' }));
+        } else {
+          console.error('Error: Invalid provider. Use: gemini, openai');
+        }
+        process.exit(1);
+      }
+
+      try {
+        const result = await ask(query, {
+          provider: options.provider,
+          model: options.model,
+          files: options.files,
+          context: options.context,
+        });
+
+        if (options.json) {
+          console.log(JSON.stringify({
+            success: true,
+            content: result.text,
+            model: result.model,
+            provider: result.provider,
+            duration_ms: result.durationMs,
+          }, null, 2));
+          return;
+        }
+
+        console.log(result.text);
+      } catch (e) {
+        const error = e instanceof Error ? e.message : String(e);
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error }));
+        } else {
+          console.error(`Error: ${error}`);
+        }
+        process.exit(1);
+      }
+    }));
+
+  // ah oracle pr-build
+  oracle
+    .command('pr-build')
+    .description('Create PR with generated description')
+    .option('--spec <spec>', 'Spec to create PR for (defaults to active)')
+    .option('--dry-run', 'Generate description without creating PR')
+    .option('--json', 'Output as JSON')
+    .action(tracedAction('oracle pr-build', async (options: {
+      spec?: string;
+      dryRun?: boolean;
+      json?: boolean;
+    }) => {
+      try {
+        // Import planning utils here to avoid circular dependency
+        const { getCurrentBranch, sanitizeBranchForDir, planningDirExists } = await import('../lib/planning.js');
+        const { getSpecForBranch } = await import('../lib/specs.js');
+
+        let spec = options.spec;
+        if (!spec) {
+          // Use current branch to find spec
+          const branch = getCurrentBranch();
+          const currentSpec = getSpecForBranch(branch);
+          if (currentSpec) {
+            spec = sanitizeBranchForDir(branch);
+          }
+        }
+        if (!spec) {
+          console.error('Error: No spec for current branch. Checkout a spec branch first.');
+          return;
+        }
+        const result = await buildPR(spec, undefined, options.dryRun);
+
+        if (options.json) {
+          console.log(JSON.stringify({
+            success: result.success,
+            pr_url: result.prUrl,
+            pr_number: result.prNumber,
+            title: result.title,
+            body: result.body,
+            review_steps: result.reviewSteps,
+            dry_run: options.dryRun || false,
+          }, null, 2));
+          return;
+        }
+
+        if (options.dryRun) {
+          console.log(`\n=== PR Preview (Dry Run) ===\n`);
+          console.log(`Title: ${result.title}`);
+          console.log(`\nBody:\n${result.body}`);
+          console.log(`\n=== Review Steps (Posted as Comment) ===\n`);
+          console.log(result.reviewSteps);
+          return;
+        }
+
+        if (result.success && result.prUrl) {
+          console.log(`\n=== PR Created ===\n`);
+          console.log(`URL: ${result.prUrl}`);
+          console.log(`Number: #${result.prNumber}`);
+          console.log(`Title: ${result.title}`);
+        } else {
+          console.error(`Failed to create PR: ${result.body}`);
+          process.exit(1);
+        }
+      } catch (e) {
+        const error = e instanceof Error ? e.message : String(e);
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error }));
+        } else {
+          console.error(`Error: ${error}`);
+        }
+        process.exit(1);
+      }
+    }));
+}

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

@@ -0,0 +1,220 @@
+/**
+ * Perplexity Commands (Agent-Facing)
+ *
+ * Web search with citations using Perplexity's sonar-pro model.
+ * Matches the configuration used by the Perplexity MCP server.
+ *
+ * Commands:
+ * - ah perplexity research <query> - Web search with citations
+ *   --challenge: Challenge findings using Grok X/Twitter search
+ */
+
+import { Command } from 'commander';
+import { tracedAction } from '../lib/base-command.js';
+
+interface PerplexityResponse {
+  choices?: Array<{
+    message?: {
+      content?: string;
+    };
+  }>;
+  citations?: string[];
+}
+
+interface GrokResponse {
+  choices?: Array<{
+    message?: {
+      content?: string;
+    };
+  }>;
+  citations?: string[];
+}
+
+const GROK_CHALLENGER_PROMPT = `You are a critical research challenger. Given research findings, search X to:
+
+1. CHALLENGE: Find contradicting opinions, failed implementations, known issues
+2. ALTERNATIVES: Surface newer/better tools the research may have missed
+3. TRENDS: Identify emerging patterns that could affect the recommendations
+4. SENTIMENT: Gauge real developer satisfaction vs marketing claims
+5. DISCUSSIONS: Find where the best practitioners are discussing this topic
+
+Be skeptical. Surface what the research missed or got wrong. Focus on recent posts (last 6 months).`;
+
+const GROK_TIMEOUT = 120000;
+
+const PERPLEXITY_TIMEOUT = parseInt(process.env.PERPLEXITY_TIMEOUT_MS ?? '60000', 10);
+
+export function register(program: Command): void {
+  const perplexity = program
+    .command('perplexity')
+    .description('Web search with citations');
+
+  // ah perplexity research
+  perplexity
+    .command('research <query>')
+    .description('Web search with citations (sonar-pro model)')
+    .option('--json', 'Output as JSON')
+    .option('--challenge', 'Challenge findings using Grok X/Twitter search')
+    .action(tracedAction('perplexity research', async (query: string, options: { json?: boolean; challenge?: boolean }) => {
+      const apiKey = process.env.PERPLEXITY_API_KEY;
+      if (!apiKey) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: 'PERPLEXITY_API_KEY not set' }));
+        } else {
+          console.error('Error: PERPLEXITY_API_KEY not set in environment');
+        }
+        process.exit(1);
+      }
+
+      try {
+        const response = await callPerplexityApi(apiKey, query);
+
+        const content = response.choices?.[0]?.message?.content ?? '';
+        const citations = response.citations ?? [];
+
+        // If --challenge flag, use Grok to challenge the findings
+        let challengeContent: string | undefined;
+        let challengeCitations: string[] | undefined;
+
+        if (options.challenge) {
+          const grokApiKey = process.env.X_AI_API_KEY;
+          if (!grokApiKey) {
+            if (options.json) {
+              console.log(JSON.stringify({ success: false, error: 'X_AI_API_KEY not set (required for --challenge)' }));
+            } else {
+              console.error('Error: X_AI_API_KEY not set in environment (required for --challenge)');
+            }
+            process.exit(1);
+          }
+
+          const grokResponse = await callGrokChallengeApi(grokApiKey, query, content);
+          challengeContent = grokResponse.choices?.[0]?.message?.content ?? '';
+          challengeCitations = grokResponse.citations ?? [];
+        }
+
+        if (options.json) {
+          const result: Record<string, unknown> = {
+            success: true,
+            query,
+            content,
+            citations,
+          };
+          if (options.challenge) {
+            result.challenge = {
+              content: challengeContent,
+              citations: challengeCitations,
+            };
+          }
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+
+        console.log('Research Results:');
+        console.log();
+        console.log(content);
+
+        if (citations.length > 0) {
+          console.log();
+          console.log('Citations:');
+          for (let i = 0; i < citations.length; i++) {
+            console.log(`  [${i + 1}] ${citations[i]}`);
+          }
+        }
+
+        if (options.challenge && challengeContent) {
+          console.log();
+          console.log('---');
+          console.log();
+          console.log('Challenge (via X/Twitter):');
+          console.log();
+          console.log(challengeContent);
+
+          if (challengeCitations && challengeCitations.length > 0) {
+            console.log();
+            console.log('Challenge Sources:');
+            for (const citation of challengeCitations) {
+              console.log(`  - ${citation}`);
+            }
+          }
+        }
+      } catch (e) {
+        const error = e instanceof Error ? e.message : String(e);
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error }));
+        } else {
+          console.error(`Error: ${error}`);
+        }
+        process.exit(1);
+      }
+    }));
+}
+
+async function callPerplexityApi(apiKey: string, query: string): Promise<PerplexityResponse> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), PERPLEXITY_TIMEOUT);
+
+  try {
+    const response = await fetch('https://api.perplexity.ai/chat/completions', {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: 'sonar-pro',
+        messages: [{ role: 'user', content: query }],
+      }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+    }
+
+    return (await response.json()) as PerplexityResponse;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function callGrokChallengeApi(
+  apiKey: string,
+  query: string,
+  findings: string
+): Promise<GrokResponse> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), GROK_TIMEOUT);
+
+  const userPrompt = `Original query: ${query}
+
+Research findings to challenge:
+${findings}
+
+Search X to challenge these findings.`;
+
+  try {
+    const response = await fetch('https://api.x.ai/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: 'grok-4-1-fast',
+        messages: [
+          { role: 'system', content: GROK_CHALLENGER_PROMPT },
+          { role: 'user', content: userPrompt },
+        ],
+      }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+    }
+
+    return (await response.json()) as GrokResponse;
+  } finally {
+    clearTimeout(timeout);
+  }
+}

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

@@ -0,0 +1,245 @@
+/**
+ * Planning Command - Manage .planning/ directories (branch-keyed)
+ *
+ * Commands:
+ * - ah planning status               - Show planning status for current branch
+ * - ah planning list                 - List all planning directories
+ * - ah planning ensure               - Ensure planning dir exists for current branch
+ *
+ * In the branch-keyed model:
+ * - Planning directories are keyed by sanitized branch name (feature/foo → feature-foo)
+ * - The spec's frontmatter.branch field is the source of truth
+ * - Current git branch determines the active context
+ */
+
+import { Command } from 'commander';
+import {
+  initializeStatus,
+  readStatus,
+  getPlanningPaths,
+  planningDirExists,
+  getCurrentBranch,
+  sanitizeBranchForDir,
+  ensurePlanningDir,
+  listPlanningDirs,
+  resetPlanningArtifacts,
+} from '../lib/planning.js';
+import { getSpecForBranch } from '../lib/specs.js';
+import { tracedAction } from '../lib/base-command.js';
+
+export function register(program: Command): void {
+  const cmd = program
+    .command('planning')
+    .description('Manage .planning/ directories (branch-keyed)');
+
+  // ah planning status
+  cmd
+    .command('status')
+    .description('Show planning status for current branch')
+    .option('--json', 'Output as JSON')
+    .action(tracedAction('planning status', async (options: { json?: boolean }) => {
+      const cwd = process.cwd();
+      const branch = getCurrentBranch(cwd);
+      const dirKey = sanitizeBranchForDir(branch);
+
+      // Find spec for current branch
+      const spec = getSpecForBranch(branch, cwd);
+      const status = readStatus(dirKey, cwd);
+
+      if (!spec) {
+        if (options.json) {
+          console.log(JSON.stringify({
+            success: true,
+            hasSpec: false,
+            hasPlanning: !!status,
+            branch,
+            message: 'No spec for this branch',
+          }, null, 2));
+        } else {
+          console.log(`Branch: ${branch}`);
+          console.log('No spec linked to this branch.');
+          if (status) {
+            console.log(`  (Planning dir exists: .planning/${dirKey}/)`);
+          }
+        }
+        return;
+      }
+
+      if (!status) {
+        if (options.json) {
+          console.log(JSON.stringify({
+            success: true,
+            hasSpec: true,
+            hasPlanning: false,
+            branch,
+            spec: {
+              id: spec.id,
+              path: spec.path,
+            },
+            message: 'Spec exists but no planning directory. Run "ah planning ensure".',
+          }, null, 2));
+        } else {
+          console.log(`Branch: ${branch}`);
+          console.log(`Spec: ${spec.id}`);
+          console.log('No planning directory. Run "ah planning ensure" to create it.');
+        }
+        return;
+      }
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          success: true,
+          hasSpec: true,
+          hasPlanning: true,
+          branch,
+          planningDir: `.planning/${dirKey}/`,
+          specInfo: {
+            id: spec.id,
+            path: spec.path,
+          },
+          ...status,
+        }, null, 2));
+      } else {
+        console.log(`Branch: ${branch}`);
+        console.log(`Spec: ${spec.id} (${spec.path})`);
+        console.log(`Planning: .planning/${dirKey}/`);
+        console.log(`Stage: ${status.stage}`);
+        if (status.pr) {
+          console.log(`PR: ${status.pr.url}`);
+        }
+      }
+    }));
+
+  // ah planning list
+  cmd
+    .command('list')
+    .description('List all planning directories')
+    .option('--json', 'Output as JSON')
+    .action(tracedAction('planning list', async (options: { json?: boolean }) => {
+      const cwd = process.cwd();
+      const dirs = listPlanningDirs(cwd);
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          success: true,
+          count: dirs.length,
+          dirs,
+        }, null, 2));
+      } else {
+        if (dirs.length === 0) {
+          console.log('No planning directories found.');
+          return;
+        }
+
+        console.log(`Found ${dirs.length} planning director${dirs.length === 1 ? 'y' : 'ies'}:\n`);
+        for (const dir of dirs) {
+          const marker = dir.isCurrent ? '→ ' : '  ';
+          console.log(`${marker}${dir.key}/`);
+          console.log(`    Spec: ${dir.specPath}`);
+          console.log(`    Stage: ${dir.stage}`);
+        }
+      }
+    }));
+
+  // ah planning ensure
+  cmd
+    .command('ensure')
+    .description('Ensure planning directory exists for current branch')
+    .option('--json', 'Output as JSON')
+    .action(tracedAction('planning ensure', async (options: { json?: boolean }) => {
+      const cwd = process.cwd();
+      const branch = getCurrentBranch(cwd);
+
+      // Find spec for this branch
+      const spec = getSpecForBranch(branch, cwd);
+
+      if (!spec) {
+        if (options.json) {
+          console.log(JSON.stringify({
+            success: false,
+            error: `No spec found for branch: ${branch}`,
+            branch,
+          }, null, 2));
+        } else {
+          console.error(`No spec found for branch: ${branch}`);
+          console.error('Use "ah specs current" to check branch-spec mapping.');
+        }
+        process.exit(1);
+      }
+
+      // Use sanitized branch name for directory
+      const dirKey = sanitizeBranchForDir(branch);
+      const alreadyExists = planningDirExists(dirKey, cwd);
+
+      if (!alreadyExists) {
+        // Create planning directory structure
+        ensurePlanningDir(dirKey, cwd);
+
+        // Initialize status file with original branch for collision detection
+        initializeStatus(dirKey, spec.path, branch, cwd);
+      }
+
+      const status = readStatus(dirKey, cwd);
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          success: true,
+          branch,
+          specId: spec.id,
+          specPath: spec.path,
+          planningDir: `.planning/${dirKey}/`,
+          created: !alreadyExists,
+          status,
+        }, null, 2));
+      } else {
+        if (alreadyExists) {
+          console.log(`Planning directory exists: .planning/${dirKey}/`);
+        } else {
+          console.log(`Created planning directory: .planning/${dirKey}/`);
+        }
+        console.log(`  Branch: ${branch}`);
+        console.log(`  Spec: ${spec.id} (${spec.path})`);
+        console.log(`  Stage: ${status?.stage || 'planning'}`);
+      }
+    }));
+
+  // ah planning reset
+  cmd
+    .command('reset')
+    .description('Reset planning artifacts for current branch (deletes prompts and alignment doc, resets stage to planning)')
+    .option('--json', 'Output as JSON')
+    .action(tracedAction('planning reset', async (options: { json?: boolean }) => {
+      const cwd = process.cwd();
+      const branch = getCurrentBranch(cwd);
+      const dirKey = sanitizeBranchForDir(branch);
+
+      if (!planningDirExists(dirKey, cwd)) {
+        if (options.json) {
+          console.log(JSON.stringify({
+            success: false,
+            error: `No planning directory for branch: ${branch}`,
+            branch,
+          }, null, 2));
+        } else {
+          console.error(`No planning directory for branch: ${branch}`);
+        }
+        process.exit(1);
+      }
+
+      const wasReset = resetPlanningArtifacts(dirKey, cwd);
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          success: wasReset,
+          branch,
+          planningDir: `.planning/${dirKey}/`,
+          message: 'Planning artifacts cleared — spec revision requires re-planning',
+        }, null, 2));
+      } else {
+        console.log('Planning artifacts cleared — spec revision requires re-planning');
+        console.log(`  Branch: ${branch}`);
+        console.log(`  Planning: .planning/${dirKey}/`);
+        console.log(`  Stage: planning`);
+      }
+    }));
+}