create-harness-vibe-coding 0.1.8 → 0.1.10

package/README.md

@@ -130,6 +130,35 @@ my-project/
 npx create-harness-vibe-coding@latest
 ```
 
+### Existing Project
+
+The scaffold is designed to be added to an existing repository without silently replacing project files.
+
+```bash
+# Preview the write plan first. No files or directories are created.
+npx create-harness-vibe-coding@latest my-app . -y --dry-run
+
+# Preserve existing files and add only missing harness files.
+npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
+```
+
+By default, conflicts fail before writing. This protects existing `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.gitignore`, docs, and scripts from accidental replacement.
+
+| Conflict mode | Meaning | Risk |
+|---------------|---------|------|
+| `fail` | Default. Stop if a target file already exists. | Safest for existing projects; requires a follow-up decision. |
+| `skip` | Keep existing files and create only missing files. | Existing docs may need manual links to new harness docs or workflows. |
+| `backup` | Rename the existing file to `<name>.harness-backup`, then write the scaffold file. | Review backups before deleting; repeated runs may need cleanup. |
+| `overwrite` | Replace existing files with scaffold versions. | Destructive. Use only after reviewing `--dry-run` output or with explicit approval. |
+
+Recommended bootstrap for agents:
+
+```bash
+node bin/create-harness-vibe-coding.js my-app . -y --dry-run
+node bin/create-harness-vibe-coding.js my-app . -y --on-conflict skip
+node scripts/validate-harness.mjs
+```
+
 ### Agent / CI/CD
 
 Agents and automation can skip all prompts with `-y`:
@@ -143,16 +172,81 @@ npx create-harness-vibe-coding@latest my-app -y
 
 # Named project, explicit directory
 npx create-harness-vibe-coding@latest my-app ./dist/my-app -y
+
+# CI-safe existing-project preview
+npx create-harness-vibe-coding@latest my-app . -y --dry-run
+
+# CI-safe existing-project add without replacing files
+npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
 ```
 
 | Flag | Purpose |
 |------|---------|
 | `-y`, `--yes` | Skip all prompts. Uses positional args or defaults. |
+| `--dry-run` | Print the planned creates, skips, backups, overwrites, and conflicts without writing. |
+| `--on-conflict <mode>` | Choose `fail`, `skip`, `backup`, or `overwrite` when files already exist. |
+| `--list-options` | Print the optional workflow catalog and presets. |
+| `--with <ids>` | Add optional workflows by comma-separated id. |
+| `--without <ids>` | Remove optional workflows selected by `--preset` or `--with`. |
+| `--preset <name>` | Add a named workflow preset such as `web-app` or `fullstack`. |
 | `-h`, `--help` | Print usage and exit. |
 
 > [!TIP]
 > Agents should always pass `-y` to avoid hanging on interactive prompts.
-> If the agent needs to discover the CLI surface first, run with `--help`.
+> If the agent needs to discover the CLI surface first, run with `--help` and `--list-options`.
+
+### Optional Workflows
+
+Optional workflows are local template assets selected explicitly at generation time. They do not install package dependencies or fetch a remote marketplace.
+
+```bash
+# Show available optional workflow ids and presets
+npx create-harness-vibe-coding@latest --list-options
+
+# Add individual workflows
+npx create-harness-vibe-coding@latest my-app -y --with browser-e2e,ts-react-frontend
+
+# Add a preset for common web app work
+npx create-harness-vibe-coding@latest my-app -y --preset web-app
+
+# Add a broader frontend/backend/PR-review preset
+npx create-harness-vibe-coding@latest my-app -y --preset fullstack
+
+# Trim a preset without restating every selected workflow
+npx create-harness-vibe-coding@latest my-app -y --preset fullstack --without github-pr-review
+```
+
+Built-in optional workflow ids:
+
+| Workflow | Use when |
+|----------|----------|
+| `browser-e2e` | Browser smoke tests, screenshots, traces, and UI evidence. |
+| `ui-ux-review` | Screenshot-driven responsive, accessibility, and polish review. |
+| `github-pr-review` | PR diff, checks, review findings, and CI evidence. |
+| `python-backend` | Python API/backend work with unittest or pytest verification. |
+| `ts-react-frontend` | TypeScript React work with typecheck, component tests, build, and browser smoke. |
+
+Presets:
+
+| Preset | Includes |
+|--------|----------|
+| `web-app` | `ts-react-frontend`, `browser-e2e`, `ui-ux-review` |
+| `fullstack` | `ts-react-frontend`, `python-backend`, `browser-e2e`, `github-pr-review` |
+
+### Verification
+
+```bash
+# Run repository tests
+npm test
+
+# Confirm optional workflow catalog output
+node bin/create-harness-vibe-coding.js --list-options
+
+# After generating a project, validate the harness from that project root
+node scripts/validate-harness.mjs
+```
+
+The harness validator checks scaffold consistency. It is not a full React, Playwright, Chrome DevTools Protocol, or browser matrix test suite.
 
 ### After scaffolding, tell Claude:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {
@@ -12,7 +12,10 @@
     "templates/"
   ],
   "scripts": {
-    "start": "node src/index.js"
+    "start": "node src/index.js",
+    "test": "node --test tests/*.test.js",
+    "test:smoke": "node --test tests/cli-smoke.test.js",
+    "pack:smoke": "node --test tests/pack-smoke.test.js"
   },
   "dependencies": {
     "@clack/prompts": "^0.7.0",

package/src/generator.js

@@ -1,36 +1,28 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import pc from 'picocolors';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates', 'common');
+const OPTIONAL_DIR = path.resolve(__dirname, '..', 'templates', 'optional');
+const OPTIONAL_CATALOG = path.join(OPTIONAL_DIR, 'catalog.json');
+const VALID_CONFLICT_POLICIES = new Set(['fail', 'skip', 'backup', 'overwrite']);
+const EMPTY_DIRS = [
+  '.claude/hooks',
+  'tests',
+];
 
 /**
- * Copy a directory recursively, replacing {{vars}} in file contents.
+ * Replace {{vars}} in file contents.
  */
-function copyDir(src, dest, vars) {
-  fs.mkdirSync(dest, { recursive: true });
+function renderTemplate(src, vars) {
+  let content = fs.readFileSync(src, 'utf-8');
 
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-
-    if (entry.isDirectory()) {
-      copyDir(srcPath, destPath, vars);
-    } else {
-      let content = fs.readFileSync(srcPath, 'utf-8');
-
-      // Replace template variables
-      for (const [key, value] of Object.entries(vars)) {
-        content = content.replaceAll(`{{${key}}}`, value);
-      }
-
-      fs.writeFileSync(destPath, content, 'utf-8');
-    }
+  for (const [key, value] of Object.entries(vars)) {
+    content = content.replaceAll(`{{${key}}}`, value);
   }
+
+  return content;
 }
 
 /**
@@ -52,53 +44,355 @@ function walkFiles(dir, base = dir) {
   return results;
 }
 
-export function generate({ projectName, targetDir }) {
+function normalizePath(filePath) {
+  return filePath.replace(/\\/g, '/');
+}
+
+export function getOptionalCatalog() {
+  if (!fs.existsSync(OPTIONAL_CATALOG)) {
+    return { skills: [], presets: {} };
+  }
+
+  return JSON.parse(fs.readFileSync(OPTIONAL_CATALOG, 'utf-8'));
+}
+
+function normalizeOptionList(value) {
+  const values = Array.isArray(value) ? value : [value];
+  return values
+    .filter(Boolean)
+    .flatMap(item => String(item).split(','))
+    .map(item => item.trim())
+    .filter(Boolean);
+}
+
+function resolveOptionalSelection({ withOptions = [], withoutOptions = [], preset = undefined }) {
+  const catalog = getOptionalCatalog();
+  const skillsById = new Map(catalog.skills.map(skill => [skill.id, skill]));
+  const selected = [];
+  const errors = [];
+
+  if (preset) {
+    if (!catalog.presets[preset]) {
+      errors.push(`Unknown preset "${preset}". Run --list-options to see available presets.`);
+    } else {
+      selected.push(...catalog.presets[preset]);
+    }
+  }
+
+  selected.push(...normalizeOptionList(withOptions));
+
+  const ids = [...new Set(selected)];
+  const withoutIds = [...new Set(normalizeOptionList(withoutOptions))];
+  for (const id of ids) {
+    if (!skillsById.has(id)) {
+      errors.push(`Unknown optional skill "${id}". Run --list-options to see available options.`);
+    }
+  }
+  for (const id of withoutIds) {
+    if (!skillsById.has(id)) {
+      errors.push(`Unknown optional skill in --without "${id}". Run --list-options to see available options.`);
+    }
+  }
+
+  const withoutSet = new Set(withoutIds);
+  const selectedIds = ids.filter(id => !withoutSet.has(id));
+
+  return {
+    catalog,
+    selectedSkills: errors.length ? [] : selectedIds.map(id => skillsById.get(id)),
+    errors,
+  };
+}
+
+function createCoreFileSpecs() {
+  const specs = walkFiles(TEMPLATES_DIR)
+    .map(file => normalizePath(file))
+    .sort()
+    .map(file => ({
+      dest: file,
+      src: path.join(TEMPLATES_DIR, ...file.split('/')),
+      type: 'common',
+    }));
+
+  specs.push({ dest: 'tests/.gitkeep', src: undefined, type: 'empty' });
+  return specs;
+}
+
+function createOptionalFileSpecs(selectedSkills) {
+  const specs = [];
+
+  for (const skill of selectedSkills) {
+    for (const fileRoot of skill.files) {
+      const absRoot = path.join(OPTIONAL_DIR, ...fileRoot.split('/'));
+      for (const file of walkFiles(absRoot).map(normalizePath).sort()) {
+        specs.push({
+          dest: file,
+          src: path.join(absRoot, ...file.split('/')),
+          type: 'optional',
+          skillId: skill.id,
+        });
+      }
+    }
+  }
+
+  return specs;
+}
+
+function createPlan(resolvedDir, fileSpecs) {
+  const plan = {
+    create: [],
+    skip: [],
+    overwrite: [],
+    backup: [],
+    conflict: [],
+    mkdir: [],
+  };
+
+  const fileSet = new Set(fileSpecs.map(spec => spec.dest));
+
+  const dirSet = new Set(['.']);
+  for (const file of fileSet) {
+    let dir = path.posix.dirname(file);
+    while (dir && dir !== '.') {
+      dirSet.add(dir);
+      dir = path.posix.dirname(dir);
+    }
+  }
+  for (const dir of EMPTY_DIRS) {
+    dirSet.add(dir);
+  }
+
+  for (const dir of [...dirSet].sort()) {
+    const absDir = dir === '.'
+      ? resolvedDir
+      : path.join(resolvedDir, ...dir.split('/'));
+    if (!fs.existsSync(absDir)) {
+      plan.mkdir.push(dir === '.' ? './' : `${dir}/`);
+    }
+  }
+
+  return plan;
+}
+
+function addFileActions(plan, fileSpecs, resolvedDir, onConflict) {
+  for (const { dest: file } of fileSpecs) {
+    const destPath = path.join(resolvedDir, ...file.split('/'));
+
+    if (!fs.existsSync(destPath)) {
+      plan.create.push(file);
+      continue;
+    }
+
+    if (fs.statSync(destPath).isDirectory()) {
+      if (onConflict === 'skip') {
+        plan.skip.push(file);
+      } else {
+        plan.conflict.push(file);
+      }
+      continue;
+    }
+
+    if (onConflict === 'skip') {
+      plan.skip.push(file);
+    } else if (onConflict === 'backup') {
+      plan.backup.push(file);
+    } else if (onConflict === 'overwrite') {
+      plan.overwrite.push(file);
+    } else {
+      plan.conflict.push(file);
+    }
+  }
+}
+
+function createSummary(plan, { noWrites = false } = {}) {
+  return {
+    created: noWrites ? 0 : plan.create.length,
+    skipped: noWrites ? 0 : plan.skip.length,
+    overwritten: noWrites ? 0 : plan.overwrite.length,
+    backedUp: noWrites ? 0 : plan.backup.length,
+    conflicts: plan.conflict.length,
+    mkdir: noWrites ? 0 : plan.mkdir.length,
+  };
+}
+
+function nextBackupPath(destPath) {
+  const first = `${destPath}.harness-backup`;
+  if (!fs.existsSync(first)) {
+    return first;
+  }
+
+  for (let index = 1; ; index += 1) {
+    const candidate = `${first}.${index}`;
+    if (!fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+}
+
+function registerOptionalContent(file, content, selectedSkills) {
+  if (!selectedSkills.length) return content;
+
+  if (file === 'MEMORY.md') {
+    const lines = selectedSkills.map(skill => (
+      `- [${skill.id}](.claude/skills/${skill.id}/SKILL.md) - ${skill.description} Workflow: docs/workflows/${skill.id}.md`
+    ));
+    return content.replace(
+      'Stack-specific skills can be added after the product shape is known.',
+      `Installed optional skills:\n\n${lines.join('\n')}\n\nStack-specific skills can be added after the product shape is known.`,
+    );
+  }
+
+  if (file === 'docs/README.md') {
+    const lines = selectedSkills.map(skill => (
+      `- [${skill.title}](workflows/${skill.id}.md) - ${skill.description}`
+    ));
+    return `${content.trimEnd()}\n\n## Installed Optional Workflows\n\n${lines.join('\n')}\n`;
+  }
+
+  return content;
+}
+
+function registrationWarnings(plan, selectedSkills) {
+  if (!selectedSkills.length) return [];
+
+  const warnings = [];
+  if (plan.skip.includes('MEMORY.md')) {
+    warnings.push('MEMORY.md was skipped; manually register selected optional skills under #Skills.');
+  }
+  if (plan.skip.includes('docs/README.md')) {
+    warnings.push('docs/README.md was skipped; manually register selected optional workflow paths.');
+  }
+
+  return warnings;
+}
+
+export function generate({
+  projectName,
+  targetDir,
+  dryRun = false,
+  onConflict = 'fail',
+  withOptions = [],
+  withoutOptions = [],
+  preset = undefined,
+}) {
   const created = [];
   const errors = [];
+  const warnings = [];
 
   // Resolve targetDir relative to cwd
   const resolvedDir = path.resolve(process.cwd(), targetDir);
+  const vars = { projectName };
 
-  // Check if target exists and is non-empty
-  if (fs.existsSync(resolvedDir)) {
-    const existing = fs.readdirSync(resolvedDir).filter(f => f !== '.git');
-    if (existing.length > 0) {
-      console.log(pc.yellow(`Directory "${targetDir}" already exists and is not empty. Files may be overwritten.`));
-    }
+  const optional = resolveOptionalSelection({ withOptions, withoutOptions, preset });
+  const fileSpecs = [
+    ...createCoreFileSpecs(),
+    ...createOptionalFileSpecs(optional.selectedSkills),
+  ];
+  const specsByDest = new Map(fileSpecs.map(spec => [spec.dest, spec]));
+  const plan = createPlan(resolvedDir, fileSpecs);
+
+  if (!VALID_CONFLICT_POLICIES.has(onConflict)) {
+    errors.push(`Unknown conflict policy "${onConflict}". Use fail, skip, backup, or overwrite.`);
+    return {
+      success: false,
+      created,
+      errors,
+      plan,
+      summary: createSummary(plan, { noWrites: true }),
+      warnings,
+    };
   }
 
-  const vars = { projectName };
+  if (optional.errors.length > 0) {
+    errors.push(...optional.errors);
+    return {
+      success: false,
+      created,
+      errors,
+      plan,
+      summary: createSummary(plan, { noWrites: true }),
+      warnings,
+    };
+  }
 
-  try {
-    // 1. Copy all template files
-    console.log(pc.cyan('Copying templates...'));
-    copyDir(TEMPLATES_DIR, resolvedDir, vars);
-
-    // List all created files from templates
-    created.push(...walkFiles(TEMPLATES_DIR).map(f => f.replace(/\\/g, '/')));
-
-    // 2. Create empty directories
-    console.log(pc.cyan('Creating placeholder directories...'));
-    const emptyDirs = [
-      '.claude/hooks',
-      'tests',
-    ];
+  addFileActions(plan, fileSpecs, resolvedDir, onConflict);
+  warnings.push(...registrationWarnings(plan, optional.selectedSkills));
+
+  if (dryRun) {
+    return {
+      success: true,
+      created,
+      errors,
+      plan,
+      summary: createSummary(plan),
+      warnings,
+      dryRun: true,
+    };
+  }
 
-    for (const dir of emptyDirs) {
-      const dirPath = path.join(resolvedDir, dir);
+  if (plan.conflict.length > 0) {
+    errors.push(`Generation stopped because ${plan.conflict.length} file conflict(s) were found: ${plan.conflict.join(', ')}`);
+    return {
+      success: false,
+      created,
+      errors,
+      plan,
+      summary: createSummary(plan, { noWrites: true }),
+      warnings,
+    };
+  }
+
+  try {
+    for (const dir of plan.mkdir) {
+      const dirPath = dir === './'
+        ? resolvedDir
+        : path.join(resolvedDir, ...dir.slice(0, -1).split('/'));
       fs.mkdirSync(dirPath, { recursive: true });
-      created.push(`${dir}/ (empty)`);
+      created.push(dir === './' ? './ (directory)' : `${dir} (directory)`);
     }
 
-    // 3. Create .gitkeep in tests/
-    const gitkeepPath = path.join(resolvedDir, 'tests', '.gitkeep');
-    fs.writeFileSync(gitkeepPath, '', 'utf-8');
-    created.push('tests/.gitkeep');
+    for (const file of plan.backup) {
+      const destPath = path.join(resolvedDir, ...file.split('/'));
+      fs.renameSync(destPath, nextBackupPath(destPath));
+    }
+
+    const writableFiles = [
+      ...plan.create,
+      ...plan.overwrite,
+      ...plan.backup,
+    ];
+
+    for (const file of writableFiles) {
+      const spec = specsByDest.get(file);
+      const destPath = path.join(resolvedDir, ...file.split('/'));
+      let content = spec.type === 'empty'
+        ? ''
+        : renderTemplate(spec.src, vars);
+      content = registerOptionalContent(file, content, optional.selectedSkills);
+
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.writeFileSync(destPath, content, 'utf-8');
+      created.push(file);
+    }
 
-    return { success: true, created, errors };
+    return {
+      success: true,
+      created,
+      errors,
+      plan,
+      summary: createSummary(plan),
+      warnings,
+    };
 
   } catch (err) {
     errors.push(err.message);
-    return { success: false, created, errors };
+    return {
+      success: false,
+      created,
+      errors,
+      plan,
+      summary: createSummary(plan),
+      warnings,
+    };
   }
 }