ralphctl 0.1.0

package/src/ai/lifecycle.ts

@@ -0,0 +1,45 @@
+import { spawnSync } from 'node:child_process';
+import { assertSafeCwd } from '@src/utils/paths.ts';
+
+/** Lifecycle events where hooks can fire. Extend this union for new phases. */
+export type LifecycleEvent = 'sprintStart' | 'taskComplete';
+
+export interface HookResult {
+  passed: boolean;
+  output: string;
+}
+
+/** Default timeout for lifecycle hooks: 5 minutes. Override via RALPHCTL_SETUP_TIMEOUT_MS. */
+const DEFAULT_HOOK_TIMEOUT_MS = 5 * 60 * 1000;
+
+function getHookTimeoutMs(): number {
+  const envVal = process.env['RALPHCTL_SETUP_TIMEOUT_MS'];
+  if (envVal) {
+    const parsed = Number(envVal);
+    if (!Number.isNaN(parsed) && parsed > 0) return parsed;
+  }
+  return DEFAULT_HOOK_TIMEOUT_MS;
+}
+
+/**
+ * Run a lifecycle hook script in a project directory.
+ *
+ * Scripts are user-configured via `project add` or `project repo add` —
+ * they are NOT arbitrary AI-generated commands.
+ */
+export function runLifecycleHook(projectPath: string, script: string, event: LifecycleEvent): HookResult {
+  assertSafeCwd(projectPath);
+  const timeoutMs = getHookTimeoutMs();
+
+  const result = spawnSync(script, {
+    cwd: projectPath,
+    shell: true,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+    timeout: timeoutMs,
+    env: { ...process.env, RALPHCTL_LIFECYCLE_EVENT: event },
+  });
+
+  const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+  return { passed: result.status === 0, output };
+}

package/src/ai/parser.ts

@@ -0,0 +1,40 @@
+export interface ExecutionResult {
+  success: boolean;
+  output: string;
+  blockedReason?: string;
+  verified?: boolean;
+  verificationOutput?: string;
+}
+
+/**
+ * Parse execution result from AI provider output.
+ * Checks for task-verified, task-complete, and task-blocked signals.
+ */
+export function parseExecutionResult(output: string): ExecutionResult {
+  // Check for verification signal
+  const verifiedMatch = /<task-verified>([\s\S]*?)<\/task-verified>/.exec(output);
+  const verified = verifiedMatch !== null;
+  const verificationOutput = verifiedMatch?.[1]?.trim();
+
+  // Check for completion signal
+  if (output.includes('<task-complete>')) {
+    if (!verified) {
+      return {
+        success: false,
+        output,
+        blockedReason:
+          'Task marked complete without verification. Output <task-verified> with verification results before <task-complete>.',
+      };
+    }
+    return { success: true, output, verified, verificationOutput };
+  }
+
+  // Check for blocked signal
+  const blockedMatch = /<task-blocked>([\s\S]*?)<\/task-blocked>/.exec(output);
+  if (blockedMatch) {
+    return { success: false, output, blockedReason: blockedMatch[1]?.trim(), verified, verificationOutput };
+  }
+
+  // No signal found - treat as incomplete
+  return { success: false, output, blockedReason: 'No completion signal received', verified, verificationOutput };
+}

package/src/ai/permissions.ts

@@ -0,0 +1,207 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { AiProvider } from '@src/schemas/index.ts';
+
+interface PermissionsConfig {
+  allow?: string[];
+  deny?: string[];
+}
+
+interface SettingsFile {
+  permissions?: PermissionsConfig;
+}
+
+export interface ProviderPermissions {
+  allow: string[];
+  deny: string[];
+}
+
+/**
+ * Get AI provider permissions from settings files.
+ * For Claude: checks .claude/settings.local.json and ~/.claude/settings.json
+ * For Copilot: returns empty permissions (Copilot uses --available-tools/--excluded-tools flags)
+ *
+ * @param projectPath - Project directory to check for settings
+ * @param provider - AI provider (defaults to 'claude' for backward compat)
+ * @returns Combined permissions from both sources
+ */
+export function getProviderPermissions(projectPath: string, provider?: AiProvider): ProviderPermissions {
+  const permissions: ProviderPermissions = {
+    allow: [],
+    deny: [],
+  };
+
+  // Copilot manages permissions via CLI flags, not settings files
+  if (provider === 'copilot') {
+    return permissions;
+  }
+
+  // Check project-level settings (.claude/settings.local.json)
+  const projectSettingsPath = join(projectPath, '.claude', 'settings.local.json');
+  if (existsSync(projectSettingsPath)) {
+    try {
+      const content = readFileSync(projectSettingsPath, 'utf-8');
+      const settings = JSON.parse(content) as SettingsFile;
+      if (settings.permissions?.allow) {
+        permissions.allow.push(...settings.permissions.allow);
+      }
+      if (settings.permissions?.deny) {
+        permissions.deny.push(...settings.permissions.deny);
+      }
+    } catch {
+      // Ignore parse errors
+    }
+  }
+
+  // Check user-level settings (~/.claude/settings.json)
+  const userSettingsPath = join(homedir(), '.claude', 'settings.json');
+  if (existsSync(userSettingsPath)) {
+    try {
+      const content = readFileSync(userSettingsPath, 'utf-8');
+      const settings = JSON.parse(content) as SettingsFile;
+      if (settings.permissions?.allow) {
+        permissions.allow.push(...settings.permissions.allow);
+      }
+      if (settings.permissions?.deny) {
+        permissions.deny.push(...settings.permissions.deny);
+      }
+    } catch {
+      // Ignore parse errors
+    }
+  }
+
+  return permissions;
+}
+
+/**
+ * Check if a specific tool/command is allowed in permissions.
+ *
+ * Permission patterns:
+ * - "Bash(command:*)" - matches "Bash" tool with command starting with "command"
+ * - "Bash(git commit:*)" - matches git commit with any message
+ * - "Bash(*)" - matches any Bash command
+ *
+ * @returns true if explicitly allowed, false if denied, 'ask' if no match
+ */
+export function isToolAllowed(permissions: ProviderPermissions, tool: string, specifier?: string): boolean | 'ask' {
+  // Check deny list first (deny takes precedence)
+  for (const pattern of permissions.deny) {
+    if (matchesPattern(pattern, tool, specifier)) {
+      return false;
+    }
+  }
+
+  // Check allow list
+  for (const pattern of permissions.allow) {
+    if (matchesPattern(pattern, tool, specifier)) {
+      return true;
+    }
+  }
+
+  // No explicit permission - will ask
+  return 'ask';
+}
+
+/**
+ * Match a permission pattern against a tool call.
+ *
+ * Pattern formats:
+ * - "ToolName" - matches tool name exactly
+ * - "ToolName(specifier)" - matches exact specifier
+ * - "ToolName(prefix*)" - matches specifier starting with prefix
+ * - "ToolName(*)" - matches any specifier for this tool
+ */
+function matchesPattern(pattern: string, tool: string, specifier?: string): boolean {
+  // Parse pattern
+  const parenIdx = pattern.indexOf('(');
+
+  if (parenIdx === -1) {
+    // Pattern is just tool name
+    return pattern === tool;
+  }
+
+  const patternTool = pattern.slice(0, parenIdx);
+  if (patternTool !== tool) {
+    return false;
+  }
+
+  // Extract specifier pattern (remove parentheses)
+  const specPattern = pattern.slice(parenIdx + 1, -1);
+
+  if (specPattern === '*') {
+    // Matches any specifier
+    return true;
+  }
+
+  if (!specifier) {
+    return false;
+  }
+
+  if (specPattern.endsWith(':*')) {
+    // Prefix match (e.g., "git commit:*" matches "git commit -m 'msg'")
+    const prefix = specPattern.slice(0, -2);
+    return specifier.startsWith(prefix);
+  }
+
+  if (specPattern.endsWith('*')) {
+    // Simple prefix match
+    const prefix = specPattern.slice(0, -1);
+    return specifier.startsWith(prefix);
+  }
+
+  // Exact match
+  return specPattern === specifier;
+}
+
+export interface PermissionWarning {
+  tool: string;
+  specifier?: string;
+  message: string;
+}
+
+/**
+ * Check permissions for common operations needed during task execution.
+ *
+ * For Claude: reads settings files and warns about operations that may need approval.
+ * For Copilot: returns no warnings (all tools granted via --allow-all-tools).
+ *
+ * @returns Array of warnings for operations that may need approval
+ */
+export function checkTaskPermissions(
+  projectPath: string,
+  options: {
+    checkScript?: string | null;
+    needsCommit?: boolean;
+    provider?: AiProvider;
+  }
+): PermissionWarning[] {
+  const warnings: PermissionWarning[] = [];
+  const permissions = getProviderPermissions(projectPath, options.provider);
+
+  // Check git commit permission
+  if (options.needsCommit !== false) {
+    const commitAllowed = isToolAllowed(permissions, 'Bash', 'git commit');
+    if (commitAllowed !== true) {
+      warnings.push({
+        tool: 'Bash',
+        specifier: 'git commit',
+        message: 'Git commits may require manual approval',
+      });
+    }
+  }
+
+  // Check check script permission
+  if (options.checkScript) {
+    const checkAllowed = isToolAllowed(permissions, 'Bash', options.checkScript);
+    if (checkAllowed !== true) {
+      warnings.push({
+        tool: 'Bash',
+        specifier: options.checkScript,
+        message: `Check script "${options.checkScript}" may require approval`,
+      });
+    }
+  }
+
+  return warnings;
+}

package/src/ai/process-manager.ts

@@ -0,0 +1,248 @@
+import type { ChildProcess } from 'node:child_process';
+import { EXIT_INTERRUPTED } from '@src/utils/exit-codes.ts';
+
+/**
+ * Graceful shutdown timeout - how long to wait for children to exit after SIGTERM
+ */
+const GRACEFUL_SHUTDOWN_TIMEOUT_MS = 5000;
+
+/**
+ * Double-signal window - time window for second Ctrl+C to trigger force-quit
+ */
+const FORCE_QUIT_WINDOW_MS = 5000;
+
+/**
+ * Singleton manager for all AI provider child processes.
+ * Ensures proper cleanup on SIGINT/SIGTERM with graceful shutdown sequence.
+ *
+ * Features:
+ * - First SIGINT: Graceful shutdown (SIGTERM to children, wait 5s, then SIGKILL)
+ * - Second SIGINT (within 5s): Force-quit (immediate SIGKILL, exit code 1)
+ * - Exit code 130 for SIGINT (standard Unix convention: 128 + 2)
+ * - Automatic child cleanup via event listeners
+ * - Cleanup callbacks for spinners and temp resources
+ */
+export class ProcessManager {
+  private static instance: ProcessManager | null = null;
+
+  /** All active AI child processes */
+  private children = new Set<ChildProcess>();
+
+  /** Cleanup callbacks (for stopping spinners, removing temp files) */
+  private cleanupCallbacks = new Set<() => void>();
+
+  /** Whether we're currently shutting down */
+  private exiting = false;
+
+  /** Whether signal handlers have been installed */
+  private handlersInstalled = false;
+
+  /** Timestamp of first SIGINT (for double-signal detection) */
+  private firstSigintAt: number | null = null;
+
+  private constructor() {
+    // Private constructor for singleton
+  }
+
+  /**
+   * Get the singleton instance.
+   */
+  public static getInstance(): ProcessManager {
+    ProcessManager.instance ??= new ProcessManager();
+    return ProcessManager.instance;
+  }
+
+  /**
+   * Reset the singleton for testing.
+   * @internal
+   */
+  public static resetForTesting(): void {
+    if (ProcessManager.instance) {
+      ProcessManager.instance.dispose();
+      ProcessManager.instance = null;
+    }
+  }
+
+  /**
+   * Register a child process for tracking.
+   * Automatically installs signal handlers on first registration.
+   * Throws an error if called during shutdown.
+   *
+   * @throws Error if called during shutdown
+   */
+  public registerChild(child: ChildProcess): void {
+    if (this.exiting) {
+      throw new Error('Cannot register child process during shutdown');
+    }
+
+    this.children.add(child);
+
+    // Auto-cleanup when child exits
+    child.once('close', () => {
+      this.children.delete(child);
+    });
+
+    // Install signal handlers on first child registration
+    if (!this.handlersInstalled) {
+      this.installSignalHandlers();
+      this.handlersInstalled = true;
+    }
+  }
+
+  /**
+   * Eagerly install signal handlers without requiring a child registration.
+   * Call this at the top of execution loops so Ctrl+C works even before
+   * the first AI process is spawned (e.g. while the spinner is visible).
+   * Idempotent — safe to call multiple times.
+   */
+  public ensureHandlers(): void {
+    if (!this.handlersInstalled) {
+      this.installSignalHandlers();
+      this.handlersInstalled = true;
+    }
+  }
+
+  /**
+   * Check if a shutdown is in progress.
+   * Used by execution loops to break immediately on Ctrl+C.
+   */
+  public isShuttingDown(): boolean {
+    return this.exiting;
+  }
+
+  /**
+   * Manually unregister a child process.
+   * Normally not needed - children auto-unregister via event listeners.
+   */
+  public unregisterChild(child: ChildProcess): void {
+    this.children.delete(child);
+  }
+
+  /**
+   * Register a cleanup callback (for spinners, temp files, etc.).
+   * Returns a deregister function.
+   */
+  public registerCleanup(callback: () => void): () => void {
+    this.cleanupCallbacks.add(callback);
+    return () => {
+      this.cleanupCallbacks.delete(callback);
+    };
+  }
+
+  /**
+   * Kill all tracked child processes with the given signal.
+   * Catches errors (ESRCH = already dead, EPERM = permission denied).
+   */
+  public killAll(signal: NodeJS.Signals): void {
+    for (const child of this.children) {
+      try {
+        child.kill(signal);
+      } catch (err) {
+        const error = err as NodeJS.ErrnoException;
+        if (error.code === 'ESRCH') {
+          // Process already dead - silently remove
+          this.children.delete(child);
+        } else if (error.code === 'EPERM') {
+          // Permission denied - log warning
+          console.warn(`Warning: Permission denied killing process ${String(child.pid)}`);
+        } else {
+          // Unknown error - log but continue
+          console.error(`Error killing process ${String(child.pid)}:`, error.message);
+        }
+      }
+    }
+  }
+
+  /**
+   * Graceful shutdown sequence:
+   * 1. Run all cleanup callbacks (stop spinners)
+   * 2. Send SIGINT to all children (what AI CLI processes expect)
+   * 3. Wait up to 5 seconds for children to exit
+   * 4. Send SIGKILL to any remaining children (force)
+   * 5. Exit with code 130 (SIGINT) or 1 (force-quit)
+   *
+   * Double Ctrl+C: immediate SIGKILL + exit(1)
+   */
+  public async shutdown(signal: NodeJS.Signals): Promise<void> {
+    // Double-signal force-quit check MUST run before the exiting guard,
+    // otherwise the second Ctrl+C is swallowed and force-quit never fires.
+    if (signal === 'SIGINT' && this.firstSigintAt) {
+      const now = Date.now();
+      if (now - this.firstSigintAt < FORCE_QUIT_WINDOW_MS) {
+        console.log('\n\nForce quit (double signal) — killing all processes immediately...');
+        this.killAll('SIGKILL');
+        process.exit(1);
+        return;
+      }
+    }
+
+    if (this.exiting) {
+      return; // Already shutting down (non-SIGINT duplicate)
+    }
+
+    this.exiting = true;
+
+    // Record timestamp for double-signal detection
+    if (signal === 'SIGINT') {
+      this.firstSigintAt = Date.now();
+    }
+
+    console.log('\n\nShutting down gracefully... (press Ctrl+C again to force-quit)');
+
+    // Run cleanup callbacks
+    for (const callback of this.cleanupCallbacks) {
+      try {
+        callback();
+      } catch (err) {
+        const error = err as Error;
+        console.error('Error in cleanup callback:', error.message);
+      }
+    }
+    this.cleanupCallbacks.clear();
+
+    // Send SIGINT to children — claude CLI handles SIGINT for graceful shutdown.
+    // SIGTERM may be ignored by some child process trees.
+    this.killAll('SIGINT');
+
+    // Wait for children to exit (with timeout)
+    const waitStart = Date.now();
+    while (this.children.size > 0 && Date.now() - waitStart < GRACEFUL_SHUTDOWN_TIMEOUT_MS) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+
+    // Force-kill any remaining children
+    if (this.children.size > 0) {
+      console.log(`Force-killing ${String(this.children.size)} remaining process(es)...`);
+      this.killAll('SIGKILL');
+    }
+
+    // Exit with appropriate code
+    process.exit(signal === 'SIGINT' ? EXIT_INTERRUPTED : 1);
+  }
+
+  /**
+   * Clean up all resources (for testing).
+   * @internal
+   */
+  public dispose(): void {
+    this.children.clear();
+    this.cleanupCallbacks.clear();
+    this.exiting = false;
+    this.handlersInstalled = false;
+    this.firstSigintAt = null;
+  }
+
+  /**
+   * Install signal handlers for SIGINT and SIGTERM.
+   * Uses process.on() (persistent) not process.once() (one-shot).
+   */
+  private installSignalHandlers(): void {
+    process.on('SIGINT', () => {
+      void this.shutdown('SIGINT');
+    });
+
+    process.on('SIGTERM', () => {
+      void this.shutdown('SIGTERM');
+    });
+  }
+}

package/src/ai/prompts/ideate-auto.md

@@ -0,0 +1,144 @@
+# Autonomous Ideation to Implementation
+
+You are a combined requirements analyst and task planner working autonomously. Your goal is to turn a rough idea into
+refined requirements and a dependency-ordered set of implementation tasks. Make all decisions based on the idea
+description and codebase analysis — there is no user to interact with.
+
+## Two-Phase Protocol
+
+### Phase 1: Refine Requirements (WHAT)
+
+Analyze the idea and produce complete, implementation-agnostic requirements:
+
+- **Problem statement** — What problem are we solving and for whom?
+- **Functional requirements** — What should the system do? (behavior, not implementation)
+- **Acceptance criteria** — Testable conditions (Given/When/Then format preferred)
+- **Scope boundaries** — What's in vs out of scope
+- **Constraints** — Performance, compatibility, business rules if applicable
+
+**Output format:**
+
+```markdown
+## Problem
+
+[Clear problem statement]
+
+## Requirements
+
+- [Functional requirement 1]
+- [Functional requirement 2]
+
+## Acceptance Criteria
+
+- Given [precondition], When [action], Then [expected result]
+- [Additional criteria...]
+
+## Scope
+
+**In scope:**
+
+- [What's included]
+
+**Out of scope:**
+
+- [What's explicitly excluded or deferred]
+
+## Constraints
+
+- [Business/technical constraints if any]
+```
+
+### Phase 2: Plan Implementation (HOW)
+
+Explore the selected repositories and produce implementation tasks:
+
+1. **Explore codebase** — Read CLAUDE.md (if exists), understand project structure, find patterns
+2. **Map requirements to implementation** — Determine which parts map to which repository
+3. **Create tasks** — Following the Planning Common Context guidelines below
+4. **Validate** — Ensure tasks are non-overlapping, properly ordered, and completable
+
+## Idea to Implement
+
+**Title:** {{IDEA_TITLE}}
+
+**Project:** {{PROJECT_NAME}}
+
+**Description:**
+
+{{IDEA_DESCRIPTION}}
+
+## Selected Repositories
+
+You have access to these repositories:
+
+{{REPOSITORIES}}
+
+## Planning Common Context
+
+{{COMMON}}
+
+## Pre-Output Validation
+
+Before outputting JSON, verify:
+
+1. **Requirements complete** — Problem statement, acceptance criteria, and scope boundaries are all present
+2. **No file overlap** — No two tasks modify the same files (or overlap is delineated in steps)
+3. **Correct order** — Foundations before dependents, all `blockedBy` references point to earlier tasks
+4. **Maximized parallelism** — Independent tasks do NOT block each other unnecessarily
+5. **Precise steps** — Every task has 3+ specific, actionable steps with file references
+6. **Verification steps** — Every task ends with project-appropriate verification commands
+7. **projectPath assigned** — Every task uses a path from the Selected Repositories
+
+If you cannot produce a valid plan, signal: `<planning-blocked>reason</planning-blocked>`
+
+## Output Format
+
+Output a single JSON object with both requirements and tasks.
+If you cannot produce a valid plan, output `<planning-blocked>reason</planning-blocked>` instead of JSON.
+
+```json
+{{SCHEMA}}
+```
+
+**Requirements:**
+
+- Complete markdown string with the structure shown in Phase 1
+- Implementation-agnostic (WHAT, not HOW)
+- Clear acceptance criteria
+
+**Tasks:**
+
+- Each task has `id`, `name`, `projectPath`, `steps`, and optional `blockedBy`
+- `projectPath` must be one of the Selected Repositories paths
+- Steps reference actual files discovered during exploration
+- Verification steps use commands from CLAUDE.md if available
+- Tasks properly ordered by dependencies
+
+**Example:**
+
+```json
+{
+  "requirements": "## Problem\n\nUsers cannot filter exports by date range...\n\n## Requirements\n\n- Support optional start/end date query parameters...\n\n## Acceptance Criteria\n\n- Given valid ISO dates, When GET /exports?startDate=...&endDate=..., Then only matching exports returned\n\n## Scope\n\n**In scope:** Date filtering on export endpoint\n**Out of scope:** Date filtering on other endpoints\n\n## Constraints\n\n- Must use ISO8601 date format",
+  "tasks": [
+    {
+      "id": "1",
+      "name": "Add date range validation schema and export filter",
+      "projectPath": "/Users/dev/my-app",
+      "steps": [
+        "Create src/schemas/date-range.ts with DateRangeSchema using Zod — validate ISO8601 format, ensure startDate <= endDate",
+        "Modify src/controllers/export.ts to accept optional startDate/endDate query params using DateRangeSchema",
+        "Update src/repositories/export.ts findExports() to add WHERE clause for date filtering",
+        "Add unit tests in src/schemas/__tests__/date-range.test.ts covering valid ranges, invalid formats, and reversed dates",
+        "Add integration test in src/controllers/__tests__/export.test.ts for filtered and unfiltered queries",
+        "Run pnpm typecheck && pnpm lint && pnpm test — all pass"
+      ],
+      "blockedBy": []
+    }
+  ]
+}
+```
+
+---
+
+Proceed autonomously: refine the idea into clear requirements, explore the codebase, then generate tasks. Output only
+the final JSON when complete.