ccraft 1.0.0

package/src/utils/existing-setup.js

@@ -0,0 +1,341 @@
+/**
+ * Existing Claude setup detection and context extraction.
+ *
+ * When claude-craft finds an existing .claude/ directory during installation,
+ * this module:
+ * 1. Detects what configuration files exist
+ * 2. Reads existing files and uses Claude to summarize project/user context
+ * 3. Removes the old setup so craft can generate a fresh configuration
+ *
+ * The extracted context enriches the new installation — the Claude analyzer
+ * receives prior knowledge about the project, producing better results.
+ */
+import { join } from 'path';
+import { existsSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync } from 'fs';
+import { isClaudeAvailable, runClaude } from './run-claude.js';
+import { extractJsonObject } from './json-extract.js';
+import * as logger from './logger.js';
+
+/**
+ * Detect if the target directory has an existing Claude setup.
+ * Returns null if no meaningful setup found, or an object describing what exists.
+ *
+ * @param {string} targetDir - Project root
+ * @returns {{ claudeMd: boolean, settings: boolean, metadata: boolean, agents: number, skills: number, rules: number, commands: number } | null}
+ */
+export function detectExistingSetup(targetDir) {
+  const claudeDir = join(targetDir, '.claude');
+  if (!existsSync(claudeDir)) return null;
+
+  const checks = {
+    claudeMd: existsSync(join(targetDir, 'CLAUDE.md')),
+    settings: existsSync(join(claudeDir, 'settings.json')),
+    metadata: existsSync(join(claudeDir, '.claude-craft.json')),
+    agents: countFilesInDir(join(claudeDir, 'agents')),
+    skills: countFilesInDir(join(claudeDir, 'skills')),
+    rules: countFilesInDir(join(claudeDir, 'rules')),
+    commands: countFilesInDir(join(claudeDir, 'commands')),
+  };
+
+  const hasContent = checks.claudeMd || checks.settings || checks.metadata
+    || checks.agents > 0 || checks.skills > 0
+    || checks.rules > 0 || checks.commands > 0;
+
+  if (!hasContent) return null;
+
+  return checks;
+}
+
+/**
+ * Extract context from existing Claude setup.
+ * Reads key files directly, then uses Claude to produce a structured summary.
+ * Falls back to a metadata-based summary if Claude is unavailable.
+ *
+ * @param {string} targetDir - Project root
+ * @returns {Promise<ExistingContext>}
+ *
+ * @typedef {object} ExistingContext
+ * @property {object|null}  previousMetadata  - Parsed .claude-craft.json
+ * @property {string|null}  claudeMdContent   - Raw CLAUDE.md text
+ * @property {object|null}  settings          - Parsed settings.json
+ * @property {{ agents: number, skills: number, rules: number, commands: number }} componentCounts
+ * @property {object}       summary           - Structured summary for downstream use
+ */
+export async function extractExistingContext(targetDir) {
+  const rawContext = readExistingFiles(targetDir);
+
+  if (isClaudeAvailable()) {
+    try {
+      const summary = await claudeSummarize(targetDir, rawContext);
+      if (summary) {
+        return { ...rawContext, summary };
+      }
+    } catch (err) {
+      logger.debug(`Claude summarization of existing setup failed: ${err.message}`);
+    }
+  }
+
+  return { ...rawContext, summary: buildFallbackSummary(rawContext) };
+}
+
+/**
+ * Remove existing .claude/ directory and root CLAUDE.md.
+ * Leaves .gitignore untouched (security patterns should persist).
+ *
+ * @param {string} targetDir - Project root
+ */
+export function removeExistingSetup(targetDir) {
+  const claudeDir = join(targetDir, '.claude');
+
+  try {
+    if (existsSync(claudeDir)) {
+      rmSync(claudeDir, { recursive: true, force: true });
+    }
+  } catch (err) {
+    logger.warn(`Failed to remove .claude/ directory: ${err.message}`);
+  }
+
+  try {
+    const claudeMdPath = join(targetDir, 'CLAUDE.md');
+    if (existsSync(claudeMdPath)) {
+      unlinkSync(claudeMdPath);
+    }
+  } catch (err) {
+    logger.warn(`Failed to remove CLAUDE.md: ${err.message}`);
+  }
+
+  try {
+    const userGuidePath = join(targetDir, 'USER_GUIDE.md');
+    if (existsSync(userGuidePath)) {
+      const content = readFileSync(userGuidePath, 'utf8');
+      if (content.includes('Generated by claude-craft')) {
+        unlinkSync(userGuidePath);
+      }
+    }
+  } catch (err) {
+    logger.warn(`Failed to remove USER_GUIDE.md: ${err.message}`);
+  }
+}
+
+/**
+ * Format extracted context into a block suitable for embedding
+ * in the Claude analyzer prompt.
+ *
+ * @param {ExistingContext} context - From extractExistingContext()
+ * @returns {string} Markdown block to append to the analysis prompt
+ */
+export function formatContextForAnalyzer(context) {
+  if (!context) return '';
+
+  const parts = [];
+
+  if (context.summary?.projectContext) {
+    parts.push(context.summary.projectContext);
+  }
+
+  if (context.summary?.userPreferences?.role) {
+    parts.push(`Previous user role: ${context.summary.userPreferences.role}`);
+  }
+
+  if (context.summary?.userPreferences?.tools?.length) {
+    parts.push(`Tools used: ${context.summary.userPreferences.tools.join(', ')}`);
+  }
+
+  if (context.summary?.customizations?.length) {
+    parts.push(`Notable customizations: ${context.summary.customizations.join('; ')}`);
+  }
+
+  if (context.summary?.preserveNotes) {
+    parts.push(`Important notes: ${context.summary.preserveNotes}`);
+  }
+
+  if (parts.length === 0) return '';
+
+  return [
+    '',
+    '## Previous Configuration Context',
+    'This project had a previous Claude Code setup. Use this to validate and enrich your analysis:',
+    ...parts,
+  ].join('\n');
+}
+
+// ── Internal helpers ─────────────────────────────────────────────
+
+/**
+ * Read key files from the existing .claude/ setup.
+ */
+function readExistingFiles(targetDir) {
+  const claudeDir = join(targetDir, '.claude');
+  const context = {
+    previousMetadata: null,
+    claudeMdContent: null,
+    settings: null,
+    componentCounts: { agents: 0, skills: 0, rules: 0, commands: 0 },
+  };
+
+  try {
+    const path = join(claudeDir, '.claude-craft.json');
+    if (existsSync(path)) {
+      context.previousMetadata = JSON.parse(readFileSync(path, 'utf8'));
+    }
+  } catch { /* skip corrupt metadata */ }
+
+  try {
+    const path = join(targetDir, 'CLAUDE.md');
+    if (existsSync(path)) {
+      const raw = readFileSync(path, 'utf8');
+      // Cap at 200 lines to keep prompts manageable
+      const lines = raw.split('\n');
+      context.claudeMdContent = lines.length > 200
+        ? lines.slice(0, 200).join('\n') + '\n... (truncated)'
+        : raw;
+    }
+  } catch { /* skip unreadable file */ }
+
+  try {
+    const path = join(claudeDir, 'settings.json');
+    if (existsSync(path)) {
+      context.settings = JSON.parse(readFileSync(path, 'utf8'));
+    }
+  } catch { /* skip corrupt settings */ }
+
+  for (const category of ['agents', 'skills', 'rules', 'commands']) {
+    context.componentCounts[category] = countFilesInDir(join(claudeDir, category));
+  }
+
+  return context;
+}
+
+/**
+ * Use Claude CLI to summarize the existing setup.
+ * All file content is embedded inline — no tool calls needed.
+ */
+async function claudeSummarize(targetDir, rawContext) {
+  const contextParts = [];
+
+  if (rawContext.claudeMdContent) {
+    contextParts.push(`## Existing CLAUDE.md\n${rawContext.claudeMdContent}`);
+  }
+
+  if (rawContext.previousMetadata) {
+    const meta = rawContext.previousMetadata;
+    const metaLines = [];
+    if (meta.project?.name) metaLines.push(`- Name: ${meta.project.name}`);
+    if (meta.project?.description) metaLines.push(`- Description: ${meta.project.description}`);
+    if (meta.project?.type) metaLines.push(`- Type: ${meta.project.type}`);
+    if (meta.role) metaLines.push(`- User role: ${meta.role}`);
+    if (meta.intents?.length) metaLines.push(`- Intents: ${meta.intents.join(', ')}`);
+    if (meta.stack?.languages?.length) metaLines.push(`- Languages: ${meta.stack.languages.join(', ')}`);
+    if (meta.stack?.frameworks?.length) metaLines.push(`- Frameworks: ${meta.stack.frameworks.join(', ')}`);
+    if (meta.architecture) metaLines.push(`- Architecture: ${meta.architecture}`);
+    if (meta.stack?.packageManager) metaLines.push(`- Package manager: ${meta.stack.packageManager}`);
+    if (meta.stack?.testFramework) metaLines.push(`- Test framework: ${meta.stack.testFramework}`);
+    if (metaLines.length > 0) {
+      contextParts.push(`## Previous Installation Metadata\n${metaLines.join('\n')}`);
+    }
+  }
+
+  if (rawContext.settings) {
+    const mcpNames = Object.keys(rawContext.settings.mcpServers || {});
+    const envVars = Object.keys(rawContext.settings.env || {});
+    const settingsLines = [];
+    if (mcpNames.length) settingsLines.push(`- MCP servers: ${mcpNames.join(', ')}`);
+    if (envVars.length) settingsLines.push(`- Environment variables: ${envVars.join(', ')}`);
+    if (settingsLines.length > 0) {
+      contextParts.push(`## Settings Summary\n${settingsLines.join('\n')}`);
+    }
+  }
+
+  if (contextParts.length === 0) return null;
+
+  const prompt = `You are analyzing an existing Claude Code configuration for a project.
+Extract useful context about the project and the user's preferences so we can
+generate a better configuration on reinstall.
+
+${contextParts.join('\n\n')}
+
+## Installed Components
+- Agents: ${rawContext.componentCounts.agents}
+- Skills: ${rawContext.componentCounts.skills}
+- Rules: ${rawContext.componentCounts.rules}
+- Commands: ${rawContext.componentCounts.commands}
+
+## Task
+
+Based on the configuration above, return a JSON summary. Focus on:
+1. Project-specific context (what the project does, tech stack, architecture)
+2. User preferences (role, work style, tools)
+3. Notable customizations beyond default generated config
+4. Anything important to carry forward to the new installation
+
+Return ONLY a JSON object:
+{
+  "projectContext": "2-3 sentence summary of the project from the existing config",
+  "userPreferences": {
+    "role": "detected user role or null",
+    "workStyle": "any work style preferences or null",
+    "tools": ["tools/services the user works with"]
+  },
+  "customizations": ["list of notable customizations beyond defaults"],
+  "preserveNotes": "anything important to carry forward, or null"
+}`;
+
+  const output = await runClaude([
+    '-p',
+    '--max-turns', '2',
+    '--allowedTools', '',
+  ], { cwd: targetDir, stdinInput: prompt, timeout: 60_000 });
+
+  return extractJsonObject(output, 'projectContext');
+}
+
+/**
+ * Build a summary from raw metadata when Claude is unavailable.
+ */
+function buildFallbackSummary(rawContext) {
+  const meta = rawContext.previousMetadata;
+  const contextParts = [];
+
+  if (meta?.project?.name) contextParts.push(`Project: ${meta.project.name}`);
+  if (meta?.project?.description) contextParts.push(meta.project.description);
+  if (meta?.stack?.languages?.length) contextParts.push(`Languages: ${meta.stack.languages.join(', ')}`);
+  if (meta?.stack?.frameworks?.length) contextParts.push(`Frameworks: ${meta.stack.frameworks.join(', ')}`);
+  if (meta?.architecture) contextParts.push(`Architecture: ${meta.architecture}`);
+
+  const tools = [];
+  if (rawContext.settings?.mcpServers) {
+    tools.push(...Object.keys(rawContext.settings.mcpServers));
+  }
+
+  return {
+    projectContext: contextParts.join('. ') || 'No previous project context available.',
+    userPreferences: {
+      role: meta?.role || null,
+      workStyle: null,
+      tools,
+    },
+    customizations: [],
+    preserveNotes: null,
+  };
+}
+
+/**
+ * Count meaningful files in a directory (excludes .gitkeep).
+ */
+function countFilesInDir(dirPath) {
+  try {
+    if (!existsSync(dirPath) || !statSync(dirPath).isDirectory()) return 0;
+    return readdirSync(dirPath, { recursive: true })
+      .filter((f) => {
+        const full = join(dirPath, String(f));
+        try {
+          return statSync(full).isFile() && !String(f).endsWith('.gitkeep');
+        } catch {
+          return false;
+        }
+      })
+      .length;
+  } catch {
+    return 0;
+  }
+}

package/src/utils/file-writer.js

@@ -0,0 +1,64 @@
+import { pathExists, ensureDir, readJson, writeJson, outputFile } from 'fs-extra/esm';
+import { dirname } from 'path';
+import { warn } from './logger.js';
+
+/**
+ * Write a file. Overwrites by default.
+ * If force=false AND interactive=true, could prompt (but we default interactive to false).
+ * Returns { path, status: 'created' | 'skipped' | 'updated' }
+ */
+export async function safeWriteFile(filePath, content, { force = false } = {}) {
+  await ensureDir(dirname(filePath));
+
+  const exists = await pathExists(filePath);
+  if (exists && !force) {
+    // Non-destructive: skip existing files unless force is set.
+    // No interactive prompt — prompts during generation hang behind the spinner.
+    return { path: filePath, status: 'skipped' };
+  }
+
+  await outputFile(filePath, content, 'utf8');
+  return { path: filePath, status: exists ? 'updated' : 'created' };
+}
+
+/**
+ * Merge new keys into an existing JSON file, or create it.
+ * Always merges — never prompts.
+ */
+export async function mergeJsonFile(filePath, data, { force = false } = {}) {
+  await ensureDir(dirname(filePath));
+
+  let existing = {};
+  const exists = await pathExists(filePath);
+
+  if (exists) {
+    try {
+      existing = await readJson(filePath);
+    } catch {
+      warn(`Could not parse ${filePath}, overwriting`);
+    }
+  }
+
+  const merged = deepMerge(existing, data);
+  await writeJson(filePath, merged, { spaces: 2 });
+  return { path: filePath, status: exists ? 'updated' : 'created' };
+}
+
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] &&
+      typeof source[key] === 'object' &&
+      !Array.isArray(source[key]) &&
+      target[key] &&
+      typeof target[key] === 'object' &&
+      !Array.isArray(target[key])
+    ) {
+      result[key] = deepMerge(target[key], source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}

package/src/utils/json-extract.js

@@ -0,0 +1,56 @@
+/**
+ * Brace-balanced JSON object extraction from mixed text.
+ *
+ * More reliable than regex for extracting JSON when the text contains
+ * nested braces inside string values (e.g. reasoning fields).
+ */
+
+/**
+ * Extract a JSON object from mixed text using brace-balanced parsing.
+ *
+ * @param {string} text         - Text that may contain a JSON object
+ * @param {string} requiredKey  - If provided, only return objects containing this key
+ * @returns {object|null}         Parsed object, or null if not found
+ */
+export function extractJsonObject(text, requiredKey = null) {
+  if (!text || typeof text !== 'string') return null;
+
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] !== '{') continue;
+
+    // Quick check: if requiredKey specified, verify it exists after this brace
+    if (requiredKey && !text.slice(i).includes(`"${requiredKey}"`)) return null;
+
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+
+    for (let j = i; j < text.length; j++) {
+      const ch = text[j];
+
+      if (escape) { escape = false; continue; }
+      if (ch === '\\' && inString) { escape = true; continue; }
+      if (ch === '"' && !escape) { inString = !inString; continue; }
+      if (inString) continue;
+
+      if (ch === '{') depth++;
+      else if (ch === '}') {
+        depth--;
+        if (depth === 0) {
+          const candidate = text.slice(i, j + 1);
+          try {
+            const obj = JSON.parse(candidate);
+            if (!requiredKey || (obj && typeof obj === 'object' && requiredKey in obj)) {
+              return obj;
+            }
+          } catch {
+            // Not valid JSON at this position, try next `{`
+          }
+          break; // This brace pair didn't parse; move to next `{`
+        }
+      }
+    }
+  }
+
+  return null;
+}

package/src/utils/logger.js

@@ -0,0 +1,27 @@
+import { colors, icons } from '../ui/theme.js';
+
+export function info(msg) {
+  console.log(icons.info, msg);
+}
+
+export function success(msg) {
+  console.log(icons.check, msg);
+}
+
+export function warn(msg) {
+  console.log(icons.warning, msg);
+}
+
+export function error(msg) {
+  console.error(icons.cross, msg);
+}
+
+export function heading(msg) {
+  console.log('\n' + colors.bold(colors.underline(msg)));
+}
+
+export function debug(msg) {
+  if (process.env.CLAUDE_CRAFT_DEBUG) {
+    console.log(colors.muted('[debug]'), msg);
+  }
+}