claudex-setup 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.7.0] - 2026-03-31
+
+### Added
+- `augment` / `suggest-only` repo-aware analysis with strengths, gaps, top actions, risk notes, and rollout order
+- `plan` command for exportable proposal bundles with file previews and diff-style output
+- `apply` command for selective starter-safe apply flows with rollback manifests and activity artifacts
+- `governance` command with permission profiles, hook registry, policy packs, and pilot rollout guidance
+- `benchmark` command that measures before/after impact in an isolated temp copy and exports evidence reports
+- claims governance and pilot rollout docs in `content/`
+
+### Changed
+- `setup` now exposes reusable planning primitives and returns written/preserved file summaries
+- CLI now supports `--out`, `--plan`, `--only`, and `--dry-run`
+- README and docs now reflect the actual product surface instead of only audit/setup flows
+- benchmark and proposal workflows now preserve existing files by default and treat mature repos as review-first
+
 ## [0.2.0] - 2026-03-31
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # claudex-setup
 
-> Score your project 0-100 for Claude Code readiness. Smart CLAUDE.md generator, 63 audit checks, interactive wizard, watch mode, CI action. Never overwrites existing config.
+> Score your project 0-100 for Claude Code readiness. Discover gaps, export proposal bundles, apply safe starter changes with rollback, and benchmark the impact without touching your live repo.
 
 [![npm version](https://img.shields.io/npm/v/claudex-setup)](https://www.npmjs.com/package/claudex-setup)
 [![npm downloads](https://img.shields.io/npm/dm/claudex-setup)](https://www.npmjs.com/package/claudex-setup)
@@ -11,6 +11,10 @@
 ```bash
 npx claudex-setup              # Audit your project (10 seconds)
 npx claudex-setup setup        # Auto-fix everything
+npx claudex-setup augment      # Repo-aware plan, no writes
+npx claudex-setup plan         # Export proposal bundles with file previews
+npx claudex-setup benchmark    # Measure before/after in an isolated temp copy
+npx claudex-setup --threshold 60   # Fail CI if score is below 60
 ```
 
 No install. No config. No dependencies.
@@ -36,12 +40,12 @@ No install. No config. No dependencies.
      CI pipeline configured
      → Add .github/workflows/ for automated testing
 
-  ⚡ Quick wins
-     1. Add LICENSE file
-     2. Add CHANGELOG.md
+  ⚡ Best next fixes
+     1. Add CLAUDE.md verification criteria
+     2. Configure safe permissions + deny rules
 
   Weakest areas:
-     design: none (0/2)
+      design: none (0/2)
      devops: none (0/4)
 
   29/63 checks passing
@@ -52,9 +56,17 @@ No install. No config. No dependencies.
 
 | Command | What it does |
 |---------|-------------|
-| `npx claudex-setup` | **Audit** - Score 0-100 against 63 checks |
-| `npx claudex-setup setup` | **Setup** - Smart CLAUDE.md + hooks + commands + agents |
+| `npx claudex-setup` | **Discover** - Score 0-100 against 63 checks |
+| `npx claudex-setup discover` | **Discover** - Alias for audit mode |
+| `npx claudex-setup setup` | **Starter** - Smart CLAUDE.md + hooks + commands + agents |
+| `npx claudex-setup starter` | **Starter** - Alias for setup mode |
 | `npx claudex-setup setup --auto` | **Auto-setup** - No prompts, apply all |
+| `npx claudex-setup augment` | **Augment** - Repo-aware improvement plan, no writes |
+| `npx claudex-setup suggest-only` | **Suggest-Only** - Structured recommendation report, no writes |
+| `npx claudex-setup plan` | **Plan** - Export proposal bundles with previews, rationale, and file-level changes |
+| `npx claudex-setup apply` | **Apply** - Apply ready proposal bundles with rollback + activity artifacts |
+| `npx claudex-setup governance` | **Governance** - Permission profiles, hook registry, policy packs, pilot kit |
+| `npx claudex-setup benchmark` | **Benchmark** - Before/after evidence from an isolated temp copy |
 | `npx claudex-setup interactive` | **Wizard** - Step-by-step guided tour |
 | `npx claudex-setup watch` | **Watch** - Live monitoring with score delta |
 | `npx claudex-setup badge` | **Badge** - Generate shields.io badge for README |
@@ -65,8 +77,14 @@ No install. No config. No dependencies.
 
 | Flag | Effect |
 |------|--------|
+| `--threshold N` | Exit with code 1 if score is below `N` (great for CI) |
+| `--out FILE` | Write JSON or markdown output to a file |
+| `--plan FILE` | Load a previously exported plan file |
+| `--only A,B` | Limit plan/apply to selected proposal ids |
+| `--dry-run` | Preview apply without writing files |
 | `--verbose` | Show all recommendations (not just critical/high) |
 | `--json` | Machine-readable JSON output (for CI) |
+| `--auto` | Apply setup files without prompts |
 | `--insights` | Enable anonymous usage insights (off by default) |
 
 ## Smart CLAUDE.md Generation
@@ -74,11 +92,75 @@ No install. No config. No dependencies.
 Not a generic template. The `setup` command actually analyzes your project:
 
 - **Reads package.json** - includes your actual test, build, lint, dev commands
+- **Reads pyproject.toml** - uses Python project name/description when package.json does not exist
 - **Detects framework** - Next.js Server Components, Django models, FastAPI Pydantic, React hooks
 - **TypeScript-aware** - detects strict mode, adds TS-specific rules
 - **Auto Mermaid diagram** - scans directories and generates architecture visualization (Mermaid diagrams are more token-efficient than prose descriptions, per Anthropic docs)
 - **XML constraint blocks** - adds `<constraints>` and `<verification>` with context-aware rules
 - **Verification criteria** - auto-generates checklist from your actual commands
+- **Safer settings.json** - generated hooks config now includes `acceptEdits` plus deny rules for dangerous or secret-sensitive operations
+
+## Mode Model
+
+- **Discover**: score the repo, surface critical issues, and show the best next actions
+- **Starter**: generate a safe baseline when the repo has little or no Claude setup
+- **Augment**: inspect the current repo and build a structured improvement plan without writing files
+- **Suggest-Only**: same no-write analysis, optimized for sharing or manual review
+- **Governance**: surface permission profiles, shipped hooks, policy packs, and pilot guidance
+- **Benchmark**: prove value on an isolated copy before touching the real repo
+
+## Proposal + Apply Workflow
+
+Use `plan` when you want a file-by-file proposal bundle before any write happens:
+
+```bash
+npx claudex-setup plan --out claudex-plan.json
+```
+
+Each proposal bundle includes:
+
+- trigger reasons tied to failed checks
+- file previews and diff-style output
+- `create` vs `manual-review` classification
+- risk/confidence labels
+
+Apply only the bundles you want:
+
+```bash
+npx claudex-setup apply --plan claudex-plan.json --only claude-md,hooks
+```
+
+`apply` creates rollback manifests and activity artifacts under `.claude/claudex-setup/`, so every applied batch has a paper trail and a delete-based rollback path.
+
+## Governance And Pilot Readiness
+
+Use `governance` when the question is "can we pilot this safely?" instead of "what files can you generate?".
+
+```bash
+npx claudex-setup governance
+```
+
+It exposes:
+
+- permission profiles: `read-only`, `suggest-only`, `safe-write`, `power-user`, `internal-research`
+- hook registry with trigger point, purpose, side effects, risk, and rollback path
+- policy packs for baseline engineering, security-sensitive repos, OSS, and regulated-lite teams
+- a pilot rollout kit with scope, approvals, success metrics, and rollback expectations
+
+## Benchmark And Evidence
+
+Use `benchmark` to measure the impact of starter-safe improvements without modifying your working repo:
+
+```bash
+npx claudex-setup benchmark --out benchmark.md
+```
+
+Benchmark mode:
+
+- runs a baseline audit on your repo
+- copies the repo to an isolated temp workspace
+- applies starter-safe artifacts only in the copy
+- reruns the audit and emits before/after deltas, a case-study summary, and an executive recommendation
 
 ## 63 Checks Across 14 Categories
 
@@ -172,6 +254,7 @@ These checks evaluate **quality**, not just existence. A well-configured project
 
 - **Zero dependencies** - nothing to audit
 - **Runs 100% locally** - no cloud processing
+- **Benchmark uses an isolated temp copy** - your live repo is not touched
 - **Anonymous insights** - opt-in, no PII, no file contents (enable with `--insights`)
 - **MIT Licensed** - use anywhere
 

package/bin/cli.js

@@ -2,11 +2,115 @@
 
 const { audit } = require('../src/audit');
 const { setup } = require('../src/setup');
+const { analyzeProject, printAnalysis } = require('../src/analyze');
+const { buildProposalBundle, printProposalBundle, writePlanFile, applyProposalBundle, printApplyResult } = require('../src/plans');
+const { getGovernanceSummary, printGovernanceSummary } = require('../src/governance');
+const { runBenchmark, printBenchmark, writeBenchmarkReport } = require('../src/benchmark');
 const { version } = require('../package.json');
 
 const args = process.argv.slice(2);
-const command = args[0] || 'audit';
-const flags = args.filter(a => a.startsWith('--'));
+const COMMAND_ALIASES = {
+  review: 'deep-review',
+  wizard: 'interactive',
+  learn: 'insights',
+  discover: 'audit',
+  starter: 'setup',
+  suggest: 'suggest-only',
+  gov: 'governance',
+};
+const KNOWN_COMMANDS = ['audit', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'help', 'version'];
+
+function levenshtein(a, b) {
+  const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
+  for (let i = 0; i <= a.length; i++) matrix[i][0] = i;
+  for (let j = 0; j <= b.length; j++) matrix[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,
+        matrix[i][j - 1] + 1,
+        matrix[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return matrix[a.length][b.length];
+}
+
+function suggestCommand(input) {
+  const candidates = [...KNOWN_COMMANDS, ...Object.keys(COMMAND_ALIASES)];
+  let best = null;
+  let bestDistance = Infinity;
+  for (const candidate of candidates) {
+    const distance = levenshtein(input, candidate);
+    if (distance < bestDistance) {
+      best = candidate;
+      bestDistance = distance;
+    }
+  }
+  return bestDistance <= 3 ? best : null;
+}
+
+function parseArgs(rawArgs) {
+  const flags = [];
+  let command = 'audit';
+  let threshold = null;
+  let out = null;
+  let planFile = null;
+  let only = [];
+  let commandSet = false;
+
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+
+    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only') {
+      const value = rawArgs[i + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error(`${arg} requires a value`);
+      }
+      if (arg === '--threshold') threshold = value;
+      if (arg === '--out') out = value;
+      if (arg === '--plan') planFile = value;
+      if (arg === '--only') only = value.split(',').map(item => item.trim()).filter(Boolean);
+      i++;
+      continue;
+    }
+
+    if (arg.startsWith('--threshold=')) {
+      threshold = arg.split('=')[1];
+      continue;
+    }
+
+    if (arg.startsWith('--out=')) {
+      out = arg.split('=').slice(1).join('=');
+      continue;
+    }
+
+    if (arg.startsWith('--plan=')) {
+      planFile = arg.split('=').slice(1).join('=');
+      continue;
+    }
+
+    if (arg.startsWith('--only=')) {
+      only = arg.split('=').slice(1).join('=').split(',').map(item => item.trim()).filter(Boolean);
+      continue;
+    }
+
+    if (arg.startsWith('--')) {
+      flags.push(arg);
+      continue;
+    }
+
+    if (!commandSet) {
+      command = arg;
+      commandSet = true;
+    }
+  }
+
+  const normalizedCommand = COMMAND_ALIASES[command] || command;
+
+  return { flags, command, normalizedCommand, threshold, out, planFile, only };
+}
 
 const HELP = `
   claudex-setup v${version}
@@ -15,23 +119,63 @@ const HELP = `
 
   Usage:
     npx claudex-setup                  Run audit on current directory
+    npx claudex-setup discover         Discover the highest-value improvements
     npx claudex-setup audit            Same as above
+    npx claudex-setup starter          Alias for setup
     npx claudex-setup setup            Apply recommended configuration
     npx claudex-setup setup --auto     Apply all without prompts
-    npx claudex-setup deep-review       AI-powered config review (uses Claude Code or API key)
+    npx claudex-setup augment          Repo-aware augment plan (no writes)
+    npx claudex-setup suggest-only     Structured suggestion report (no writes)
+    npx claudex-setup plan             Exportable proposal bundles with file previews
+    npx claudex-setup apply            Apply ready proposal bundles with rollback manifest
+    npx claudex-setup governance       Profiles, hooks, and pilot rollout guidance
+    npx claudex-setup benchmark        Measure before/after impact in an isolated temp copy
+    npx claudex-setup deep-review      AI-powered config review (uses Claude Code or API key)
     npx claudex-setup interactive      Step-by-step guided wizard
     npx claudex-setup watch            Monitor changes and re-audit live
     npx claudex-setup badge            Generate shields.io badge markdown
 
   Options:
+    --threshold N   Exit with code 1 if score is below N (useful for CI)
+    --out FILE      Write JSON or markdown output to a file
+    --plan FILE     Load a previously exported plan file
+    --only A,B      Limit plan/apply to selected proposal ids or technique keys
+    --dry-run       Preview apply without writing files
     --verbose       Show all recommendations (not just critical/high)
     --json          Output as JSON (for CI pipelines)
-    --insights       Enable anonymous usage insights (off by default)
+    --auto          Apply all generated setup files without prompting
+    --insights      Enable anonymous usage insights (off by default)
     --help          Show this help
     --version       Show version
+
+  Examples:
+    npx claudex-setup
+    npx claudex-setup augment
+    npx claudex-setup suggest-only --json
+    npx claudex-setup plan --out claudex-plan.json
+    npx claudex-setup apply --plan claudex-plan.json --only hooks,commands
+    npx claudex-setup governance --json
+    npx claudex-setup benchmark --out benchmark.md
+    npx claudex-setup --json --threshold 60
+    npx claudex-setup setup --auto
+    npx claudex-setup interactive
+
+  Exit codes:
+    0  Success
+    1  Error, unknown command, or score below --threshold
 `;
 
 async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs(args);
+  } catch (err) {
+    console.error(`\n  Error: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const { flags, command, normalizedCommand } = parsed;
+
   if (flags.includes('--help') || command === 'help') {
     console.log(HELP);
     process.exit(0);
@@ -46,9 +190,29 @@ async function main() {
     verbose: flags.includes('--verbose'),
     json: flags.includes('--json'),
     auto: flags.includes('--auto'),
+    dryRun: flags.includes('--dry-run'),
+    threshold: parsed.threshold !== null ? Number(parsed.threshold) : null,
+    out: parsed.out,
+    planFile: parsed.planFile,
+    only: parsed.only,
     dir: process.cwd()
   };
 
+  if (options.threshold !== null && (!Number.isFinite(options.threshold) || options.threshold < 0 || options.threshold > 100)) {
+    console.error('\n  Error: --threshold must be a number between 0 and 100.\n');
+    process.exit(1);
+  }
+
+  if (!KNOWN_COMMANDS.includes(normalizedCommand)) {
+    const suggestion = suggestCommand(command);
+    console.error(`\n  Error: Unknown command '${command}'.`);
+    if (suggestion) {
+      console.error(`  Did you mean '${suggestion}'?`);
+    }
+    console.error('  Run claudex-setup --help for usage.\n');
+    process.exit(1);
+  }
+
   if (!require('fs').existsSync(options.dir)) {
     console.error(`\n  Error: Directory not found: ${options.dir}`);
     console.error('  Run claudex-setup from inside your project directory.\n');
@@ -56,14 +220,14 @@ async function main() {
   }
 
   try {
-    if (command === 'badge') {
+    if (normalizedCommand === 'badge') {
       const { getBadgeMarkdown } = require('../src/badge');
       const result = await audit({ ...options, silent: true });
       console.log(getBadgeMarkdown(result.score));
       console.log('');
       console.log('Add this to your README.md');
       process.exit(0);
-    } else if (command === 'insights' || command === 'learn') {
+    } else if (normalizedCommand === 'insights') {
       const https = require('https');
       const url = 'https://claudex-insights.claudex.workers.dev/v1/stats';
       https.get(url, (res) => {
@@ -98,19 +262,58 @@ async function main() {
         console.log('  Could not reach insights server. Run locally: npx claudex-setup');
       });
       return; // keep process alive for http
-    } else if (command === 'deep-review' || command === 'review') {
+    } else if (normalizedCommand === 'augment' || normalizedCommand === 'suggest-only') {
+      const report = await analyzeProject({ ...options, mode: normalizedCommand });
+      printAnalysis(report, options);
+    } else if (normalizedCommand === 'plan') {
+      const bundle = await buildProposalBundle(options);
+      let artifact = null;
+      if (options.out) {
+        artifact = writePlanFile(bundle, options.out);
+      }
+      printProposalBundle(bundle, options);
+      if (options.out && !options.json) {
+        console.log(`  Plan written to ${options.out}`);
+        if (artifact) {
+          console.log(`  Activity log: ${artifact.relativePath}`);
+        }
+        console.log('');
+      }
+    } else if (normalizedCommand === 'apply') {
+      const result = await applyProposalBundle(options);
+      printApplyResult(result, options);
+    } else if (normalizedCommand === 'governance') {
+      const summary = getGovernanceSummary();
+      printGovernanceSummary(summary, options);
+    } else if (normalizedCommand === 'benchmark') {
+      const report = await runBenchmark(options);
+      if (options.out) {
+        writeBenchmarkReport(report, options.out);
+      }
+      printBenchmark(report, options);
+      if (options.out && !options.json) {
+        console.log(`  Benchmark report written to ${options.out}`);
+        console.log('');
+      }
+    } else if (normalizedCommand === 'deep-review') {
       const { deepReview } = require('../src/deep-review');
       await deepReview(options);
-    } else if (command === 'interactive' || command === 'wizard') {
+    } else if (normalizedCommand === 'interactive') {
       const { interactive } = require('../src/interactive');
       await interactive(options);
-    } else if (command === 'watch') {
+    } else if (normalizedCommand === 'watch') {
       const { watch } = require('../src/watch');
       await watch(options);
-    } else if (command === 'setup') {
+    } else if (normalizedCommand === 'setup') {
       await setup(options);
     } else {
-      await audit(options);
+      const result = await audit(options);
+      if (options.threshold !== null && result.score < options.threshold) {
+        if (!options.json) {
+          console.error(`  Threshold failed: score ${result.score}/100 is below required ${options.threshold}/100.\n`);
+        }
+        process.exit(1);
+      }
     }
   } catch (err) {
     console.error(`\n  Error: ${err.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudex-setup",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Audit and optimize any project for Claude Code. Powered by 1107 verified techniques.",
   "main": "src/index.js",
   "bin": {

package/src/activity.js

@@ -0,0 +1,60 @@
+const fs = require('fs');
+const path = require('path');
+
+function timestampId() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function ensureArtifactDirs(dir) {
+  const root = path.join(dir, '.claude', 'claudex-setup');
+  const activityDir = path.join(root, 'activity');
+  const rollbackDir = path.join(root, 'rollbacks');
+  fs.mkdirSync(activityDir, { recursive: true });
+  fs.mkdirSync(rollbackDir, { recursive: true });
+  return { root, activityDir, rollbackDir };
+}
+
+function writeJson(filePath, payload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(payload, null, 2), 'utf8');
+}
+
+function writeActivityArtifact(dir, type, payload) {
+  const id = timestampId();
+  const { activityDir } = ensureArtifactDirs(dir);
+  const filePath = path.join(activityDir, `${id}-${type}.json`);
+  writeJson(filePath, {
+    id,
+    type,
+    createdAt: new Date().toISOString(),
+    ...payload,
+  });
+  return {
+    id,
+    filePath,
+    relativePath: path.relative(dir, filePath),
+  };
+}
+
+function writeRollbackArtifact(dir, payload) {
+  const id = timestampId();
+  const { rollbackDir } = ensureArtifactDirs(dir);
+  const filePath = path.join(rollbackDir, `${id}.json`);
+  writeJson(filePath, {
+    id,
+    createdAt: new Date().toISOString(),
+    rollbackType: 'delete-created-files',
+    ...payload,
+  });
+  return {
+    id,
+    filePath,
+    relativePath: path.relative(dir, filePath),
+  };
+}
+
+module.exports = {
+  ensureArtifactDirs,
+  writeActivityArtifact,
+  writeRollbackArtifact,
+};