@dzhechkov/p-replicator 1.2.0 → 1.5.2

package/src/commands/verify.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const path = require('path');
+const {
+  green, red, yellow, cyan, bold, dim,
+  info, success, error: logError,
+  readManifest, fileExists,
+  COMPONENTS, getItemRelativePath,
+} = require('../utils');
+
+function run(options) {
+  const { targetDir } = options;
+
+  const manifest = readManifest(targetDir);
+  if (!manifest) {
+    logError('P-Replicator is not installed in this directory.');
+    info(`Run ${cyan('npx @dzhechkov/p-replicator init')} first.`);
+    process.exit(1);
+  }
+
+  let issues = 0;
+  let warnings = 0;
+
+  function pass(msg) { console.log(`  ${green('✓')} ${msg}`); }
+  function fail(msg) { console.log(`  ${red('✗')} ${msg}`); issues++; }
+  function hint(msg) { console.log(`  ${yellow('!')} ${msg}`); warnings++; }
+
+  console.log(bold('P-Replicator — Verify state'));
+  console.log(dim(`Manifest: v${manifest.version}, installed ${manifest.installedAt}`));
+  console.log('');
+
+  // ── Section 1: Pre-shipped (init contract — MUST exist) ─────────────────
+  console.log(bold('Pre-shipped (from p-replicator init):'));
+  console.log('');
+
+  const preShippedGroups = Object.entries(COMPONENTS)
+    .filter(([, c]) => c.kind === 'pre-shipped');
+
+  for (const [groupKey, comp] of preShippedGroups) {
+    for (const [itemKey, desc] of Object.entries(comp.items)) {
+      const rel = getItemRelativePath(comp, itemKey);
+      const full = path.join(targetDir, rel);
+      // Display labels: commands as /name, others as group: name
+      const label = groupKey === 'commands'
+        ? `/${itemKey}`
+        : `${groupKey}: ${itemKey}`;
+      if (fileExists(full)) {
+        pass(`${label} ${dim('— ' + desc)}`);
+      } else {
+        fail(`${label} — missing (${rel})`);
+      }
+    }
+  }
+
+  console.log('');
+
+  // ── Section 2: Post-/replicate (project-generated — advisory) ────────────
+  // Detect: was /replicate run? Heuristic: CLAUDE.md OR feature-roadmap.json present.
+  const replicateRan =
+    fileExists(path.join(targetDir, 'CLAUDE.md')) ||
+    fileExists(path.join(targetDir, '.claude', 'feature-roadmap.json'));
+
+  const projectGroups = Object.entries(COMPONENTS)
+    .filter(([, c]) => c.kind === 'project-generated');
+
+  if (replicateRan) {
+    console.log(bold('Post-/replicate (generated by Phase 3):'));
+    console.log('');
+    for (const [, comp] of projectGroups) {
+      for (const [itemKey, desc] of Object.entries(comp.items)) {
+        const rel = getItemRelativePath(comp, itemKey);
+        const full = path.join(targetDir, rel);
+        if (fileExists(full)) {
+          pass(`${rel} ${dim('— ' + desc)}`);
+        } else {
+          hint(`${rel} ${dim('— ' + desc)} (not found)`);
+        }
+      }
+    }
+  } else {
+    console.log(bold('Post-/replicate:'));
+    console.log(dim('  No /replicate output detected (CLAUDE.md and feature-roadmap.json both absent).'));
+    console.log(dim('  Run /replicate in Claude Code to generate project-specific artifacts.'));
+    console.log('');
+    console.log(dim(`  Expected after /replicate (${projectGroups.reduce((n, [, c]) => n + Object.keys(c.items).length, 0)} artifacts across ${projectGroups.length} groups):`));
+    for (const [groupKey, comp] of projectGroups) {
+      console.log(dim(`    ${groupKey}: ${Object.keys(comp.items).length} items`));
+    }
+  }
+
+  console.log('');
+
+  // ── Summary ─────────────────────────────────────────────────────────────
+  console.log(bold('─'.repeat(60)));
+  if (issues === 0 && warnings === 0) {
+    success(bold('All artifacts verified.'));
+  } else if (issues === 0) {
+    success(`Pre-shipped contract OK (${yellow(warnings + ' post-replicate hint(s)')}).`);
+  } else {
+    logError(`${red(issues + ' issue(s)')} in pre-shipped contract, ${yellow(warnings + ' post-replicate hint(s)')}.`);
+    console.log('');
+    info(`Repair pre-shipped: ${cyan('npx @dzhechkov/p-replicator init --force')}`);
+    info(`Regenerate post-pipeline: run ${cyan('/replicate')} in Claude Code`);
+  }
+  console.log('');
+
+  process.exitCode = issues > 0 ? 1 : 0;
+}
+
+module.exports = run;
+module.exports.run = run;

package/src/utils.js

@@ -207,13 +207,21 @@ function writeManifest(targetDir, data) {
   writeJSON(path.join(targetDir, MANIFEST_FILE), data);
 }
 
-function createManifest(version, components, files) {
-  return {
+function createManifest(version, components, files, shippedDefaults) {
+  const manifest = {
     version: version,
     installedAt: new Date().toISOString(),
     components: components,
     files: files,
   };
+  // shippedDefaults (v1.4.3+): snapshot of files we shipped this install. Used
+  // by next upgrade to detect orphan hooks that have been removed from the
+  // current template. Currently tracks settings.json only (the file most
+  // affected by user customization vs template drift).
+  if (shippedDefaults && Object.keys(shippedDefaults).length > 0) {
+    manifest.shippedDefaults = shippedDefaults;
+  }
+  return manifest;
 }
 
 // ===========================================================================
@@ -231,29 +239,282 @@ function getTemplatesDir() {
 // needed since this is a complete package).
 // ===========================================================================
 
+// items maps are the SINGLE SOURCE OF TRUTH for component names + descriptions.
+// Consumed by: doctor.js (existence checks), list.js (display), cli.js (help counts),
+// verify.js (post-/replicate state check), and is the canonical contract for what
+// the package ships AND what /replicate is expected to generate.
+//
+// `kind: 'pre-shipped'`    — installed by `npx p-replicator init` (must always exist).
+// `kind: 'project-generated'` — created by `/replicate` Phase 3; items keys are full
+//                            relative paths (e.g., '.claude/agents/planner.md').
 const COMPONENTS = {
   skills: {
     src: '.claude/skills',
+    kind: 'pre-shipped',
     label: 'Skills (10 skill packs)',
     group: 'core',
+    items: {
+      'explore':                       'Socratic task clarification',
+      'sparc-prd-mini':                'SPARC documentation generator (11 docs)',
+      'goap-research-ed25519':         'Verified research with Ed25519 anti-hallucination',
+      'problem-solver-enhanced':       'First principles + TRIZ (9 modules)',
+      'requirements-validator':        'INVEST/SMART validation + BDD scenarios',
+      'brutal-honesty-review':         'Unvarnished technical criticism',
+      'cc-toolkit-generator-enhanced': 'Modular toolkit generator (9 modules, ~165K chars)',
+      'reverse-engineering-unicorn':   'Company reverse engineering + playbook',
+      'pipeline-forge':                'Meta-skill: build AI pipelines from patterns',
+      'knowledge-extractor':           'Extract reusable knowledge from projects',
+    },
   },
   commands: {
     src: '.claude/commands',
-    label: 'Commands (/replicate, /harvest)',
+    kind: 'pre-shipped',
+    label: 'Commands (orchestration + workflow)',
     group: 'core',
+    items: {
+      'replicate':  'Full pipeline: idea → validated docs → toolkit',
+      'harvest':    'Knowledge extraction from projects',
+      'start':      'Bootstrap project from SPARC docs (monorepo + Docker)',
+      'plan':       'Lightweight planning to docs/plans/ (auto-commit)',
+      'feature':    'Full SPARC-mini lifecycle (PLAN → VALIDATE → IMPLEMENT → REVIEW)',
+      'go':         'Intelligent pipeline router (delegates to /plan or /feature)',
+      'run':        'Autonomous build loop: /next → /go → repeat',
+      'next':       'Pick next feature from .claude/feature-roadmap.json',
+      'docs':       'Bilingual documentation generator (RU/EN)',
+      'deploy':     'Deployment workflow (dev / staging / prod)',
+      'myinsights': 'Capture and recall development insights',
+    },
   },
   agents: {
     src: '.claude/agents',
+    kind: 'pre-shipped',
     label: 'Agents (4 orchestrators)',
     group: 'core',
+    items: {
+      'replicate-coordinator': 'Pipeline orchestration (Phases 0-4)',
+      'product-discoverer':    'Market research (Phase 0)',
+      'doc-validator':         'Documentation validation swarm (Phase 2)',
+      'harvest-coordinator':   'Knowledge extraction swarm',
+    },
   },
   rules: {
     src: '.claude/rules',
-    label: 'Rules (pipeline constraints)',
+    kind: 'pre-shipped',
+    label: 'Rules (pipeline + workflow constraints)',
+    group: 'core',
+    items: {
+      'replicate-pipeline':       'Phase sequence, output paths, git discipline, modular skill loading',
+      'skill-interface-protocol': 'view() contract, module interface, maturity tagging, composition rules',
+      'git-workflow':             'Commit/push discipline, branch strategy, semantic messages',
+      'insights-capture':         'When and how to capture development insights to knowledge base',
+      'feature-lifecycle':        '/feature phases (PLAN → VALIDATE → IMPLEMENT → REVIEW), checkpoints, scoring',
+    },
+  },
+  settings: {
+    src: '.claude/settings.json',
+    kind: 'pre-shipped',
+    label: 'Hooks config (settings.json)',
     group: 'core',
+    isFile: true,
+    items: {
+      'settings.json': 'SessionStart insight injection + Stop auto-commit (roadmap, insights, plans)',
+    },
+  },
+  hooks: {
+    src: '.claude/hooks',
+    kind: 'pre-shipped',
+    label: 'Hook scripts (cross-platform Node)',
+    group: 'core',
+    items: {
+      'session-insights':    'Inject 3 most recent insights into Claude session context',
+      'autocommit-roadmap':  'Auto-commit .claude/feature-roadmap.json on Stop hook',
+      'autocommit-insights': 'Auto-commit .claude/insights/ on Stop hook',
+      'autocommit-plans':    'Auto-commit docs/plans/ on Stop hook',
+      'statusline':          'Multi-line dashboard (pipeline, roadmap, toolkit) for Claude Code statusLine',
+      'state-update':        'Argv-driven helper for pipeline commands to publish current command + phase + progress',
+    },
+  },
+  // ─── Project-generated groups (created by /replicate Phase 3) ───────────
+  // items keys are FULL relative paths (e.g., '.claude/agents/planner.md').
+  // Used by verify.js to report post-/replicate state; doctor.js does NOT
+  // assert their presence (advisory hints only).
+  projectAgents: {
+    kind: 'project-generated',
+    label: 'Project-specific agents (Phase 3 generated from SPARC)',
+    group: 'project',
+    items: {
+      '.claude/agents/planner.md':       'Feature planning with algorithm templates from Pseudocode.md',
+      '.claude/agents/code-reviewer.md': 'Quality review with edge cases from Refinement.md',
+      '.claude/agents/architect.md':     'System design from Architecture.md + Solution_Strategy.md',
+    },
+  },
+  projectRules: {
+    kind: 'project-generated',
+    label: 'Project-specific rules (Phase 3 generated from NFRs/tech stack)',
+    group: 'project',
+    items: {
+      '.claude/rules/security.md':     'NFRs from Specification.md',
+      '.claude/rules/coding-style.md': 'Conventions from Architecture.md tech stack',
+      '.claude/rules/testing.md':      'Test strategy from Refinement.md',
+    },
+  },
+  projectFiles: {
+    kind: 'project-generated',
+    label: 'Project files (Phase 3 generated)',
+    group: 'project',
+    items: {
+      'CLAUDE.md':                      'Project context (root)',
+      '.claude/feature-roadmap.json':   'Feature list (used by /run, /next)',
+      'DEVELOPMENT_GUIDE.md':           'Step-by-step dev lifecycle',
+      'docker-compose.yml':             'Container orchestration scaffold',
+    },
   },
 };
 
+// ---------------------------------------------------------------------------
+// Path derivation: maps a component + item key to its on-disk relative path.
+// Centralizes the "where do we find item X of group Y" logic so doctor/verify/list
+// don't each re-implement it.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// settings.json merge (v1.4.2): preserve user customizations on `init --force`.
+// Algorithm: deep-merge top-level fields (template fills only what user lacks),
+// per-event-type merge for hooks, per-matcher merge for hook arrays, de-dup by
+// command string. Use `--reset-settings` flag for explicit overwrite.
+// ---------------------------------------------------------------------------
+
+function mergeSettingsJson(existing, template) {
+  if (!existing) return template;
+  if (!template) return existing;
+
+  const merged = { ...existing };
+
+  // Top-level: add template fields that user doesn't have. Don't overwrite.
+  for (const [key, value] of Object.entries(template)) {
+    if (!(key in merged)) merged[key] = value;
+  }
+
+  // Special: hooks need structural merge.
+  if (template.hooks) {
+    merged.hooks = mergeHookEvents(existing.hooks || {}, template.hooks);
+  }
+
+  return merged;
+}
+
+function mergeHookEvents(existing, template) {
+  const merged = { ...existing };
+  for (const eventType of Object.keys(template)) {
+    if (!merged[eventType]) {
+      merged[eventType] = template[eventType];
+    } else {
+      merged[eventType] = mergeHookMatchers(merged[eventType], template[eventType]);
+    }
+  }
+  return merged;
+}
+
+// ---------------------------------------------------------------------------
+// removeOrphanHooks (v1.4.3): orphan detection on upgrade.
+// "Orphan" = a hook command that WAS shipped by the package previously
+// (in oldTemplate from manifest.shippedDefaults) but is NO LONGER in the
+// current template. Such hooks should be removed from user's settings on
+// upgrade — otherwise they linger forever, calling broken/missing scripts.
+//
+// Identity model: hooks are compared by their `command` string. User-modified
+// commands have a different string and are treated as user-added (preserved).
+// User-added commands (never in oldTemplate) are also preserved.
+// ---------------------------------------------------------------------------
+
+function extractCommands(hooksRoot) {
+  const cmds = new Set();
+  if (!hooksRoot || !hooksRoot.hooks) return cmds;
+  for (const eventEntries of Object.values(hooksRoot.hooks)) {
+    if (!Array.isArray(eventEntries)) continue;
+    for (const matcher of eventEntries) {
+      for (const h of (matcher.hooks || [])) {
+        if (h && typeof h.command === 'string') cmds.add(h.command);
+      }
+    }
+  }
+  return cmds;
+}
+
+function removeOrphanHooks(existing, oldTemplate, newTemplate) {
+  // First-upgrade case: no baseline → can't detect orphans. Pass-through.
+  if (!oldTemplate || !existing) return existing;
+
+  const oldCmds = extractCommands(oldTemplate);
+  const newCmds = extractCommands(newTemplate);
+
+  // Orphans: shipped previously, no longer shipped.
+  const orphanCmds = new Set();
+  for (const cmd of oldCmds) {
+    if (!newCmds.has(cmd)) orphanCmds.add(cmd);
+  }
+  if (orphanCmds.size === 0) return existing;
+
+  // Deep-clone existing while filtering out orphan commands.
+  const cleaned = { ...existing };
+  if (existing.hooks) {
+    cleaned.hooks = {};
+    for (const [eventType, entries] of Object.entries(existing.hooks)) {
+      if (!Array.isArray(entries)) {
+        cleaned.hooks[eventType] = entries;
+        continue;
+      }
+      cleaned.hooks[eventType] = entries.map((matcher) => ({
+        ...matcher,
+        hooks: (matcher.hooks || []).filter(
+          (h) => !(h && typeof h.command === 'string' && orphanCmds.has(h.command))
+        ),
+      }));
+    }
+  }
+  return cleaned;
+}
+
+function mergeHookMatchers(existing, template) {
+  // Clone the existing array; we'll mutate per-entry hook arrays via reference.
+  const result = existing.map((m) => ({ ...m, hooks: [...(m.hooks || [])] }));
+  for (const tplEntry of template) {
+    const target = result.find((e) => e.matcher === tplEntry.matcher);
+    if (!target) {
+      // New matcher — keep it as-is
+      result.push({ ...tplEntry, hooks: [...(tplEntry.hooks || [])] });
+      continue;
+    }
+    // Same matcher — append template hooks not already present (compare by command)
+    const existingCmds = new Set(target.hooks.map((h) => h.command));
+    for (const tplHook of tplEntry.hooks || []) {
+      if (!existingCmds.has(tplHook.command)) {
+        target.hooks.push(tplHook);
+      }
+    }
+  }
+  return result;
+}
+
+function getItemRelativePath(comp, itemKey) {
+  // Single-file components (settings.json)
+  if (comp.isFile) return comp.src;
+
+  // Project-generated: items keys ARE full relative paths
+  if (comp.kind === 'project-generated') return itemKey;
+
+  // Pre-shipped multi-file groups
+  if (comp.src === '.claude/skills') {
+    return path.join(comp.src, itemKey, 'SKILL.md');
+  }
+  // Hook scripts have .cjs extension
+  if (comp.src === '.claude/hooks') {
+    return path.join(comp.src, itemKey + '.cjs');
+  }
+  // commands / rules / agents are plain .md
+  return path.join(comp.src, itemKey + '.md');
+}
+
 // ===========================================================================
 // Exports
 // ===========================================================================
@@ -277,4 +538,14 @@ module.exports = {
 
   // Components
   COMPONENTS,
+  getItemRelativePath,
+
+  // Settings merge (v1.4.2)
+  mergeSettingsJson,
+  mergeHookEvents,
+  mergeHookMatchers,
+
+  // Orphan detection (v1.4.3)
+  removeOrphanHooks,
+  extractCommands,
 };

package/templates/.claude/commands/deploy.md

@@ -0,0 +1,100 @@
+---
+description: Guide deployment to dev/staging/prod environments. Reads pre-deployment checklist from docs/Completion.md, runs gating checks per environment tier, executes deployment, and verifies post-deploy health.
+argument-hint: '<dev | staging | prod>'
+---
+
+# /deploy $ARGUMENTS
+
+## Purpose
+
+Structured deployment workflow with environment-specific gates.
+
+## Environment Tiers
+
+| Tier | Confirmation | Checks | Auto-rollback |
+|------|--------------|--------|---------------|
+| `dev` | None — auto | Tests pass, build succeeds | No |
+| `staging` | Implicit (after gate checks) | Tests + lint + smoke + health | Yes |
+| `prod` | Explicit `yes` typed | All staging + manual review | Yes |
+
+## Process
+
+### Step 1: Determine Target
+
+Parse `$ARGUMENTS`: `dev` (default) | `staging` | `prod`. Halt on invalid.
+
+### Step 2: Read Pre-Deploy Checklist
+
+From `docs/Completion.md`: env vars, external services, migrations, smoke tests, rollback procedure.
+
+### Step 3: Gate Checks (per tier)
+
+```
+ALL TIERS:
+  ✓ git status clean
+  ✓ on main/master
+  ✓ tests passing: npm test
+  ✓ build succeeds: npm run build
+  ✓ lint clean
+
+STAGING + PROD:
+  ✓ all .env.<tier> vars set
+  ✓ external services reachable (DB, Redis)
+  ✓ docker images tagged with current commit SHA
+
+PROD ONLY:
+  ✓ staging deploy was successful in last 24h
+  ✓ no open critical issues
+  ✓ on-call notified
+  ✓ rollback plan reviewed
+```
+
+If any gate fails → halt with specific remediation.
+
+### Step 4: Execute Deployment
+
+```bash
+docker build -t <project>:<commit-sha> .
+docker tag <project>:<commit-sha> <registry>/<project>:<tier>
+docker push <registry>/<project>:<tier>
+docker compose -f docker-compose.<tier>.yml up -d
+<migration-command>
+until curl -f https://<tier-host>/health; do sleep 2; done
+```
+
+### Step 5: Smoke Tests
+
+Run smoke test suite from `docs/Completion.md`.
+
+### Step 6: Confirmation (prod only)
+
+```
+🚨 PROD DEPLOYMENT — confirm
+   Tag: <commit-sha>
+   Migrations: <list>
+   Downtime: <duration>
+   Rollback: <procedure>
+   Type 'yes' to proceed.
+```
+
+### Step 7: Deploy + Monitor (5-15 min)
+
+For prod: progressive rollout (canary → full) if infra supports.
+Monitor: error rate, p95/p99 latency, health endpoint.
+
+### Step 8: Report
+
+```
+✅ Deploy complete
+   Tier: <tier>, Commit: <sha>
+   Migrations: <N>, Smoke: <pass/fail>, Health: <status>
+```
+
+## Rollback
+
+`/deploy <tier> --rollback`: re-deploy previous successful tag, run reverse migrations from Completion.md.
+
+## Related
+
+- `docs/Completion.md` — pre-deploy checklist source
+- `.claude/rules/git-workflow.md` — branch + commit discipline

package/templates/.claude/commands/docs.md

@@ -0,0 +1,79 @@
+---
+description: Generate bilingual project documentation (Russian + English). Creates `README/ru/` and `README/eng/` with admin guide, user guide, API docs, and quick start. Modes: default (both languages), `eng`/`ru` (single), `update` (refresh existing).
+argument-hint: '[eng | ru | update]'
+---
+
+# /docs $ARGUMENTS
+
+## Purpose
+
+Generate user-facing and admin-facing documentation from project artifacts.
+Bilingual by default (Russian + English).
+
+## Modes
+
+| `$ARGUMENTS` | Languages | Mode |
+|--------------|-----------|------|
+| (empty) | RU + EN | Create or replace |
+| `ru` | RU only | Create or replace |
+| `eng` | EN only | Create or replace |
+| `update` | Existing | Update only changed sections |
+
+## Process
+
+### Step 1: Gather Context
+
+Read these sources:
+
+| Source | Used for |
+|--------|----------|
+| `docs/PRD.md` | Product overview, user personas |
+| `docs/Architecture.md` | System design, deployment |
+| `docs/Specification.md` | Feature list, API surface |
+| `CLAUDE.md` | Project context |
+| `.claude/insights/index.md` | Known gotchas, FAQs |
+| Source code | API signatures (top-level routes) |
+| `package.json` | Tech stack, scripts, dependencies |
+
+### Step 2: Generate Per-Language Files
+
+For each target language, write into `README/<lang>/`:
+
+| File | Content |
+|------|---------|
+| `01_quickstart.md` | Install + run in 5 commands |
+| `02_user_guide.md` | End-user workflows |
+| `03_admin_guide.md` | Deployment, monitoring, backup, secrets |
+| `04_api_reference.md` | API endpoints with examples |
+| `05_architecture.md` | High-level architecture (auto from Architecture.md) |
+| `06_troubleshooting.md` | From insights |
+| `07_changelog.md` | From git log |
+| `README.md` | TOC linking to the above |
+
+### Step 3: Cross-Language Consistency
+
+Ensure RU + EN cover identical sections (same numbering, same TOC).
+
+### Step 4: Generate Top-Level Index
+
+Update root `README.md`:
+```markdown
+## Documentation
+- 🇷🇺 [Документация на русском](./README/ru/README.md)
+- 🇬🇧 [English documentation](./README/eng/README.md)
+```
+
+### Step 5: Validate + Commit
+
+- All internal links resolve
+- All code blocks have language tags
+- Commit: `docs: generate bilingual documentation (RU + EN)`
+
+## Update Mode
+
+`/docs update` only regenerates files where source has changed since last run.
+
+## Related
+
+- `/harvest` — extract reusable patterns (different goal)
+- `/myinsights` — fed into troubleshooting section