wiggum-cli 0.1.0

package/src/commands/new.ts

@@ -0,0 +1,312 @@
+/**
+ * New Command
+ * Create a new feature specification from template
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { logger } from '../utils/logger.js';
+import { loadConfigWithDefaults, hasConfig } from '../utils/config.js';
+import pc from 'picocolors';
+import * as prompts from '@clack/prompts';
+
+export interface NewOptions {
+  /** Open in editor after creation */
+  edit?: boolean;
+  /** Editor to use (defaults to $EDITOR or 'code') */
+  editor?: string;
+  /** Skip confirmation */
+  yes?: boolean;
+  /** Force overwrite if file exists */
+  force?: boolean;
+}
+
+/**
+ * Default spec template content
+ */
+const DEFAULT_SPEC_TEMPLATE = `# {{feature}} Feature Specification
+
+**Status:** Planned
+**Version:** 1.0
+**Last Updated:** {{date}}
+
+## Purpose
+
+Describe what this feature does and why it's needed.
+
+## User Stories
+
+- As a user, I want [action] so that [benefit]
+- As an admin, I want [action] so that [benefit]
+
+## Requirements
+
+### Functional Requirements
+- [ ] Requirement 1 - Description of what the system must do
+- [ ] Requirement 2 - Another functional requirement
+
+### Non-Functional Requirements
+- [ ] Performance: [target metrics]
+- [ ] Security: [security considerations]
+- [ ] Accessibility: [WCAG level]
+
+## Technical Notes
+
+- **Uses:** Existing patterns or components to leverage
+- **Location:** Where the code should live
+- **Dependencies:** External libraries or APIs needed
+- **Database:** Schema changes required (if any)
+
+## Visual Requirements
+
+(For UI features - delete this section if backend-only)
+
+- **Layout:** Describe the layout structure and responsive behavior
+- **Components:** List the UI components needed
+- **States:**
+  - Empty: What to show when there's no data
+  - Loading: Skeleton or spinner pattern
+  - Error: How to display errors
+- **Mobile:** How the layout adapts on small screens
+
+## API Endpoints
+
+(If applicable)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | \`/api/{{feature}}\` | Fetch data |
+| POST | \`/api/{{feature}}\` | Create new |
+
+## Acceptance Criteria
+
+- [ ] Criteria 1 - Specific, testable condition
+- [ ] Criteria 2 - Another acceptance criterion
+- [ ] Criteria 3 - E2E testable scenario
+
+## Out of Scope
+
+- Feature X (planned for future iteration)
+- Integration Y (separate spec)
+
+## Open Questions
+
+- [ ] Question 1 - Decision needed
+- [ ] Question 2 - Clarification required
+`;
+
+/**
+ * Find the _example.md template
+ */
+async function findExampleTemplate(projectRoot: string): Promise<string | null> {
+  const config = await loadConfigWithDefaults(projectRoot);
+  const specsDir = config.paths.specs;
+
+  // Check multiple locations
+  const possiblePaths = [
+    join(projectRoot, specsDir, '_example.md'),
+    join(projectRoot, '.ralph', 'specs', '_example.md'),
+    join(projectRoot, 'specs', '_example.md'),
+  ];
+
+  for (const templatePath of possiblePaths) {
+    if (existsSync(templatePath)) {
+      return templatePath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get template directory from the package
+ */
+function getPackageTemplateDir(): string {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+  // Go up from commands/ to src/ or dist/, then to templates/
+  return join(__dirname, '..', 'templates', 'specs');
+}
+
+/**
+ * Process template variables
+ */
+function processTemplate(template: string, feature: string): string {
+  const date = new Date().toISOString().split('T')[0];
+  const featureTitle = feature
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+
+  return template
+    .replace(/\{\{feature\}\}/g, feature)
+    .replace(/\{\{featureTitle\}\}/g, featureTitle)
+    .replace(/\{\{date\}\}/g, date)
+    .replace(/YYYY-MM-DD/g, date);
+}
+
+/**
+ * Open file in editor
+ */
+function openInEditor(filePath: string, editor?: string): void {
+  const editorCmd = editor || process.env.EDITOR || 'code';
+
+  logger.info(`Opening in editor: ${editorCmd}`);
+
+  const child = spawn(editorCmd, [filePath], {
+    detached: true,
+    stdio: 'ignore',
+  });
+
+  child.unref();
+}
+
+/**
+ * Create a new feature specification
+ */
+export async function newCommand(feature: string, options: NewOptions = {}): Promise<void> {
+  const projectRoot = process.cwd();
+
+  // Validate feature name
+  if (!feature || typeof feature !== 'string') {
+    logger.error('Feature name is required');
+    process.exit(1);
+  }
+
+  // Sanitize feature name (allow alphanumeric, hyphens, underscores)
+  if (!/^[a-zA-Z0-9_-]+$/.test(feature)) {
+    logger.error('Feature name must contain only letters, numbers, hyphens, and underscores');
+    logger.info('Example: ralph new my-feature or ralph new user_auth');
+    process.exit(1);
+  }
+
+  // Check for reserved names
+  const reservedNames = ['_example', '_template', 'config', 'ralph'];
+  if (reservedNames.includes(feature.toLowerCase())) {
+    logger.error(`"${feature}" is a reserved name. Please choose a different feature name.`);
+    process.exit(1);
+  }
+
+  logger.info(`Creating new feature spec: ${pc.bold(feature)}`);
+  console.log('');
+
+  // Check for config
+  if (!hasConfig(projectRoot)) {
+    logger.warn('No ralph.config.js found. Run "ralph init" first to configure your project.');
+    logger.info('Using default paths...');
+    console.log('');
+  }
+
+  // Load config
+  const config = await loadConfigWithDefaults(projectRoot);
+  const specsDir = join(projectRoot, config.paths.specs);
+
+  // Create specs directory if it doesn't exist
+  if (!existsSync(specsDir)) {
+    logger.info(`Creating specs directory: ${specsDir}`);
+    mkdirSync(specsDir, { recursive: true });
+  }
+
+  // Check if spec already exists
+  const specPath = join(specsDir, `${feature}.md`);
+  if (existsSync(specPath)) {
+    if (!options.force) {
+      logger.error(`Spec file already exists: ${specPath}`);
+
+      if (!options.yes) {
+        const shouldOverwrite = await prompts.confirm({
+          message: 'Do you want to overwrite the existing spec?',
+          initialValue: false,
+        });
+
+        if (prompts.isCancel(shouldOverwrite) || !shouldOverwrite) {
+          logger.info('Cancelled');
+          return;
+        }
+      } else {
+        logger.info('Use --force to overwrite');
+        return;
+      }
+    }
+
+    logger.warn('Overwriting existing spec file');
+  }
+
+  // Find or use default template
+  let templateContent: string;
+
+  // Try to find _example.md template
+  const exampleTemplate = await findExampleTemplate(projectRoot);
+  if (exampleTemplate) {
+    logger.info(`Using template: ${exampleTemplate}`);
+    templateContent = readFileSync(exampleTemplate, 'utf-8');
+  } else {
+    // Try package template
+    const packageTemplateDir = getPackageTemplateDir();
+    const packageTemplate = join(packageTemplateDir, '_example.md.tmpl');
+    if (existsSync(packageTemplate)) {
+      logger.info(`Using package template`);
+      templateContent = readFileSync(packageTemplate, 'utf-8');
+    } else {
+      // Use default template
+      logger.info('Using default template');
+      templateContent = DEFAULT_SPEC_TEMPLATE;
+    }
+  }
+
+  // Process template
+  const specContent = processTemplate(templateContent, feature);
+
+  // Confirm with user (unless --yes)
+  if (!options.yes) {
+    console.log('');
+    console.log(pc.cyan('--- Spec Preview ---'));
+    console.log(`File: ${specPath}`);
+    console.log('');
+
+    // Show first few lines of the processed template
+    const previewLines = specContent.split('\n').slice(0, 15);
+    console.log(pc.dim(previewLines.join('\n')));
+    if (specContent.split('\n').length > 15) {
+      console.log(pc.dim('...'));
+    }
+    console.log('');
+
+    const shouldCreate = await prompts.confirm({
+      message: 'Create this spec file?',
+      initialValue: true,
+    });
+
+    if (prompts.isCancel(shouldCreate) || !shouldCreate) {
+      logger.info('Cancelled');
+      return;
+    }
+  }
+
+  // Write the spec file
+  try {
+    writeFileSync(specPath, specContent, 'utf-8');
+    logger.success(`Created spec: ${specPath}`);
+  } catch (error) {
+    logger.error(`Failed to create spec: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+
+  // Open in editor if requested
+  if (options.edit) {
+    try {
+      openInEditor(specPath, options.editor);
+    } catch (error) {
+      logger.warn(`Could not open editor: ${error instanceof Error ? error.message : String(error)}`);
+      logger.info(`Manually open: ${specPath}`);
+    }
+  }
+
+  // Display next steps
+  console.log('');
+  console.log('Next steps:');
+  console.log(`  1. Edit the spec: ${pc.cyan(`$EDITOR ${specPath}`)}`);
+  console.log(`  2. When ready, run: ${pc.cyan(`ralph run ${feature}`)}`);
+}

package/src/commands/run.ts

@@ -0,0 +1,214 @@
+/**
+ * Run Command
+ * Executes the feature development loop for a specific feature
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { logger } from '../utils/logger.js';
+import {
+  loadConfigWithDefaults,
+  hasConfig,
+  type RalphConfig,
+} from '../utils/config.js';
+import pc from 'picocolors';
+
+export interface RunOptions {
+  worktree?: boolean;
+  resume?: boolean;
+  model?: string;
+  maxIterations?: number;
+  maxE2eAttempts?: number;
+}
+
+/**
+ * Find the feature-loop.sh script
+ * Checks: 1) .ralph/scripts/ 2) ralph/ (parent ralph repo)
+ */
+function findFeatureLoopScript(projectRoot: string): string | null {
+  // Check .ralph/scripts first
+  const localScript = join(projectRoot, '.ralph', 'scripts', 'feature-loop.sh');
+  if (existsSync(localScript)) {
+    return localScript;
+  }
+
+  // Check for ralph directory as sibling (development setup)
+  const siblingRalph = join(projectRoot, '..', 'ralph', 'feature-loop.sh');
+  if (existsSync(siblingRalph)) {
+    return siblingRalph;
+  }
+
+  // Check for ralph directory as parent (when running from within ralph-cli)
+  const parentRalph = join(projectRoot, 'feature-loop.sh');
+  if (existsSync(parentRalph)) {
+    return parentRalph;
+  }
+
+  return null;
+}
+
+/**
+ * Validate that the spec file exists
+ */
+async function validateSpecFile(projectRoot: string, feature: string): Promise<string | null> {
+  const config = await loadConfigWithDefaults(projectRoot);
+  const specsDir = config.paths.specs;
+
+  // Check various possible spec locations
+  const possiblePaths = [
+    join(projectRoot, specsDir, `${feature}.md`),
+    join(projectRoot, '.ralph', 'specs', `${feature}.md`),
+    join(projectRoot, 'specs', `${feature}.md`),
+  ];
+
+  for (const specPath of possiblePaths) {
+    if (existsSync(specPath)) {
+      return specPath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Run the feature development loop for a specific feature
+ */
+export async function runCommand(feature: string, options: RunOptions = {}): Promise<void> {
+  const projectRoot = process.cwd();
+
+  // Validate feature name
+  if (!feature || typeof feature !== 'string') {
+    logger.error('Feature name is required');
+    process.exit(1);
+  }
+
+  // Sanitize feature name (allow alphanumeric, hyphens, underscores)
+  if (!/^[a-zA-Z0-9_-]+$/.test(feature)) {
+    logger.error('Feature name must contain only letters, numbers, hyphens, and underscores');
+    process.exit(1);
+  }
+
+  logger.info(`Running feature loop for: ${pc.bold(feature)}`);
+  console.log('');
+
+  // Check for config
+  if (!hasConfig(projectRoot)) {
+    logger.warn('No ralph.config.js found. Run "ralph init" first to configure your project.');
+    logger.info('Attempting to run with default settings...');
+    console.log('');
+  }
+
+  // Load config
+  const config = await loadConfigWithDefaults(projectRoot);
+
+  // Validate spec file exists
+  const specFile = await validateSpecFile(projectRoot, feature);
+  if (!specFile) {
+    logger.error(`Spec file not found: ${feature}.md`);
+    logger.info(`Create the spec first: ralph new ${feature}`);
+    logger.info(`Expected location: ${join(projectRoot, config.paths.specs, `${feature}.md`)}`);
+    process.exit(1);
+  }
+
+  logger.info(`Found spec: ${specFile}`);
+
+  // Find the feature-loop.sh script
+  const scriptPath = findFeatureLoopScript(projectRoot);
+  if (!scriptPath) {
+    logger.error('feature-loop.sh script not found');
+    logger.info('The script should be in .ralph/scripts/ or the ralph/ directory');
+    logger.info('Run "ralph init" to generate the necessary scripts');
+    process.exit(1);
+  }
+
+  logger.info(`Using script: ${scriptPath}`);
+  console.log('');
+
+  // Build command arguments
+  const args: string[] = [feature];
+
+  // Add max iterations
+  const maxIterations = options.maxIterations ?? config.loop.maxIterations;
+  args.push(String(maxIterations));
+
+  // Add max E2E attempts
+  const maxE2eAttempts = options.maxE2eAttempts ?? config.loop.maxE2eAttempts;
+  args.push(String(maxE2eAttempts));
+
+  // Add flags
+  if (options.worktree) {
+    args.push('--worktree');
+  }
+
+  if (options.resume) {
+    args.push('--resume');
+  }
+
+  if (options.model) {
+    args.push('--model', options.model);
+  }
+
+  // Display configuration
+  console.log(pc.cyan('--- Run Configuration ---'));
+  console.log(`  Feature: ${pc.bold(feature)}`);
+  console.log(`  Spec: ${specFile}`);
+  console.log(`  Max Iterations: ${maxIterations}`);
+  console.log(`  Max E2E Attempts: ${maxE2eAttempts}`);
+  console.log(`  Model: ${options.model || config.loop.defaultModel}`);
+  console.log(`  Worktree: ${options.worktree ? 'enabled' : 'disabled'}`);
+  console.log(`  Resume: ${options.resume ? 'enabled' : 'disabled'}`);
+  console.log('');
+
+  // Execute the feature-loop.sh script
+  logger.info('Starting feature loop...');
+  console.log('');
+
+  const scriptDir = dirname(scriptPath);
+
+  return new Promise((resolve, reject) => {
+    try {
+      const child = spawn('bash', [scriptPath, ...args], {
+        cwd: scriptDir,
+        stdio: 'inherit',
+        env: {
+          ...process.env,
+          // Pass config paths to script
+          RALPH_CONFIG_ROOT: config.paths.root,
+          RALPH_SPEC_DIR: config.paths.specs,
+          RALPH_SCRIPTS_DIR: config.paths.scripts,
+        },
+      });
+
+      child.on('error', (error) => {
+        logger.error(`Failed to start feature loop: ${error.message}`);
+        if (process.env.DEBUG) {
+          console.error(error.stack);
+        }
+        reject(error);
+      });
+
+      child.on('close', (code) => {
+        console.log('');
+        if (code === 0) {
+          logger.success('Feature loop completed successfully!');
+          resolve();
+        } else if (code === 130) {
+          // SIGINT (Ctrl+C)
+          logger.info('Feature loop interrupted by user');
+          resolve();
+        } else {
+          logger.error(`Feature loop exited with code: ${code}`);
+          logger.info('Use --resume to continue from where you left off');
+          reject(new Error(`Feature loop exited with code: ${code || 1}`));
+        }
+      });
+    } catch (error) {
+      logger.error(`Unexpected error starting feature loop: ${error instanceof Error ? error.message : String(error)}`);
+      if (process.env.DEBUG && error instanceof Error) {
+        console.error(error.stack);
+      }
+      reject(error);
+    }
+  });
+}

package/src/generator/config.ts

@@ -0,0 +1,116 @@
+/**
+ * Config Generator
+ * Generates ralph.config.js file from scan results
+ */
+
+import type { ScanResult } from '../scanner/types.js';
+import { extractVariables, type TemplateVariables } from './templates.js';
+
+/**
+ * Ralph configuration structure
+ */
+export interface RalphConfig {
+  name: string;
+  stack: {
+    framework: {
+      name: string;
+      version: string;
+      variant: string;
+    };
+    packageManager: string;
+    testing: {
+      unit: string;
+      e2e: string;
+    };
+    styling: string;
+  };
+  commands: {
+    dev: string;
+    build: string;
+    test: string;
+    lint: string;
+    typecheck: string;
+  };
+  paths: {
+    root: string;
+    prompts: string;
+    guides: string;
+    specs: string;
+    scripts: string;
+    learnings: string;
+    agents: string;
+  };
+  loop: {
+    maxIterations: number;
+    maxE2eAttempts: number;
+    defaultModel: string;
+    planningModel: string;
+  };
+}
+
+/**
+ * Generate ralph config object from scan result
+ */
+export function generateConfig(scanResult: ScanResult, customVars: Record<string, string> = {}): RalphConfig {
+  const vars = extractVariables(scanResult, customVars);
+
+  return {
+    name: vars.projectName,
+    stack: {
+      framework: {
+        name: vars.framework,
+        version: vars.frameworkVersion,
+        variant: vars.frameworkVariant,
+      },
+      packageManager: vars.packageManager,
+      testing: {
+        unit: vars.unitTest,
+        e2e: vars.e2eTest,
+      },
+      styling: vars.styling,
+    },
+    commands: {
+      dev: vars.devCommand,
+      build: vars.buildCommand,
+      test: vars.testCommand,
+      lint: vars.lintCommand,
+      typecheck: vars.typecheckCommand,
+    },
+    paths: {
+      root: '.ralph',
+      prompts: '.ralph/prompts',
+      guides: '.ralph/guides',
+      specs: '.ralph/specs',
+      scripts: '.ralph/scripts',
+      learnings: '.ralph/LEARNINGS.md',
+      agents: '.ralph/AGENTS.md',
+    },
+    loop: {
+      maxIterations: 10,
+      maxE2eAttempts: 5,
+      defaultModel: 'sonnet',
+      planningModel: 'opus',
+    },
+  };
+}
+
+/**
+ * Generate ralph.config.js file content as JavaScript module
+ */
+export function generateConfigFile(config: RalphConfig): string {
+  const content = `module.exports = ${JSON.stringify(config, null, 2)};
+`;
+
+  // Fix JSON to valid JS (unquote keys)
+  return content
+    .replace(/"(\w+)":/g, '$1:')
+    .replace(/: "([^"]+)"/g, ": '$1'");
+}
+
+/**
+ * Generate ralph.config.js from scan result
+ */
+export function generateConfigFileFromScan(scanResult: ScanResult, customVars: Record<string, string> = {}): string {
+  const config = generateConfig(scanResult, customVars);
+  return generateConfigFile(config);
+}