wiggum-cli 0.1.0

package/src/generator/writer.ts

@@ -0,0 +1,293 @@
+/**
+ * File Writer
+ * Creates .ralph directory structure and writes processed templates
+ */
+
+import { mkdir, writeFile, readFile, copyFile, stat, rename, readdir } from 'node:fs/promises';
+import { join, dirname, basename } from 'node:path';
+import { existsSync } from 'node:fs';
+
+/**
+ * Options for file writing
+ */
+export interface WriteOptions {
+  /** How to handle existing files: 'backup', 'skip', 'overwrite' */
+  existingFiles: 'backup' | 'skip' | 'overwrite';
+  /** Whether to create backup files */
+  createBackups: boolean;
+  /** Verbose output */
+  verbose: boolean;
+}
+
+/**
+ * Default write options
+ */
+export const DEFAULT_WRITE_OPTIONS: WriteOptions = {
+  existingFiles: 'backup',
+  createBackups: true,
+  verbose: false,
+};
+
+/**
+ * Result of a write operation
+ */
+export interface WriteResult {
+  /** Path that was written */
+  path: string;
+  /** Whether the write was successful */
+  success: boolean;
+  /** Action taken: created, backed_up, skipped, overwritten */
+  action: 'created' | 'backed_up' | 'skipped' | 'overwritten' | 'error';
+  /** Error message if any */
+  error?: string;
+  /** Backup path if created */
+  backupPath?: string;
+}
+
+/**
+ * Summary of all write operations
+ */
+export interface WriteSummary {
+  /** Total files processed */
+  total: number;
+  /** Files created (new) */
+  created: number;
+  /** Files backed up and replaced */
+  backedUp: number;
+  /** Files skipped (already existed) */
+  skipped: number;
+  /** Files overwritten */
+  overwritten: number;
+  /** Files that failed */
+  errors: number;
+  /** Individual results */
+  results: WriteResult[];
+}
+
+/**
+ * Create a directory and all parent directories
+ */
+export async function ensureDir(dirPath: string): Promise<void> {
+  await mkdir(dirPath, { recursive: true });
+}
+
+/**
+ * Check if a file exists
+ */
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create a backup of an existing file
+ */
+export async function backupFile(filePath: string): Promise<string> {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const dir = dirname(filePath);
+  const name = basename(filePath);
+  const backupPath = join(dir, `.${name}.backup-${timestamp}`);
+
+  await copyFile(filePath, backupPath);
+  return backupPath;
+}
+
+/**
+ * Write a single file with options
+ */
+export async function writeFileWithOptions(
+  filePath: string,
+  content: string,
+  options: WriteOptions = DEFAULT_WRITE_OPTIONS
+): Promise<WriteResult> {
+  const result: WriteResult = {
+    path: filePath,
+    success: false,
+    action: 'created',
+  };
+
+  try {
+    // Ensure directory exists
+    await ensureDir(dirname(filePath));
+
+    // Check if file exists
+    const exists = await fileExists(filePath);
+
+    if (exists) {
+      switch (options.existingFiles) {
+        case 'skip':
+          result.action = 'skipped';
+          result.success = true;
+          return result;
+
+        case 'backup':
+          if (options.createBackups) {
+            result.backupPath = await backupFile(filePath);
+            result.action = 'backed_up';
+          } else {
+            result.action = 'overwritten';
+          }
+          break;
+
+        case 'overwrite':
+          result.action = 'overwritten';
+          break;
+      }
+    }
+
+    // Write the file
+    await writeFile(filePath, content, 'utf-8');
+    result.success = true;
+
+    if (options.verbose) {
+      console.log(`  ${result.action}: ${filePath}`);
+    }
+  } catch (error) {
+    result.action = 'error';
+    result.error = error instanceof Error ? error.message : String(error);
+    result.success = false;
+  }
+
+  return result;
+}
+
+/**
+ * Write multiple files from a Map
+ */
+export async function writeFiles(
+  files: Map<string, string>,
+  baseDir: string,
+  options: WriteOptions = DEFAULT_WRITE_OPTIONS
+): Promise<WriteSummary> {
+  const summary: WriteSummary = {
+    total: files.size,
+    created: 0,
+    backedUp: 0,
+    skipped: 0,
+    overwritten: 0,
+    errors: 0,
+    results: [],
+  };
+
+  for (const [relativePath, content] of files) {
+    const fullPath = join(baseDir, relativePath);
+    const result = await writeFileWithOptions(fullPath, content, options);
+    summary.results.push(result);
+
+    switch (result.action) {
+      case 'created':
+        summary.created++;
+        break;
+      case 'backed_up':
+        summary.backedUp++;
+        break;
+      case 'skipped':
+        summary.skipped++;
+        break;
+      case 'overwritten':
+        summary.overwritten++;
+        break;
+      case 'error':
+        summary.errors++;
+        break;
+    }
+  }
+
+  return summary;
+}
+
+/**
+ * Directory structure for .ralph
+ */
+export const RALPH_DIRECTORY_STRUCTURE = {
+  root: '.ralph',
+  directories: [
+    '.ralph/prompts',
+    '.ralph/guides',
+    '.ralph/specs',
+    '.ralph/scripts',
+  ],
+};
+
+/**
+ * Create the .ralph directory structure
+ */
+export async function createDirectoryStructure(projectRoot: string): Promise<void> {
+  for (const dir of RALPH_DIRECTORY_STRUCTURE.directories) {
+    await ensureDir(join(projectRoot, dir));
+  }
+}
+
+/**
+ * Map template output paths to their final locations in .ralph
+ */
+export function mapTemplateOutputPaths(templateOutputs: Map<string, string>): Map<string, string> {
+  const mapped = new Map<string, string>();
+
+  for (const [outputPath, content] of templateOutputs) {
+    // Map template categories to .ralph structure
+    let finalPath: string;
+
+    if (outputPath.startsWith('prompts/')) {
+      finalPath = `.ralph/${outputPath}`;
+    } else if (outputPath.startsWith('guides/')) {
+      finalPath = `.ralph/${outputPath}`;
+    } else if (outputPath.startsWith('specs/')) {
+      finalPath = `.ralph/${outputPath}`;
+    } else if (outputPath.startsWith('scripts/')) {
+      // Scripts go to .ralph/scripts/
+      finalPath = `.ralph/${outputPath}`;
+    } else if (outputPath.startsWith('config/')) {
+      // ralph.config.js goes to project root
+      finalPath = outputPath.replace('config/', '');
+    } else if (outputPath.startsWith('root/')) {
+      // Root files go to .ralph/
+      finalPath = `.ralph/${outputPath.replace('root/', '')}`;
+    } else {
+      // Default: put in .ralph/
+      finalPath = `.ralph/${outputPath}`;
+    }
+
+    mapped.set(finalPath, content);
+  }
+
+  return mapped;
+}
+
+/**
+ * Format write summary for display
+ */
+export function formatWriteSummary(summary: WriteSummary): string {
+  const lines: string[] = [];
+
+  lines.push('Write Summary:');
+  lines.push(`  Total files: ${summary.total}`);
+  lines.push(`  Created: ${summary.created}`);
+
+  if (summary.backedUp > 0) {
+    lines.push(`  Backed up & updated: ${summary.backedUp}`);
+  }
+
+  if (summary.skipped > 0) {
+    lines.push(`  Skipped (existing): ${summary.skipped}`);
+  }
+
+  if (summary.overwritten > 0) {
+    lines.push(`  Overwritten: ${summary.overwritten}`);
+  }
+
+  if (summary.errors > 0) {
+    lines.push(`  Errors: ${summary.errors}`);
+    for (const result of summary.results) {
+      if (result.action === 'error') {
+        lines.push(`    - ${result.path}: ${result.error}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+import { createCli } from './cli.js';
+
+/**
+ * Main entry point for the Ralph CLI
+ */
+export async function main(): Promise<void> {
+  const program = createCli();
+  await program.parseAsync(process.argv);
+}
+
+// Export for programmatic use
+export { createCli } from './cli.js';
+export { displayHeader } from './utils/header.js';
+export { logger } from './utils/logger.js';
+
+// Export scanner
+export { Scanner, scanProject, formatScanResult } from './scanner/index.js';
+export type {
+  DetectionResult,
+  DetectedStack,
+  ScanResult,
+  ScannerOptions,
+} from './scanner/index.js';
+
+// Export generator
+export {
+  Generator,
+  generateRalph,
+  formatGenerationResult,
+  extractVariables,
+  generateConfig,
+  generateConfigFile,
+} from './generator/index.js';
+export type {
+  GeneratorOptions,
+  GenerationResult,
+  TemplateVariables,
+  RalphConfig,
+  WriteOptions,
+  WriteSummary,
+} from './generator/index.js';

package/src/scanner/detectors/core/framework.ts

@@ -0,0 +1,332 @@
+/**
+ * Framework Detector
+ * Detects web frameworks: Next.js, React, Vue, Svelte, Remix, Astro
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Detector, DetectionResult } from '../../types.js';
+import {
+  readPackageJson,
+  getDependencies,
+  findConfigFile,
+  type DependencyMap,
+} from '../utils.js';
+
+/**
+ * Detect Next.js variant (app router vs pages router)
+ */
+function detectNextJsVariant(projectRoot: string): string | undefined {
+  const appDir = join(projectRoot, 'app');
+  const srcAppDir = join(projectRoot, 'src', 'app');
+
+  if (existsSync(appDir) || existsSync(srcAppDir)) {
+    return 'app-router';
+  }
+
+  const pagesDir = join(projectRoot, 'pages');
+  const srcPagesDir = join(projectRoot, 'src', 'pages');
+
+  if (existsSync(pagesDir) || existsSync(srcPagesDir)) {
+    return 'pages-router';
+  }
+
+  return undefined;
+}
+
+/**
+ * Detect Next.js
+ */
+function detectNextJs(projectRoot: string, deps: DependencyMap): DetectionResult | null {
+  const evidence: string[] = [];
+  let confidence = 0;
+
+  // Check for next dependency
+  if (deps.next) {
+    evidence.push(`next@${deps.next} in dependencies`);
+    confidence += 60;
+  }
+
+  // Check for next.config.* files
+  const configExtensions = ['.js', '.mjs', '.ts'];
+  const configFile = findConfigFile(projectRoot, 'next.config', configExtensions);
+  if (configFile) {
+    evidence.push(`${configFile} found`);
+    confidence += 30;
+  }
+
+  if (confidence === 0) return null;
+
+  const variant = detectNextJsVariant(projectRoot);
+  if (variant) {
+    evidence.push(`${variant} detected`);
+    confidence += 10;
+  }
+
+  return {
+    name: 'Next.js',
+    version: deps.next,
+    variant,
+    confidence: Math.min(confidence, 100),
+    evidence,
+  };
+}
+
+/**
+ * Detect Vue/Nuxt
+ */
+function detectVue(projectRoot: string, deps: DependencyMap): DetectionResult | null {
+  const evidence: string[] = [];
+  let confidence = 0;
+
+  // Check for nuxt (takes precedence as it includes Vue)
+  if (deps.nuxt) {
+    evidence.push(`nuxt@${deps.nuxt} in dependencies`);
+    confidence += 70;
+
+    const nuxtConfig = findConfigFile(projectRoot, 'nuxt.config', ['.js', '.ts']);
+    if (nuxtConfig) {
+      evidence.push(`${nuxtConfig} found`);
+      confidence += 30;
+    }
+
+    return {
+      name: 'Nuxt',
+      version: deps.nuxt,
+      confidence: Math.min(confidence, 100),
+      evidence,
+    };
+  }
+
+  // Check for vue
+  if (deps.vue) {
+    evidence.push(`vue@${deps.vue} in dependencies`);
+    confidence += 50;
+
+    // Check for Vue-specific configs
+    const vueConfig = findConfigFile(projectRoot, 'vue.config', ['.js', '.ts']);
+    if (vueConfig) {
+      evidence.push(`${vueConfig} found`);
+      confidence += 20;
+    }
+
+    const viteConfig = findConfigFile(projectRoot, 'vite.config', ['.js', '.ts', '.mjs']);
+    if (viteConfig && deps['@vitejs/plugin-vue']) {
+      evidence.push('Vite + Vue plugin detected');
+      confidence += 20;
+    }
+
+    if (confidence === 0) return null;
+
+    return {
+      name: 'Vue',
+      version: deps.vue,
+      confidence: Math.min(confidence, 100),
+      evidence,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Detect Svelte/SvelteKit
+ */
+function detectSvelte(projectRoot: string, deps: DependencyMap): DetectionResult | null {
+  const evidence: string[] = [];
+  let confidence = 0;
+
+  // Check for SvelteKit (takes precedence)
+  if (deps['@sveltejs/kit']) {
+    evidence.push(`@sveltejs/kit@${deps['@sveltejs/kit']} in dependencies`);
+    confidence += 70;
+
+    const svelteConfig = findConfigFile(projectRoot, 'svelte.config', ['.js', '.ts']);
+    if (svelteConfig) {
+      evidence.push(`${svelteConfig} found`);
+      confidence += 30;
+    }
+
+    return {
+      name: 'SvelteKit',
+      version: deps['@sveltejs/kit'],
+      confidence: Math.min(confidence, 100),
+      evidence,
+    };
+  }
+
+  // Check for Svelte
+  if (deps.svelte) {
+    evidence.push(`svelte@${deps.svelte} in dependencies`);
+    confidence += 50;
+
+    const svelteConfig = findConfigFile(projectRoot, 'svelte.config', ['.js', '.ts']);
+    if (svelteConfig) {
+      evidence.push(`${svelteConfig} found`);
+      confidence += 30;
+    }
+
+    if (confidence === 0) return null;
+
+    return {
+      name: 'Svelte',
+      version: deps.svelte,
+      confidence: Math.min(confidence, 100),
+      evidence,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Detect Remix
+ */
+function detectRemix(projectRoot: string, deps: DependencyMap): DetectionResult | null {
+  const evidence: string[] = [];
+  let confidence = 0;
+
+  if (deps['@remix-run/react'] || deps['@remix-run/node']) {
+    const version = deps['@remix-run/react'] || deps['@remix-run/node'];
+    evidence.push(`@remix-run packages@${version} in dependencies`);
+    confidence += 70;
+
+    // Check for remix config
+    const remixConfig = findConfigFile(projectRoot, 'remix.config', ['.js', '.ts']);
+    if (remixConfig) {
+      evidence.push(`${remixConfig} found`);
+      confidence += 20;
+    }
+
+    // Remix v2+ uses vite
+    const viteConfig = findConfigFile(projectRoot, 'vite.config', ['.js', '.ts', '.mjs']);
+    if (viteConfig && deps['@remix-run/dev']) {
+      evidence.push('Vite-based Remix setup detected');
+      confidence += 10;
+    }
+
+    return {
+      name: 'Remix',
+      version,
+      confidence: Math.min(confidence, 100),
+      evidence,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Detect Astro
+ */
+function detectAstro(projectRoot: string, deps: DependencyMap): DetectionResult | null {
+  const evidence: string[] = [];
+  let confidence = 0;
+
+  if (deps.astro) {
+    evidence.push(`astro@${deps.astro} in dependencies`);
+    confidence += 60;
+
+    const astroConfig = findConfigFile(projectRoot, 'astro.config', ['.mjs', '.js', '.ts']);
+    if (astroConfig) {
+      evidence.push(`${astroConfig} found`);
+      confidence += 30;
+    }
+
+    return {
+      name: 'Astro',
+      version: deps.astro,
+      confidence: Math.min(confidence, 100),
+      evidence,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Detect plain React (no framework)
+ */
+function detectReact(projectRoot: string, deps: DependencyMap): DetectionResult | null {
+  const evidence: string[] = [];
+  let confidence = 0;
+
+  if (deps.react) {
+    evidence.push(`react@${deps.react} in dependencies`);
+    confidence += 40;
+
+    // Check for common React setups
+    if (deps['react-scripts']) {
+      evidence.push('Create React App detected (react-scripts)');
+      confidence += 40;
+      return {
+        name: 'React',
+        version: deps.react,
+        variant: 'create-react-app',
+        confidence: Math.min(confidence, 100),
+        evidence,
+      };
+    }
+
+    // Vite + React
+    if (deps['@vitejs/plugin-react'] || deps['@vitejs/plugin-react-swc']) {
+      evidence.push('Vite + React setup detected');
+      confidence += 30;
+      return {
+        name: 'React',
+        version: deps.react,
+        variant: 'vite',
+        confidence: Math.min(confidence, 100),
+        evidence,
+      };
+    }
+
+    // Plain React
+    return {
+      name: 'React',
+      version: deps.react,
+      confidence: Math.min(confidence, 100),
+      evidence,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Framework detector
+ */
+export const frameworkDetector: Detector = {
+  category: 'framework',
+  name: 'Framework Detector',
+
+  async detect(projectRoot: string): Promise<DetectionResult | null> {
+    const pkg = readPackageJson(projectRoot);
+    if (!pkg) {
+      return null;
+    }
+
+    const deps = getDependencies(pkg);
+
+    // Order matters: check meta-frameworks first, then base frameworks
+    const detectors = [
+      detectNextJs,
+      detectRemix,
+      detectAstro,
+      detectVue, // Also handles Nuxt
+      detectSvelte, // Also handles SvelteKit
+      detectReact, // Check React last as it's often a dependency of frameworks
+    ];
+
+    for (const detector of detectors) {
+      const result = detector(projectRoot, deps);
+      if (result && result.confidence >= 40) {
+        return result;
+      }
+    }
+
+    return null;
+  },
+};
+
+export default frameworkDetector;