ralphctl 0.1.0 → 0.1.2

package/src/ai/lifecycle.ts

@@ -1,45 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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

@@ -1,207 +0,0 @@
-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

@@ -1,248 +0,0 @@
-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/index.ts

@@ -1,89 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-function loadTemplate(name: string): string {
-  return readFileSync(join(__dirname, `${name}.md`), 'utf-8');
-}
-
-function buildPlanPrompt(template: string, context: string, schema: string): string {
-  const common = loadTemplate('plan-common');
-  return template.replace('{{COMMON}}', common).replace('{{CONTEXT}}', context).replace('{{SCHEMA}}', schema);
-}
-
-export function buildInteractivePrompt(context: string, outputFile: string, schema: string): string {
-  const template = loadTemplate('plan-interactive');
-  return buildPlanPrompt(template, context, schema).replace('{{OUTPUT_FILE}}', outputFile);
-}
-
-export function buildAutoPrompt(context: string, schema: string): string {
-  const template = loadTemplate('plan-auto');
-  return buildPlanPrompt(template, context, schema);
-}
-
-export function buildTaskExecutionPrompt(progressFilePath: string, noCommit: boolean, contextFileName: string): string {
-  const template = loadTemplate('task-execution');
-  const commitStep = noCommit
-    ? ''
-    : '\n> **Before continuing:** Create a git commit with a descriptive message for the changes made.\n';
-  const commitConstraint = noCommit ? '' : '- **Must commit** — Create a git commit before signaling completion.\n';
-  return template
-    .replace('{{PROGRESS_FILE}}', progressFilePath)
-    .replace('{{COMMIT_STEP}}', commitStep)
-    .replace('{{COMMIT_CONSTRAINT}}', commitConstraint)
-    .replaceAll('{{CONTEXT_FILE}}', contextFileName);
-}
-
-export function buildTicketRefinePrompt(
-  ticketContent: string,
-  outputFile: string,
-  schema: string,
-  issueContext = ''
-): string {
-  const template = loadTemplate('ticket-refine');
-  return template
-    .replace('{{TICKET}}', ticketContent)
-    .replace('{{OUTPUT_FILE}}', outputFile)
-    .replace('{{SCHEMA}}', schema)
-    .replace('{{ISSUE_CONTEXT}}', issueContext);
-}
-
-export function buildIdeatePrompt(
-  ideaTitle: string,
-  ideaDescription: string,
-  projectName: string,
-  repositories: string,
-  outputFile: string,
-  schema: string
-): string {
-  const template = loadTemplate('ideate');
-  const common = loadTemplate('plan-common');
-  return template
-    .replace('{{IDEA_TITLE}}', ideaTitle)
-    .replace('{{IDEA_DESCRIPTION}}', ideaDescription)
-    .replace('{{PROJECT_NAME}}', projectName)
-    .replace('{{REPOSITORIES}}', repositories)
-    .replace('{{OUTPUT_FILE}}', outputFile)
-    .replace('{{SCHEMA}}', schema)
-    .replace('{{COMMON}}', common);
-}
-
-export function buildIdeateAutoPrompt(
-  ideaTitle: string,
-  ideaDescription: string,
-  projectName: string,
-  repositories: string,
-  schema: string
-): string {
-  const template = loadTemplate('ideate-auto');
-  const common = loadTemplate('plan-common');
-  return template
-    .replace('{{IDEA_TITLE}}', ideaTitle)
-    .replace('{{IDEA_DESCRIPTION}}', ideaDescription)
-    .replace('{{PROJECT_NAME}}', projectName)
-    .replace('{{REPOSITORIES}}', repositories)
-    .replace('{{SCHEMA}}', schema)
-    .replace('{{COMMON}}', common);
-}