speci 0.1.0

package/lib/copilot.ts

@@ -0,0 +1,229 @@
+/**
+ * Copilot CLI Wrapper Module
+ *
+ * Provides a clean interface for invoking GitHub Copilot CLI with:
+ * - Interactive mode (-i flag) for full terminal passthrough
+ * - One-shot mode (-p flag) for non-interactive agent execution
+ * - Retry logic with exponential backoff for transient failures
+ * - Proper stdio handling and process spawning
+ */
+
+import { spawn } from 'node:child_process';
+import type { SpeciConfig } from './config.js';
+import { resolveAgentPath } from './config.js';
+import { log } from './utils/logger.js';
+
+/**
+ * Options for building copilot CLI arguments
+ */
+export interface CopilotArgsOptions {
+  interactive: boolean;
+  prompt?: string;
+  agent?: string;
+  allowAll?: boolean;
+}
+
+/**
+ * Result of running an agent
+ */
+export interface AgentRunResult {
+  success: boolean;
+  exitCode: number;
+  error?: string;
+}
+
+/**
+ * Retry policy for transient failures
+ */
+interface RetryPolicy {
+  maxRetries: number;
+  baseDelay: number;
+  maxDelay: number;
+  retryableExitCodes: number[];
+}
+
+/**
+ * Default retry policy
+ */
+const DEFAULT_RETRY_POLICY: RetryPolicy = {
+  maxRetries: 3,
+  baseDelay: 1000,
+  maxDelay: 4000,
+  retryableExitCodes: [429], // Rate limit
+};
+
+/**
+ * Build copilot CLI arguments from config and options
+ *
+ * @param config - Speci configuration
+ * @param options - Argument building options
+ * @returns Array of CLI arguments
+ *
+ * @example
+ * ```typescript
+ * const args = buildCopilotArgs(config, { interactive: true });
+ * // Returns: ['-i', '--allow-all']
+ * ```
+ */
+export function buildCopilotArgs(
+  config: SpeciConfig,
+  options: CopilotArgsOptions
+): string[] {
+  const args: string[] = [];
+
+  // Mode flag
+  if (options.interactive) {
+    args.push('-i');
+  } else if (options.prompt) {
+    args.push('-p', options.prompt);
+  }
+
+  // Agent flag
+  if (options.agent) {
+    args.push(`--agent=${options.agent}`);
+  }
+
+  // Permission flag
+  const { permissions } = config.copilot;
+  if (permissions === 'allow-all') {
+    args.push('--allow-all');
+  } else if (permissions === 'yolo') {
+    args.push('--yolo');
+  }
+
+  // Model flag
+  if (config.copilot.model) {
+    args.push('--model', config.copilot.model);
+  }
+
+  // Extra flags
+  args.push(...config.copilot.extraFlags);
+
+  return args;
+}
+
+/**
+ * Spawn copilot CLI process
+ *
+ * @param args - CLI arguments
+ * @param options - Spawn options
+ * @returns Promise that resolves with exit code
+ * @throws {Error} If copilot process fails to spawn
+ */
+export async function spawnCopilot(
+  args: string[],
+  options: { inherit?: boolean; cwd?: string } = {}
+): Promise<number> {
+  const { inherit = true, cwd = process.cwd() } = options;
+
+  return new Promise((resolve, reject) => {
+    const child = spawn('copilot', args, {
+      stdio: inherit ? 'inherit' : 'pipe',
+      cwd,
+      env: process.env,
+      shell: false,
+    });
+
+    child.on('error', (err) => {
+      reject(err);
+    });
+
+    child.on('close', (code) => {
+      resolve(code ?? 1);
+    });
+  });
+}
+
+/**
+ * Sleep for specified milliseconds
+ *
+ * @param ms - Milliseconds to sleep
+ * @returns Promise that resolves after delay
+ */
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Run an agent with retry logic for transient failures
+ *
+ * @param config - Speci configuration
+ * @param agentName - Name of agent to run
+ * @param label - Human-readable label for logging
+ * @param policy - Retry policy (uses default if not specified)
+ * @returns Promise that resolves with agent run result
+ * @throws {Error} If agent file not found or execution fails
+ */
+export async function runAgent(
+  config: SpeciConfig,
+  agentName: string,
+  _label: string,
+  policy: RetryPolicy = DEFAULT_RETRY_POLICY
+): Promise<AgentRunResult> {
+  let lastError: Error | undefined;
+  let lastExitCode = 1;
+
+  for (let attempt = 0; attempt <= policy.maxRetries; attempt++) {
+    if (attempt > 0) {
+      const delay = Math.min(
+        policy.baseDelay * Math.pow(2, attempt - 1),
+        policy.maxDelay
+      );
+      log.warn(`Retry ${attempt}/${policy.maxRetries} after ${delay}ms...`);
+      await sleep(delay);
+    }
+
+    try {
+      const agentPath = resolveAgentPath(
+        config,
+        agentName as
+          | 'plan'
+          | 'task'
+          | 'refactor'
+          | 'impl'
+          | 'review'
+          | 'fix'
+          | 'tidy'
+      );
+      const args = buildCopilotArgs(config, {
+        interactive: true,
+        agent: agentPath,
+      });
+
+      log.debug(`Spawning copilot: copilot ${args.join(' ')}`);
+      const exitCode = await spawnCopilot(args);
+
+      if (exitCode === 0) {
+        return { success: true, exitCode: 0 };
+      }
+
+      lastExitCode = exitCode;
+
+      // Check if retryable
+      if (!policy.retryableExitCodes.includes(exitCode)) {
+        return {
+          success: false,
+          exitCode,
+          error: `Agent exited with code ${exitCode}`,
+        };
+      }
+    } catch (err) {
+      lastError = err as Error;
+
+      // ENOENT is not retryable
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        return {
+          success: false,
+          exitCode: 127,
+          error: 'Copilot CLI not found. Is it installed and in PATH?',
+        };
+      }
+    }
+  }
+
+  return {
+    success: false,
+    exitCode: lastExitCode,
+    error: lastError?.message ?? `Failed after ${policy.maxRetries} retries`,
+  };
+}

package/lib/errors.ts

@@ -0,0 +1,166 @@
+/**
+ * Error Codes Module
+ *
+ * Defines structured error codes with messages, causes, and solutions.
+ * Used for consistent error reporting across the CLI.
+ */
+
+/**
+ * Error code definition with diagnostic information
+ */
+export interface ErrorDefinition {
+  message: string;
+  cause: string;
+  solution: string;
+}
+
+/**
+ * All error codes used by speci CLI
+ *
+ * Error codes are grouped by category:
+ * - ERR-PRE-* : Prerequisite errors (missing dependencies, environment issues)
+ * - ERR-INP-* : Input errors (invalid arguments, missing files)
+ * - ERR-STA-* : State errors (lock conflicts, state parsing)
+ * - ERR-EXE-* : Execution errors (command failures, timeouts)
+ */
+export const ERROR_CODES: Record<string, ErrorDefinition> = {
+  // Prerequisite Errors (ERR-PRE-*)
+  'ERR-PRE-01': {
+    message: 'Copilot CLI is not installed',
+    cause: 'The copilot command was not found in PATH',
+    solution: 'Run: npm install -g @github/copilot',
+  },
+  'ERR-PRE-02': {
+    message: 'Copilot CLI is not authenticated',
+    cause: 'Copilot CLI requires authentication to function',
+    solution: 'Run /login in Copilot CLI or set GH_TOKEN environment variable',
+  },
+  'ERR-PRE-03': {
+    message: 'Not a git repository',
+    cause: 'Current directory is not inside a git repository',
+    solution: 'Run git init in your project root',
+  },
+  'ERR-PRE-04': {
+    message: 'Configuration file not found',
+    cause: 'speci.config.json does not exist in project',
+    solution: 'Run speci init to create configuration',
+  },
+  'ERR-PRE-05': {
+    message: 'PROGRESS.md file not found',
+    cause: 'Progress tracking file does not exist',
+    solution: 'Run speci init or create docs/PROGRESS.md manually',
+  },
+
+  // Input Errors (ERR-INP-*)
+  'ERR-INP-01': {
+    message: 'Required argument missing',
+    cause: 'A required command argument was not provided',
+    solution: 'Check command usage with --help',
+  },
+  'ERR-INP-02': {
+    message: 'Agent file not found',
+    cause: 'Specified agent file does not exist',
+    solution: 'Verify agent path or use bundled agents (set to null in config)',
+  },
+  'ERR-INP-03': {
+    message: 'Config file is malformed',
+    cause: 'speci.config.json contains invalid JSON syntax',
+    solution: 'Fix JSON syntax errors in speci.config.json',
+  },
+  'ERR-INP-04': {
+    message: 'Config validation failed',
+    cause: 'Configuration does not match expected schema',
+    solution: 'Check config values against schema requirements',
+  },
+  'ERR-INP-05': {
+    message: 'Plan file not found',
+    cause: 'Specified plan file does not exist',
+    solution: 'Provide valid path with --plan option',
+  },
+
+  // State Errors (ERR-STA-*)
+  'ERR-STA-01': {
+    message: 'Lock file already exists',
+    cause: 'Another speci instance may be running',
+    solution: 'Wait for other instance to finish or use --force to override',
+  },
+  'ERR-STA-02': {
+    message: 'Cannot parse PROGRESS.md',
+    cause: 'Progress file format is invalid or corrupted',
+    solution: 'Verify PROGRESS.md follows expected markdown table format',
+  },
+  'ERR-STA-03': {
+    message: 'Invalid state transition',
+    cause: 'PROGRESS.md contains invalid or conflicting state markers',
+    solution: 'Check state markers (IN PROGRESS, IN REVIEW, COMPLETE, etc.)',
+  },
+
+  // Execution Errors (ERR-EXE-*)
+  'ERR-EXE-01': {
+    message: 'Gate command failed',
+    cause: 'One or more gate validation commands failed',
+    solution: 'Fix lint/typecheck/test errors reported in output',
+  },
+  'ERR-EXE-02': {
+    message: 'Copilot execution failed',
+    cause: 'Copilot CLI command exited with error',
+    solution: 'Check Copilot authentication and permissions',
+  },
+  'ERR-EXE-03': {
+    message: 'Max iterations reached',
+    cause: 'Loop reached maximum iteration limit',
+    solution: 'Review progress and increase --max-iterations if needed',
+  },
+  'ERR-EXE-04': {
+    message: 'Max fix attempts exceeded',
+    cause: 'Gate validation failed after maximum fix attempts',
+    solution: 'Review gate failures and fix issues manually',
+  },
+};
+
+/**
+ * Get error definition by code
+ *
+ * @param code - Error code (e.g., 'ERR-PRE-01')
+ * @returns Error definition or undefined if code not found
+ */
+export function getErrorDefinition(code: string): ErrorDefinition | undefined {
+  return ERROR_CODES[code];
+}
+
+/**
+ * Format error message with code, cause, and solution
+ *
+ * @param code - Error code
+ * @param context - Optional additional context
+ * @returns Formatted error message
+ */
+export function formatError(code: string, context?: string): string {
+  const def = getErrorDefinition(code);
+  if (!def) {
+    return `Unknown error code: ${code}`;
+  }
+
+  let message = `[${code}] ${def.message}`;
+  if (context) {
+    message += `\n  Context: ${context}`;
+  }
+  message += `\n  Cause: ${def.cause}`;
+  message += `\n  Solution: ${def.solution}`;
+
+  return message;
+}
+
+/**
+ * Create error with structured code and message
+ *
+ * @param code - Error code
+ * @param context - Optional additional context
+ * @returns Error object with formatted message
+ */
+export function createError(code: string, context?: string): Error {
+  const message = formatError(code, context);
+  const error = new Error(message);
+  error.name = code;
+  return error;
+}

package/lib/state.ts

@@ -0,0 +1,148 @@
+/**
+ * State Parser Module
+ *
+ * Reads and parses PROGRESS.md to determine the current loop state.
+ * Provides state detection and task statistics for orchestrator decision-making.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import type { SpeciConfig } from './config.js';
+
+/**
+ * State enum representing the current orchestration state
+ */
+export enum STATE {
+  WORK_LEFT = 'WORK_LEFT',
+  IN_REVIEW = 'IN_REVIEW',
+  BLOCKED = 'BLOCKED',
+  DONE = 'DONE',
+  NO_PROGRESS = 'NO_PROGRESS',
+}
+
+/**
+ * Task statistics interface
+ */
+export interface TaskStats {
+  total: number;
+  completed: number;
+  remaining: number;
+  inReview: number;
+  blocked: number;
+}
+
+// Pre-compile regex patterns at module load for performance
+const PATTERNS = {
+  BLOCKED: /TASK_\d+\s*\|.*BLOCKED/i,
+  IN_REVIEW: /TASK_\d+\s*\|.*IN.REVIEW/i,
+  WORK_LEFT: /TASK_\d+\s*\|.*(NOT STARTED|IN PROGRESS)/i,
+  TASK_ROW: /TASK_(\d+)\s*\|([^|]+)\|([^|]+)(?:\|([^|]+))?/i,
+} as const;
+
+// Priority order for state detection (highest to lowest)
+const STATE_PRIORITY: Array<{ state: STATE; pattern: RegExp }> = [
+  { state: STATE.BLOCKED, pattern: PATTERNS.BLOCKED },
+  { state: STATE.IN_REVIEW, pattern: PATTERNS.IN_REVIEW },
+  { state: STATE.WORK_LEFT, pattern: PATTERNS.WORK_LEFT },
+];
+
+/**
+ * Check if content matches a state pattern
+ * @param content - Content to check
+ * @param pattern - Regex pattern to test
+ * @returns true if pattern matches
+ */
+export function hasStatePattern(content: string, pattern: RegExp): boolean {
+  return pattern.test(content);
+}
+
+/**
+ * Get current orchestration state by parsing PROGRESS.md
+ *
+ * @param config - Speci configuration
+ * @returns Current STATE enum value
+ * @throws {Error} ERR-STA-02 if PROGRESS.md cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * const state = await getState(config);
+ * if (state === STATE.WORK_LEFT) {
+ *   // Start implementation
+ * }
+ * ```
+ */
+export async function getState(config: SpeciConfig): Promise<STATE> {
+  const progressPath = config.paths.progress;
+
+  // Check file existence
+  if (!existsSync(progressPath)) {
+    return STATE.NO_PROGRESS;
+  }
+
+  // Read file content
+  const content = await readFile(progressPath, 'utf8');
+
+  // Check patterns in priority order (early exit)
+  for (const { state, pattern } of STATE_PRIORITY) {
+    if (pattern.test(content)) {
+      return state;
+    }
+  }
+
+  // No incomplete tasks found
+  return STATE.DONE;
+}
+
+/**
+ * Get task statistics from PROGRESS.md
+ *
+ * @param config - Speci configuration
+ * @returns TaskStats object with counts
+ *
+ * @example
+ * ```typescript
+ * const stats = await getTaskStats(config);
+ * console.log(`${stats.completed}/${stats.total} tasks complete`);
+ * ```
+ */
+export async function getTaskStats(config: SpeciConfig): Promise<TaskStats> {
+  const progressPath = config.paths.progress;
+
+  if (!existsSync(progressPath)) {
+    return { total: 0, completed: 0, remaining: 0, inReview: 0, blocked: 0 };
+  }
+
+  const content = await readFile(progressPath, 'utf8');
+  const lines = content.split('\n');
+
+  const stats: TaskStats = {
+    total: 0,
+    completed: 0,
+    remaining: 0,
+    inReview: 0,
+    blocked: 0,
+  };
+
+  for (const line of lines) {
+    // Match task rows: | TASK_001 | Description | Status | or | TASK_001 | Title | Priority | Status |
+    const match = line.match(PATTERNS.TASK_ROW);
+    if (!match) continue;
+
+    stats.total++;
+
+    // Status is in the last captured group (either match[3] for 3 columns or match[4] for 4 columns)
+    const status = (match[4] || match[3]).trim().toUpperCase();
+
+    if (status === 'COMPLETE' || status === 'COMPLETED' || status === 'DONE') {
+      stats.completed++;
+    } else if (status === 'BLOCKED') {
+      stats.blocked++;
+    } else if (status === 'IN_REVIEW' || status === 'IN REVIEW') {
+      stats.inReview++;
+    } else if (status === 'NOT STARTED' || status === 'IN PROGRESS') {
+      stats.remaining++;
+    }
+  }
+
+  return stats;
+}

package/lib/ui/banner.ts

@@ -0,0 +1,109 @@
+/**
+ * ASCII Banner Module
+ *
+ * Renders the SPECI CLI brand banner with horizontal gradient effect.
+ * Uses Ice Blue color palette (sky-200 → sky-400 → sky-500) for visual appeal.
+ *
+ * The banner provides immediate brand recognition on CLI startup.
+ * Respects NO_COLOR and FORCE_COLOR environment variables.
+ */
+
+import { createRequire } from 'node:module';
+import { ANSI } from './palette.js';
+import { colorize, supportsColor } from './colors.js';
+
+// Use createRequire for reliable JSON imports in ESM (works in both runtime and tests)
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json') as { version: string };
+
+/** Package version from package.json */
+export const VERSION = pkg.version;
+
+/**
+ * ASCII art banner for SPECI CLI
+ * 6 lines tall, 40 characters wide
+ */
+export const BANNER_ART = [
+  '  ███████╗██████╗ ███████╗ ██████╗██╗',
+  '  ██╔════╝██╔══██╗██╔════╝██╔════╝██║',
+  '  ███████╗██████╔╝█████╗  ██║     ██║',
+  '  ╚════██║██╔═══╝ ██╔══╝  ██║     ██║',
+  '  ███████║██║     ███████╗╚██████╗██║',
+  '  ╚══════╝╚═╝     ╚══════╝ ╚═════╝╚═╝',
+] as const;
+
+/**
+ * Options for banner rendering
+ */
+export interface BannerOptions {
+  /**
+   * Include version number below banner
+   * @default true
+   */
+  showVersion?: boolean;
+}
+
+/**
+ * Apply horizontal gradient to a line of text
+ * Divides line into thirds: sky200 | sky400 | sky500
+ *
+ * @param line - Text line to apply gradient to
+ * @returns Gradient-colored line (or plain text if colors disabled)
+ */
+function applyGradient(line: string): string {
+  if (!supportsColor()) {
+    return line;
+  }
+
+  const len = line.length;
+  const third = Math.floor(len / 3);
+
+  const left = line.slice(0, third);
+  const middle = line.slice(third, third * 2);
+  const right = line.slice(third * 2);
+
+  return (
+    `${ANSI.sky200}${left}` +
+    `${ANSI.sky400}${middle}` +
+    `${ANSI.sky500}${right}${ANSI.reset}`
+  );
+}
+
+/**
+ * Render ASCII art banner with Ice Blue gradient
+ *
+ * Displays the SPECI logo with a horizontal gradient effect.
+ * Optionally includes version number centered below the banner.
+ *
+ * @param options - Render options
+ * @returns Formatted banner string ready for console output
+ *
+ * @example
+ * ```typescript
+ * // Render banner with version
+ * console.log(renderBanner());
+ *
+ * // Render banner without version
+ * console.log(renderBanner({ showVersion: false }));
+ * ```
+ */
+export function renderBanner(options: BannerOptions = {}): string {
+  const { showVersion = true } = options;
+
+  // Apply gradient to each line
+  const bannerLines = BANNER_ART.map((line) => applyGradient(line));
+
+  // Join banner lines
+  let output = bannerLines.join('\n');
+
+  // Add version if requested
+  if (showVersion) {
+    const versionText = `v${pkg.version}`;
+    const bannerWidth = BANNER_ART[0].length;
+    const padding = Math.floor((bannerWidth - versionText.length) / 2);
+    const centeredVersion = ' '.repeat(padding) + colorize(versionText, 'dim');
+    output += '\n' + centeredVersion;
+  }
+
+  return output;
+}