create-sdd-project 0.6.1 → 0.7.0

package/README.md

@@ -168,6 +168,18 @@ npx create-sdd-project --doctor
 
 Exit code 1 if errors found — useful for CI pipelines.
 
+### Preview Changes (--diff)
+
+See what `--init` or `--upgrade` 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
+```
+
+Shows detected stack, files that would be created/replaced/preserved, and standards status — zero filesystem writes.
+
 ### CI/CD (Auto-Generated)
 
 Every project gets a GitHub Actions CI workflow at `.github/workflows/ci.yml`, adapted to your stack:

package/bin/cli.js

@@ -11,8 +11,12 @@ const isInit = args.includes('--init');
 const isUpgrade = args.includes('--upgrade');
 const isDoctor = args.includes('--doctor');
 const isForce = args.includes('--force');
+const isDiff = args.includes('--diff');
 
 async function main() {
+  if (isDiff) {
+    return runDiff();
+  }
   if (isDoctor) {
     return runDoctorCmd();
   }
@@ -216,6 +220,100 @@ async function runUpgrade() {
   generateUpgrade(config);
 }
 
+async function runDiff() {
+  if (!isInit && !isUpgrade) {
+    console.error('Error: --diff must be combined with --init or --upgrade.');
+    console.error('Usage: create-sdd-project --init --diff');
+    console.error('       create-sdd-project --upgrade --diff');
+    process.exit(1);
+  }
+
+  if (projectName) {
+    console.error('Error: Cannot specify a project name with --diff.');
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+
+  if (!fs.existsSync(path.join(cwd, 'package.json'))) {
+    console.error('Error: No package.json found in current directory.');
+    process.exit(1);
+  }
+
+  const { scan } = require('../lib/scanner');
+  const { buildInitDefaultConfig } = require('../lib/init-wizard');
+  const { runInitDiffReport, runUpgradeDiffReport } = require('../lib/diff-generator');
+
+  if (isInit) {
+    // Same validation as --init
+    if (fs.existsSync(path.join(cwd, 'ai-specs'))) {
+      console.error('Error: ai-specs/ directory already exists.');
+      console.error('SDD DevFlow appears to already be installed. Use --upgrade --diff instead.');
+      process.exit(1);
+    }
+
+    const scanResult = scan(cwd);
+    const config = buildInitDefaultConfig(scanResult);
+    runInitDiffReport(config);
+    return;
+  }
+
+  if (isUpgrade) {
+    // Same validation as --upgrade
+    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. Use --init --diff instead.');
+      process.exit(1);
+    }
+
+    const {
+      readInstalledVersion,
+      getPackageVersion,
+      detectAiTools,
+      detectProjectType,
+      readAutonomyLevel,
+      collectCustomAgents,
+      collectCustomCommands,
+    } = require('../lib/upgrade-generator');
+
+    const installedVersion = readInstalledVersion(cwd);
+    const packageVersion = getPackageVersion();
+
+    if (installedVersion === packageVersion && !isForce) {
+      console.log(`\nSDD DevFlow is already at version ${packageVersion}.`);
+      console.log('Use --force --diff to preview a re-install.\n');
+      return;
+    }
+
+    const scanResult = scan(cwd);
+    const aiTools = detectAiTools(cwd);
+    const projectType = detectProjectType(cwd);
+    const autonomy = readAutonomyLevel(cwd);
+    const customAgents = collectCustomAgents(cwd);
+    const customCommands = collectCustomCommands(cwd);
+    const settingsLocal = fs.existsSync(path.join(cwd, '.claude', 'settings.local.json'));
+
+    const config = buildInitDefaultConfig(scanResult);
+    config.aiTools = aiTools;
+    config.projectType = projectType;
+    config.autonomyLevel = autonomy.level;
+    config.autonomyName = autonomy.name;
+    config.installedVersion = installedVersion;
+
+    const state = {
+      installedVersion,
+      packageVersion,
+      aiTools,
+      projectType,
+      customAgents,
+      customCommands,
+      settingsLocal,
+    };
+
+    runUpgradeDiffReport(config, state);
+  }
+}
+
 main().catch((err) => {
   console.error('\nError:', err.message);
   process.exit(1);

package/lib/diff-generator.js

@@ -0,0 +1,274 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  FRONTEND_AGENTS,
+  BACKEND_AGENTS,
+  TEMPLATE_AGENTS,
+} = require('./config');
+const {
+  adaptBaseStandards,
+  adaptBackendStandards,
+  adaptFrontendStandards,
+} = require('./init-generator');
+const {
+  isStandardModified,
+  getPackageVersion,
+} = require('./upgrade-generator');
+const { formatScanSummary } = require('./init-wizard');
+
+const templateDir = path.join(__dirname, '..', 'template');
+
+/**
+ * Count files recursively in a directory.
+ */
+function countFiles(dir) {
+  if (!fs.existsSync(dir)) return 0;
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      count += countFiles(path.join(dir, entry.name));
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Compute how many agents would be kept after project-type filtering.
+ */
+function countAgents(projectType) {
+  const all = TEMPLATE_AGENTS.length; // 9
+  if (projectType === 'backend') return all - FRONTEND_AGENTS.length;
+  if (projectType === 'frontend') return all - BACKEND_AGENTS.length;
+  return all;
+}
+
+/**
+ * Compute how many standards would be created for a project type.
+ * base + documentation + backend (if not frontend) + frontend (if not backend)
+ */
+function countStandards(projectType) {
+  let count = 2; // base + documentation
+  if (projectType !== 'frontend') count++; // backend
+  if (projectType !== 'backend') count++; // frontend
+  return count;
+}
+
+// ── Init Diff ────────────────────────────────────────────────
+
+function runInitDiffReport(config) {
+  const dest = config.projectDir;
+  const scan = config.scanResult;
+  const projectType = config.projectType;
+  const aiTools = config.aiTools;
+
+  const lines = [];
+  lines.push('\n🔍 SDD DevFlow — Preview (--init)\n');
+
+  // Detected stack
+  lines.push('  Detected stack:');
+  lines.push(formatScanSummary(scan));
+  lines.push('');
+
+  // Compute what would be created
+  const wouldCreate = [];
+
+  // AI tool directories
+  const agentCount = countAgents(projectType);
+  const removedAgents = TEMPLATE_AGENTS.length - agentCount;
+
+  if (aiTools !== 'gemini') {
+    const claudeSkills = countFiles(path.join(templateDir, '.claude', 'skills'));
+    wouldCreate.push(`  .claude/agents/             ${agentCount} agents${removedAgents > 0 ? ` (${removedAgents} removed: ${projectType}-only)` : ''}`);
+    wouldCreate.push(`  .claude/skills/             ${claudeSkills} files (4 skills)`);
+    wouldCreate.push('  .claude/hooks/              quick-scan.sh');
+    wouldCreate.push('  .claude/settings.json');
+    wouldCreate.push('  .claude/commands/           .gitkeep');
+  }
+
+  if (aiTools !== 'claude') {
+    const geminiSkills = countFiles(path.join(templateDir, '.gemini', 'skills'));
+    const geminiCmds = countFiles(path.join(templateDir, '.gemini', 'commands'));
+    wouldCreate.push(`  .gemini/agents/             ${agentCount} agents${removedAgents > 0 ? ` (${removedAgents} removed: ${projectType}-only)` : ''}`);
+    wouldCreate.push(`  .gemini/skills/             ${geminiSkills} files (4 skills)`);
+    wouldCreate.push(`  .gemini/commands/           ${geminiCmds} commands`);
+    wouldCreate.push('  .gemini/styles/             default.md');
+    wouldCreate.push('  .gemini/settings.json');
+  }
+
+  // Standards
+  const stdCount = countStandards(projectType);
+  const stdDetails = ['base-standards'];
+  if (projectType !== 'frontend') stdDetails.push('backend-standards');
+  if (projectType !== 'backend') stdDetails.push('frontend-standards');
+  stdDetails.push('documentation-standards');
+  wouldCreate.push(`  ai-specs/specs/             ${stdCount} standards (${stdDetails.join(', ')})`);
+
+  // Docs
+  wouldCreate.push('  docs/project_notes/         4 files (bugs, decisions, key_facts, product-tracker)');
+  const specFiles = [];
+  if (projectType !== 'frontend') specFiles.push('api-spec.yaml');
+  if (projectType !== 'backend') specFiles.push('ui-components.md');
+  if (specFiles.length > 0) {
+    wouldCreate.push(`  docs/specs/                 ${specFiles.join(', ')}`);
+  }
+  wouldCreate.push('  docs/tickets/               .gitkeep');
+
+  // Top-level files
+  wouldCreate.push('  AGENTS.md');
+  if (aiTools !== 'gemini') wouldCreate.push('  CLAUDE.md');
+  if (aiTools !== 'claude') wouldCreate.push('  GEMINI.md');
+  wouldCreate.push('  .env.example');
+  wouldCreate.push('  .github/workflows/ci.yml');
+  wouldCreate.push('  .sdd-version');
+
+  lines.push(`  Would create (${wouldCreate.length} items):`);
+  for (const item of wouldCreate) {
+    lines.push(`    + ${item.trim()}`);
+  }
+
+  // .gitignore handling
+  const gitignorePath = path.join(dest, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    lines.push('\n  Would modify:');
+    lines.push('    ~ .gitignore                append SDD entries');
+  } else {
+    lines.push('\n  Would create:');
+    lines.push('    + .gitignore                with SDD entries');
+  }
+
+  lines.push('\n  No files deleted. Run without --diff to apply.\n');
+
+  console.log(lines.join('\n'));
+}
+
+// ── Upgrade Diff ─────────────────────────────────────────────
+
+function runUpgradeDiffReport(config, state) {
+  const dest = config.projectDir;
+  const scan = config.scanResult;
+  const projectType = config.projectType;
+  const aiTools = config.aiTools;
+
+  const lines = [];
+  lines.push('\n🔍 SDD DevFlow — Preview (--upgrade)\n');
+  lines.push(`  ${state.installedVersion} → ${state.packageVersion}\n`);
+
+  // Would replace
+  const replaceItems = [];
+
+  if (aiTools !== 'gemini') {
+    const agentCount = countAgents(projectType);
+    replaceItems.push(`.claude/agents/             ${agentCount} agents`);
+    replaceItems.push('.claude/skills/             4 skills');
+    replaceItems.push('.claude/hooks/              quick-scan.sh');
+    replaceItems.push('.claude/settings.json       hooks updated, permissions preserved');
+  }
+  if (aiTools !== 'claude') {
+    const agentCount = countAgents(projectType);
+    replaceItems.push(`.gemini/agents/             ${agentCount} agents`);
+    replaceItems.push('.gemini/skills/             4 skills');
+    replaceItems.push('.gemini/commands/           TOML commands');
+    replaceItems.push('.gemini/styles/             default.md');
+    replaceItems.push('.gemini/settings.json');
+  }
+  replaceItems.push('AGENTS.md');
+  if (aiTools !== 'gemini') replaceItems.push('CLAUDE.md');
+  if (aiTools !== 'claude') replaceItems.push('GEMINI.md');
+  replaceItems.push('.env.example                custom vars preserved');
+  replaceItems.push('.sdd-version');
+
+  lines.push(`  Would replace (${replaceItems.length} items):`);
+  for (const item of replaceItems) {
+    lines.push(`    ✓ ${item}`);
+  }
+
+  // Would preserve
+  const preserveItems = [];
+  if (state.settingsLocal) preserveItems.push('.claude/settings.local.json   personal settings');
+  for (const c of state.customCommands) preserveItems.push(`${c.relativePath}   custom command`);
+  for (const a of state.customAgents) preserveItems.push(`${a.relativePath}   custom agent`);
+  preserveItems.push('docs/project_notes/*          project memory');
+  preserveItems.push('docs/specs/*                  your specs');
+  preserveItems.push('docs/tickets/*                your tickets');
+  preserveItems.push('.gitignore');
+
+  lines.push(`\n  Would preserve (${preserveItems.length} items):`);
+  for (const item of preserveItems) {
+    lines.push(`    ⊘ ${item}`);
+  }
+
+  // Standards diff
+  const standardsStatus = [];
+
+  const baseStdPath = path.join(dest, 'ai-specs', 'specs', 'base-standards.mdc');
+  if (fs.existsSync(baseStdPath)) {
+    const existing = fs.readFileSync(baseStdPath, 'utf8');
+    const template = fs.readFileSync(path.join(templateDir, 'ai-specs', 'specs', 'base-standards.mdc'), 'utf8');
+    const fresh = adaptBaseStandards(template, scan, config);
+    standardsStatus.push({
+      name: 'base-standards.mdc',
+      modified: isStandardModified(existing, fresh),
+    });
+  }
+
+  if (projectType !== 'frontend') {
+    const backendStdPath = path.join(dest, 'ai-specs', 'specs', 'backend-standards.mdc');
+    if (fs.existsSync(backendStdPath)) {
+      const existing = fs.readFileSync(backendStdPath, 'utf8');
+      const template = fs.readFileSync(path.join(templateDir, 'ai-specs', 'specs', 'backend-standards.mdc'), 'utf8');
+      const fresh = adaptBackendStandards(template, scan);
+      standardsStatus.push({
+        name: 'backend-standards.mdc',
+        modified: isStandardModified(existing, fresh),
+      });
+    }
+  }
+
+  if (projectType !== 'backend') {
+    const frontendStdPath = path.join(dest, 'ai-specs', 'specs', 'frontend-standards.mdc');
+    if (fs.existsSync(frontendStdPath)) {
+      const existing = fs.readFileSync(frontendStdPath, 'utf8');
+      const template = fs.readFileSync(path.join(templateDir, 'ai-specs', 'specs', 'frontend-standards.mdc'), 'utf8');
+      const fresh = adaptFrontendStandards(template, scan);
+      standardsStatus.push({
+        name: 'frontend-standards.mdc',
+        modified: isStandardModified(existing, fresh),
+      });
+    }
+  }
+
+  standardsStatus.push({ name: 'documentation-standards.mdc', modified: false });
+
+  lines.push('\n  Standards:');
+  for (const s of standardsStatus) {
+    if (s.modified) {
+      lines.push(`    ⚠ ${s.name}  customized → preserve`);
+    } else {
+      lines.push(`    ✓ ${s.name}  unchanged → update`);
+    }
+  }
+
+  // Would add (new files)
+  const addItems = [];
+  const ciPath = path.join(dest, '.github', 'workflows', 'ci.yml');
+  if (!fs.existsSync(ciPath)) {
+    addItems.push('.github/workflows/ci.yml');
+  }
+
+  if (addItems.length > 0) {
+    lines.push(`\n  Would add (${addItems.length} new):`);
+    for (const item of addItems) {
+      lines.push(`    + ${item}`);
+    }
+  }
+
+  lines.push('\n  Run without --diff to apply.\n');
+
+  console.log(lines.join('\n'));
+}
+
+module.exports = { runInitDiffReport, runUpgradeDiffReport };

package/lib/init-wizard.js

@@ -283,4 +283,4 @@ function buildInitDefaultConfig(scanResult) {
   return config;
 }
 
-module.exports = { runInitWizard, buildInitDefaultConfig };
+module.exports = { runInitWizard, buildInitDefaultConfig, formatScanSummary };

package/lib/upgrade-generator.js

@@ -512,5 +512,6 @@ module.exports = {
   readAutonomyLevel,
   collectCustomAgents,
   collectCustomCommands,
+  isStandardModified,
   buildSummary,
 };

package/package.json

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