create-sdd-project 0.7.0 → 0.8.0

package/README.md

@@ -168,14 +168,62 @@ npx create-sdd-project --doctor
 
 Exit code 1 if errors found — useful for CI pipelines.
 
+### Eject (Uninstall SDD)
+
+Cleanly remove all SDD DevFlow files from your project:
+
+```bash
+cd your-project
+npx create-sdd-project --eject
+```
+
+```
+🗑️  SDD DevFlow Eject
+
+  Installed version:  0.7.0
+  AI tools:           Claude Code + Gemini
+  Project type:       backend
+
+  Will remove:
+    ✗ .claude/agents/           template agents
+    ✗ .claude/skills/
+    ✗ .claude/hooks/
+    ✗ .claude/settings.json
+    ✗ .gemini/                  entire directory
+    ✗ ai-specs/                 standards
+    ✗ AGENTS.md
+    ✗ CLAUDE.md / GEMINI.md
+    ✗ .env.example
+    ✗ .sdd-version
+    ✗ .github/workflows/ci.yml  (SDD-generated)
+
+  Will preserve:
+    ⊘ .claude/agents/my-agent.md   (custom agent)
+    ⊘ .claude/settings.local.json  (personal settings)
+    ⊘ docs/                        (project notes, specs, tickets)
+
+  Proceed? (y/N)
+```
+
+**What gets removed:** All SDD-generated files (agents, skills, hooks, standards, configs, CI workflow).
+
+**What is always preserved:** Custom agents, custom commands, personal settings, project documentation (`docs/`), customized CI workflows (without SDD marker).
+
+For non-interactive eject: `npx create-sdd-project --eject --yes`
+
+Preview what would be removed: `npx create-sdd-project --eject --diff`
+
+To re-install later: `npx create-sdd-project --init`
+
 ### Preview Changes (--diff)
 
-See what `--init` or `--upgrade` would do without modifying anything:
+See what `--init`, `--upgrade`, or `--eject` would do without modifying anything:
 
 ```bash
 cd your-existing-project
 npx create-sdd-project --init --diff      # Preview init
 npx create-sdd-project --upgrade --diff   # Preview upgrade
+npx create-sdd-project --eject --diff    # Preview eject
 ```
 
 Shows detected stack, files that would be created/replaced/preserved, and standards status — zero filesystem writes.

package/bin/cli.js

@@ -11,6 +11,7 @@ const isInit = args.includes('--init');
 const isUpgrade = args.includes('--upgrade');
 const isDoctor = args.includes('--doctor');
 const isForce = args.includes('--force');
+const isEject = args.includes('--eject');
 const isDiff = args.includes('--diff');
 
 async function main() {
@@ -20,6 +21,9 @@ async function main() {
   if (isDoctor) {
     return runDoctorCmd();
   }
+  if (isEject) {
+    return runEject();
+  }
   if (isUpgrade) {
     return runUpgrade();
   }
@@ -220,11 +224,64 @@ async function runUpgrade() {
   generateUpgrade(config);
 }
 
+async function runEject() {
+  const readline = require('readline');
+  const {
+    collectEjectInventory,
+    buildEjectSummary,
+    generateEject,
+  } = require('../lib/eject-generator');
+
+  const cwd = process.cwd();
+
+  // Validate: must be in an existing project
+  if (!fs.existsSync(path.join(cwd, 'package.json'))) {
+    console.error('Error: No package.json found in current directory.');
+    console.error('The --eject flag must be run from inside an existing project.');
+    process.exit(1);
+  }
+
+  // Validate: SDD must be installed
+  if (!fs.existsSync(path.join(cwd, 'ai-specs'))) {
+    console.error('Error: ai-specs/ directory not found.');
+    console.error('SDD DevFlow does not appear to be installed. Nothing to eject.');
+    process.exit(1);
+  }
+
+  // Validate: no project name with --eject
+  if (projectName) {
+    console.error('Error: Cannot specify a project name with --eject.');
+    console.error('Usage: create-sdd-project --eject');
+    process.exit(1);
+  }
+
+  const state = collectEjectInventory(cwd);
+
+  if (!useDefaults) {
+    console.log('\n' + buildEjectSummary(state));
+    console.log('');
+
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+      rl.question('  Proceed? (y/N) ', resolve);
+    });
+    rl.close();
+
+    if (answer.toLowerCase() !== 'y' && answer.toLowerCase() !== 'yes') {
+      console.log('\nEject cancelled.\n');
+      return;
+    }
+  }
+
+  generateEject(cwd);
+}
+
 async function runDiff() {
-  if (!isInit && !isUpgrade) {
-    console.error('Error: --diff must be combined with --init or --upgrade.');
+  if (!isInit && !isUpgrade && !isEject) {
+    console.error('Error: --diff must be combined with --init, --upgrade, or --eject.');
     console.error('Usage: create-sdd-project --init --diff');
     console.error('       create-sdd-project --upgrade --diff');
+    console.error('       create-sdd-project --eject --diff');
     process.exit(1);
   }
 
@@ -240,6 +297,22 @@ async function runDiff() {
     process.exit(1);
   }
 
+  if (isEject) {
+    // Same validation as --eject
+    if (!fs.existsSync(path.join(cwd, 'ai-specs'))) {
+      console.error('Error: ai-specs/ directory not found.');
+      console.error('SDD DevFlow does not appear to be installed. Nothing to eject.');
+      process.exit(1);
+    }
+
+    const { runEjectDiffReport } = require('../lib/diff-generator');
+    const { collectEjectInventory } = require('../lib/eject-generator');
+
+    const state = collectEjectInventory(cwd);
+    runEjectDiffReport(state);
+    return;
+  }
+
   const { scan } = require('../lib/scanner');
   const { buildInitDefaultConfig } = require('../lib/init-wizard');
   const { runInitDiffReport, runUpgradeDiffReport } = require('../lib/diff-generator');

package/lib/diff-generator.js

@@ -271,4 +271,17 @@ function runUpgradeDiffReport(config, state) {
   console.log(lines.join('\n'));
 }
 
-module.exports = { runInitDiffReport, runUpgradeDiffReport };
+// ── Eject Diff ──────────────────────────────────────────────
+
+function runEjectDiffReport(state) {
+  const { buildEjectSummary } = require('./eject-generator');
+
+  const lines = [];
+  lines.push('\n🔍 SDD DevFlow — Preview (--eject)\n');
+  lines.push(buildEjectSummary(state).split('\n').slice(1).join('\n')); // skip the emoji header (already have our own)
+  lines.push('\n  No files removed. Run without --diff to apply.\n');
+
+  console.log(lines.join('\n'));
+}
+
+module.exports = { runInitDiffReport, runUpgradeDiffReport, runEjectDiffReport };

package/lib/eject-generator.js

@@ -0,0 +1,352 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { TEMPLATE_AGENTS } = require('./config');
+const {
+  readInstalledVersion,
+  detectAiTools,
+  detectProjectType,
+  collectCustomAgents,
+  collectCustomCommands,
+} = require('./upgrade-generator');
+
+/**
+ * Collect inventory of what eject would remove vs preserve.
+ */
+function collectEjectInventory(cwd) {
+  const installedVersion = readInstalledVersion(cwd);
+  const aiTools = detectAiTools(cwd);
+  const projectType = detectProjectType(cwd);
+  const customAgents = collectCustomAgents(cwd);
+  const customCommands = collectCustomCommands(cwd);
+
+  const hasSettingsLocal = fs.existsSync(path.join(cwd, '.claude', 'settings.local.json'));
+  const hasDocsDir = fs.existsSync(path.join(cwd, 'docs'));
+
+  // Detect SDD-generated CI workflow
+  let ciIsSddGenerated = false;
+  const ciPath = path.join(cwd, '.github', 'workflows', 'ci.yml');
+  if (fs.existsSync(ciPath)) {
+    const ciContent = fs.readFileSync(ciPath, 'utf8');
+    ciIsSddGenerated = ciContent.includes('Generated by SDD DevFlow');
+  }
+
+  // Detect SDD entries in .gitignore
+  let gitignoreHasSddEntries = false;
+  const gitignorePath = path.join(cwd, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    gitignoreHasSddEntries = content.includes('# SDD DevFlow');
+  }
+
+  return {
+    installedVersion,
+    aiTools,
+    projectType,
+    customAgents,
+    customCommands,
+    hasSettingsLocal,
+    hasDocsDir,
+    ciPath: fs.existsSync(ciPath) ? ciPath : null,
+    ciIsSddGenerated,
+    gitignoreHasSddEntries,
+  };
+}
+
+/**
+ * Build the eject summary for display.
+ */
+function buildEjectSummary(state) {
+  const lines = [];
+  lines.push('🗑️  SDD DevFlow Eject\n');
+  lines.push(`  Installed version:  ${state.installedVersion}`);
+  lines.push(`  AI tools:           ${state.aiTools === 'both' ? 'Claude Code + Gemini' : state.aiTools === 'claude' ? 'Claude Code' : 'Gemini'}`);
+  lines.push(`  Project type:       ${state.projectType}\n`);
+
+  // Will remove
+  lines.push('  Will remove:');
+  if (state.aiTools !== 'gemini') {
+    lines.push('    ✗ .claude/agents/           template agents');
+    lines.push('    ✗ .claude/skills/');
+    lines.push('    ✗ .claude/hooks/');
+    lines.push('    ✗ .claude/settings.json');
+  }
+  if (state.aiTools !== 'claude') {
+    lines.push('    ✗ .gemini/                  entire directory');
+  }
+  lines.push('    ✗ ai-specs/                 standards');
+  lines.push('    ✗ AGENTS.md');
+  if (state.aiTools !== 'gemini') lines.push('    ✗ CLAUDE.md');
+  if (state.aiTools !== 'claude') lines.push('    ✗ GEMINI.md');
+  lines.push('    ✗ .env.example');
+  lines.push('    ✗ .sdd-version');
+  if (state.ciIsSddGenerated) {
+    lines.push('    ✗ .github/workflows/ci.yml  (SDD-generated)');
+  }
+
+  // Will preserve
+  const preserveItems = [];
+  if (state.customAgents.length > 0) {
+    for (const a of state.customAgents) {
+      preserveItems.push(`${a.relativePath}  (custom agent)`);
+    }
+  }
+  if (state.customCommands.length > 0) {
+    for (const c of state.customCommands) {
+      preserveItems.push(`${c.relativePath}  (custom command)`);
+    }
+  }
+  if (state.hasSettingsLocal) {
+    preserveItems.push('.claude/settings.local.json  (personal settings)');
+  }
+  if (state.hasDocsDir) {
+    preserveItems.push('docs/                        (project notes, specs, tickets)');
+  }
+  if (state.ciPath && !state.ciIsSddGenerated) {
+    preserveItems.push('.github/workflows/ci.yml     (customized — not SDD-generated)');
+  }
+
+  if (preserveItems.length > 0) {
+    lines.push('\n  Will preserve:');
+    for (const item of preserveItems) {
+      lines.push(`    ⊘ ${item}`);
+    }
+  }
+
+  // Will modify
+  if (state.gitignoreHasSddEntries) {
+    lines.push('\n  Will modify:');
+    lines.push('    ~ .gitignore                remove SDD DevFlow section');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Execute the eject: remove all SDD-owned files, preserve user work.
+ */
+function generateEject(cwd) {
+  const state = collectEjectInventory(cwd);
+  let removed = 0;
+  let preserved = 0;
+
+  console.log(`\nEjecting SDD DevFlow from ${path.basename(cwd)}...\n`);
+
+  // --- 1. Remove template agents (preserve custom) ---
+  for (const toolDir of ['.claude', '.gemini']) {
+    const agentsDir = path.join(cwd, toolDir, 'agents');
+    if (!fs.existsSync(agentsDir)) continue;
+
+    const files = fs.readdirSync(agentsDir);
+    for (const file of files) {
+      if (TEMPLATE_AGENTS.includes(file)) {
+        fs.unlinkSync(path.join(agentsDir, file));
+        removed++;
+      }
+    }
+
+    // Remove agents dir if empty
+    if (fs.existsSync(agentsDir) && fs.readdirSync(agentsDir).length === 0) {
+      fs.rmSync(agentsDir, { recursive: true });
+    }
+  }
+  step('Removed template agents');
+
+  // --- 2. Remove skills ---
+  for (const toolDir of ['.claude', '.gemini']) {
+    const skillsDir = path.join(cwd, toolDir, 'skills');
+    if (fs.existsSync(skillsDir)) {
+      removed += countFilesRecursive(skillsDir);
+      fs.rmSync(skillsDir, { recursive: true });
+    }
+  }
+  step('Removed skills');
+
+  // --- 3. Remove hooks ---
+  const hooksDir = path.join(cwd, '.claude', 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    removed += countFilesRecursive(hooksDir);
+    fs.rmSync(hooksDir, { recursive: true });
+  }
+  step('Removed hooks');
+
+  // --- 4. Handle commands ---
+  // .claude/commands: only remove .gitkeep, keep custom commands
+  const claudeCommandsDir = path.join(cwd, '.claude', 'commands');
+  if (fs.existsSync(claudeCommandsDir)) {
+    const gitkeepPath = path.join(claudeCommandsDir, '.gitkeep');
+    if (fs.existsSync(gitkeepPath)) {
+      fs.unlinkSync(gitkeepPath);
+      removed++;
+    }
+    // Remove dir if empty
+    if (fs.readdirSync(claudeCommandsDir).length === 0) {
+      fs.rmSync(claudeCommandsDir, { recursive: true });
+    }
+  }
+
+  // .gemini/commands: remove entirely (SDD-owned TOML commands)
+  const geminiCommandsDir = path.join(cwd, '.gemini', 'commands');
+  if (fs.existsSync(geminiCommandsDir)) {
+    removed += countFilesRecursive(geminiCommandsDir);
+    fs.rmSync(geminiCommandsDir, { recursive: true });
+  }
+
+  // --- 5. Handle .claude/settings.json ---
+  const settingsPath = path.join(cwd, '.claude', 'settings.json');
+  if (fs.existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      delete settings.hooks;
+
+      // If nothing meaningful remains, delete the file
+      const remainingKeys = Object.keys(settings);
+      if (remainingKeys.length === 0) {
+        fs.unlinkSync(settingsPath);
+        removed++;
+      } else {
+        // Keep permissions and other user settings
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+        preserved++;
+      }
+    } catch {
+      // Corrupted JSON — remove it
+      fs.unlinkSync(settingsPath);
+      removed++;
+    }
+  }
+  step('Handled settings.json');
+
+  // --- 6. Remove .gemini/ entirely (styles, settings) ---
+  // styles
+  const geminiStylesDir = path.join(cwd, '.gemini', 'styles');
+  if (fs.existsSync(geminiStylesDir)) {
+    removed += countFilesRecursive(geminiStylesDir);
+    fs.rmSync(geminiStylesDir, { recursive: true });
+  }
+  // settings.json
+  const geminiSettingsPath = path.join(cwd, '.gemini', 'settings.json');
+  if (fs.existsSync(geminiSettingsPath)) {
+    fs.unlinkSync(geminiSettingsPath);
+    removed++;
+  }
+
+  // --- 7. Remove ai-specs/ entirely ---
+  const aiSpecsDir = path.join(cwd, 'ai-specs');
+  if (fs.existsSync(aiSpecsDir)) {
+    removed += countFilesRecursive(aiSpecsDir);
+    fs.rmSync(aiSpecsDir, { recursive: true });
+  }
+  step('Removed ai-specs/');
+
+  // --- 8. Remove top-level SDD files ---
+  const topLevelFiles = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', '.env.example', '.sdd-version'];
+  for (const file of topLevelFiles) {
+    const filePath = path.join(cwd, file);
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+      removed++;
+    }
+  }
+  step('Removed AGENTS.md, CLAUDE.md, GEMINI.md, .env.example, .sdd-version');
+
+  // --- 9. Handle CI workflow ---
+  if (state.ciIsSddGenerated) {
+    fs.unlinkSync(state.ciPath);
+    removed++;
+    step('Removed .github/workflows/ci.yml (SDD-generated)');
+
+    // Clean empty dirs
+    const workflowsDir = path.join(cwd, '.github', 'workflows');
+    if (fs.existsSync(workflowsDir) && fs.readdirSync(workflowsDir).length === 0) {
+      fs.rmSync(workflowsDir, { recursive: true });
+    }
+    const githubDir = path.join(cwd, '.github');
+    if (fs.existsSync(githubDir) && fs.readdirSync(githubDir).length === 0) {
+      fs.rmSync(githubDir, { recursive: true });
+    }
+  } else if (state.ciPath) {
+    preserved++;
+    step('Preserved .github/workflows/ci.yml (customized)');
+  }
+
+  // --- 10. Clean .gitignore ---
+  if (state.gitignoreHasSddEntries) {
+    const gitignorePath = path.join(cwd, '.gitignore');
+    let content = fs.readFileSync(gitignorePath, 'utf8');
+    // Remove the SDD DevFlow section (tolerant of leading/trailing newlines)
+    content = content.replace(/\n?# SDD DevFlow\ndocs\/tickets\/\*\.md\n!docs\/tickets\/\.gitkeep\n?/, '');
+    fs.writeFileSync(gitignorePath, content, 'utf8');
+    step('Cleaned .gitignore');
+  }
+
+  // --- 11. Clean empty parent directories ---
+  for (const dir of ['.claude', '.gemini']) {
+    const dirPath = path.join(cwd, dir);
+    if (fs.existsSync(dirPath)) {
+      cleanEmptyDirs(dirPath);
+    }
+  }
+
+  // Count preserved items
+  preserved += state.customAgents.length + state.customCommands.length;
+  if (state.hasSettingsLocal) preserved++;
+  if (state.hasDocsDir) preserved++;
+
+  // --- Show result ---
+  console.log(`\n✅ SDD DevFlow ejected (was v${state.installedVersion})\n`);
+  console.log(`  Removed: ${removed} SDD files`);
+  if (preserved > 0) {
+    const items = [];
+    if (state.customAgents.length > 0) items.push(`${state.customAgents.length} custom agent(s)`);
+    if (state.customCommands.length > 0) items.push(`${state.customCommands.length} custom command(s)`);
+    if (state.hasSettingsLocal) items.push('personal settings');
+    if (state.hasDocsDir) items.push('docs/');
+    if (state.ciPath && !state.ciIsSddGenerated) items.push('CI workflow (customized)');
+    console.log(`  Preserved: ${items.join(', ')}`);
+  }
+  console.log('\n  To re-install later: npx create-sdd-project --init\n');
+}
+
+function step(msg) {
+  console.log(`  ✓ ${msg}`);
+}
+
+function countFilesRecursive(dir) {
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      count += countFilesRecursive(path.join(dir, entry.name));
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Remove a directory if empty, then check parent recursively.
+ */
+function cleanEmptyDirs(dirPath) {
+  if (!fs.existsSync(dirPath)) return;
+
+  // First clean subdirectories
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      cleanEmptyDirs(path.join(dirPath, entry.name));
+    }
+  }
+
+  // Then remove if empty
+  if (fs.existsSync(dirPath) && fs.readdirSync(dirPath).length === 0) {
+    fs.rmSync(dirPath, { recursive: true });
+  }
+}
+
+module.exports = {
+  collectEjectInventory,
+  buildEjectSummary,
+  generateEject,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sdd-project",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Create a new SDD DevFlow project with AI-assisted development workflow",
   "bin": {
     "create-sdd-project": "bin/cli.js"