@nerviq/cli 0.9.6 → 1.0.1

package/src/certification.js

@@ -0,0 +1,100 @@
+/**
+ * Certification system for Nerviq.
+ * Evaluates a project against all active platforms and assigns a certification level.
+ */
+
+const path = require('path');
+const { audit } = require('./audit');
+const { harmonyAudit } = require('./harmony/audit');
+const { detectPlatforms } = require('./public-api');
+
+const LEVELS = {
+  GOLD: 'Nerviq Certified Gold',
+  SILVER: 'Nerviq Certified Silver',
+  BRONZE: 'Nerviq Certified Bronze',
+  NONE: 'Not Certified',
+};
+
+const BADGE_COLORS = {
+  [LEVELS.GOLD]: 'gold',
+  [LEVELS.SILVER]: 'silver',
+  [LEVELS.BRONZE]: 'cd7f32',
+  [LEVELS.NONE]: 'lightgrey',
+};
+
+/**
+ * Certify a project directory.
+ * Runs harmony audit and per-platform audits, then determines certification level.
+ *
+ * @param {string} dir - Project directory path
+ * @returns {Promise<{ level: string, harmonyScore: number, platformScores: Object, badge: string }>}
+ */
+async function certifyProject(dir) {
+  const resolvedDir = path.resolve(dir || '.');
+
+  // Detect active platforms
+  const platforms = detectPlatforms(resolvedDir);
+
+  // Run per-platform audits
+  const platformScores = {};
+  for (const platform of platforms) {
+    try {
+      const result = await audit({ dir: resolvedDir, platform, silent: true });
+      platformScores[platform] = result.score;
+    } catch {
+      platformScores[platform] = 0;
+    }
+  }
+
+  // Run harmony audit
+  let harmonyScore = 0;
+  try {
+    const harmonyResult = await harmonyAudit({ dir: resolvedDir, silent: true });
+    harmonyScore = harmonyResult.harmonyScore || 0;
+  } catch {
+    harmonyScore = 0;
+  }
+
+  // Determine certification level
+  const scores = Object.values(platformScores);
+  const allAbove70 = scores.length > 0 && scores.every(s => s >= 70);
+  const allAbove50 = scores.length > 0 && scores.every(s => s >= 50);
+  const anyAbove40 = scores.some(s => s >= 40);
+
+  let level;
+  if (harmonyScore >= 80 && allAbove70) {
+    level = LEVELS.GOLD;
+  } else if (harmonyScore >= 60 && allAbove50) {
+    level = LEVELS.SILVER;
+  } else if (anyAbove40) {
+    level = LEVELS.BRONZE;
+  } else {
+    level = LEVELS.NONE;
+  }
+
+  const badge = generateCertBadge(level);
+
+  return {
+    level,
+    harmonyScore,
+    platformScores,
+    platforms,
+    badge,
+  };
+}
+
+/**
+ * Generate a shields.io badge markdown string for a certification level.
+ *
+ * @param {string} level - One of the LEVELS values
+ * @returns {string} Markdown badge string
+ */
+function generateCertBadge(level) {
+  const color = BADGE_COLORS[level] || 'lightgrey';
+  const label = encodeURIComponent('Nerviq');
+  const message = encodeURIComponent(level);
+  const url = `https://img.shields.io/badge/${label}-${message}-${color}`;
+  return `[![${level}](${url})](https://nerviq.net)`;
+}
+
+module.exports = { certifyProject, generateCertBadge, LEVELS };

package/CHANGELOG.md

@@ -1,181 +0,0 @@
-# Changelog
-
-## [1.16.2] - 2026-04-03
-
-### Changed
-- bumped the local release line to `1.16.2` so the next publish does not overwrite the already-live `1.16.1` npm release
-- synchronized README, docs, launch copy, and proof-facing state to distinguish clearly between public npm latest (`1.16.1`) and local release prep (`1.16.2`)
-
-### Fixed
-- release-truth drift across package metadata, docs, and public-facing proof references
-
-## [1.16.1] - 2026-04-03
-
-### Added
-- `feedback` command validation on the public npm package line
-- stronger secret detection coverage for Anthropic-style keys
-- deep-review sanitization and secret redaction hardening
-- watch-mode resilience improvements across recursive and non-recursive platforms
-
-### Changed
-- increased verified check count from `84` to `85`
-- proof-backed product copy and case-study traceability improvements
-
-## [1.10.3] - 2026-04-02
-
-### Added
-- `--snapshot` support for `audit`, `augment`, `suggest-only`, `benchmark`, and `governance`, writing normalized evidence artifacts under `.claude/claudex-setup/snapshots/`
-- shared snapshot history via `index.json` so before/after work can accumulate into a single local evidence spine
-- `governance --out governance.md` for a shareable governance / pilot-readiness artifact
-- packaged Claude-native `audit-repo` skill template under `content/claude-code/audit-repo/`
-- lightweight release checklist in `content/release-checklist.md`
-
-### Changed
-- default audit now surfaces `Top 5 Next Actions` with rationale, traceability, risk, confidence, and a suggested next command
-- `--lite` now gives a shorter beginner-first top-3 quick scan
-- README and docs now reflect snapshot artifacts, governance export, and the Claude-native skill path
-- packaged content and public-facing counts are now aligned with the current CLAUDEX state
-
-## [1.14.0] - 2026-04-03
-
-### Added
-- Check-level test matrix: 327 verified scenarios across all 84 checks
-- Golden matrix: 12 repo profile tests with expected results
-
-### Fixed
-- `hooks` check now detects hooks in settings.json (not only .claude/hooks/ dir)
-- `context7Mcp` check now reads .mcp.json
-- `skillUsesPaths` now traverses skill subdirectories (skills/name/SKILL.md)
-- `lintCommand` now matches npm/yarn/pnpm/bun lint commands
-
-## [1.13.0] - 2026-04-03
-
-### Added
-- 10 new checks (74→84): project description, directory structure, multiple hook types, stop-failure hook, skill paths, MCP env config, gitignore local settings, .env.example, package scripts, type checking
-- 15 new tests (58→73): history/compare/trend, new checks structure, CLI commands, deny depth, negative instructions, --require flag
-- All references updated to 74→84 checks
-
-## [1.12.0] - 2026-04-03
-
-### Added
-- 12 new checks (62→74): test coverage, agent tool restrictions, auto-memory, sandbox, deny rule depth, git attribution, effort level, snapshot history, worktree, negative instructions, output style, CI variants
-- 8 new stacks (22→30): Deno, Bun, Elixir, Astro, Remix, NestJS, Laravel, .NET
-- Deeper domain detection: llamaindex, crewai, autogen, ollama for AI/ML; paypal, square, adyen, medusa for ecommerce; chromatic, style-dictionary for design; capacitor, ionic for mobile
-
-### Fixed
-- `githubActionsOrCI` check used non-existent `ctx.hasFile()` — now uses `ctx.fileContent()`
-- `.NET` stack detection no longer uses glob patterns
-
-## [1.11.0] - 2026-04-03
-
-### Added
-- `history` command — show score timeline from saved snapshots
-- `compare` command — diff latest vs previous snapshot with delta, regressions, improvements
-- `trend --out report.md` — export trend report as shareable markdown
-- `--require A,B` CI flag — exit code 1 if named checks fail (policy guardrails)
-- Agentic DX positioning in README
-- Real results table (4 case studies) in README
-- Claude-native integration guide (skill, hook, agent examples)
-- Trust-first help text reordering
-
-### Fixed
-- Hook checks (hooksInSettings, preToolUse, postToolUse, sessionStart) now OR across settings.json and settings.local.json
-
-## [1.10.2] - 2026-04-02
-
-### Fixed
-- MCP recommendations are now less speculative: `postgres-mcp` requires explicit Postgres signals, `figma-mcp` only appears for design-system repos, and `mcp-security` is no longer auto-added just because multiple packs were suggested
-- `sentry-mcp` now requires real observability signals or stricter operational domains instead of appearing for every frontend/backend repo
-- design-system detection now respects `.storybook/` directories directly, improving frontend pack accuracy
-
-### Added
-- MCP preflight warnings for `setup`, `plan`, and `apply` when selected packs require missing environment variables
-- user-facing docs now reflect the actual 22 detected stacks
-
-## [1.10.1] - 2026-04-02
-
-### Fixed
-- corrected MCP pack package names to verified npm packages
-- aligned settings hierarchy checks with shared settings precedence
-
-## [1.10.0] - 2026-04-01
-
-### Added
-- 11 new MCP packs (15→26): sequential-thinking, jira-confluence, ga4-analytics, search-console, n8n-workflows, zendesk, infisical-secrets, shopify, huggingface, blender, wordpress
-- 7 new domain packs (10→17→16 final): ecommerce, ai-ml, devops-cicd, design-system, docs-content, security-focused
-- Smart recommendation for all new packs based on detected stack and domain
-- Detection logic: Storybook, Docusaurus, Stripe, LangChain, GitHub Actions, auth deps
-
-## [1.9.0] - 2026-03-31
-
-### Added
-- 3 new domain packs: `monorepo`, `mobile`, `regulated-lite` (7→10 total)
-- 3 new MCP packs: `github-mcp`, `postgres-mcp`, `memory-mcp` (2→5 total)
-- smart MCP pack recommendation based on detected domain packs
-- `suggest-only --out report.md` exports full analysis as shareable markdown
-- `why` explanations for all strengths preserved (20+ specific reasons)
-- `why` explanations for all gap findings (12+ specific reasons)
-- 5 new hooks in governance registry: duplicate-id-check, injection-defense, trust-drift-check, session-init, protect-catalog
-- case study template in `content/case-study-template.md`
-- hook risk level display in governance output (color-coded low/medium/high)
-
-### Fixed
-- **Settings hierarchy bug**: `noBypassPermissions` and `secretsProtection` checks now correctly read `.claude/settings.json` before `.claude/settings.local.json`, so personal maintainer overrides no longer fail the shared audit
-- domain pack detection now handles monorepo (nx.json, turbo.json, lerna.json, workspaces), mobile (React Native, Flutter, iOS/Android dirs), and regulated repos (SECURITY.md, compliance dirs)
-
-### Changed
-- strengths preserved section now shows 8 items (was 6) with specific value explanations
-- claudex-sync.json updated with domain pack, MCP pack, and anti-pattern counts
-
-## [1.8.0] - 2026-03-31
-
-### Added
-- domain pack recommendations for backend, frontend, data, infra, OSS, and enterprise-governed repos
-- MCP pack recommendations and merge support for `context7-docs` and `next-devtools`
-- workflow-evidence coverage in benchmark reports
-- runtime settings overlays so `apply --plan` still respects current `--profile` and `--mcp-pack` flags
-
-### Changed
-- benchmark now respects the selected profile and MCP pack options during isolated-copy runs
-- governance and suggest-only outputs now expose domain packs and MCP packs directly
-- README and docs clarify the local-vs-opt-in-network boundary for core flows vs `deep-review`
-- audit output now frames `setup` as starter-safe generation instead of an automatic full fix
-
-## [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
-- 50+ audit checks (up from 16)
-- 8 new categories: Design, DevOps, Hygiene, Performance, MCP, Prompting, Git Safety, Automation
-- 6 new stack detections: Svelte, Flutter, Ruby, Java, Kotlin, Swift
-- Improved CLAUDE.md template with Mermaid diagrams and XML constraints
-- Auto-sync with CLAUDEX research catalog (1,107 items)
-- Copy-paste config snippets in fix suggestions
-
-### Changed
-- Knowledge base upgraded from 972 to 1,107 verified techniques
-- Better scoring weights per category
-
-## [0.1.0] - 2026-03-30
-
-### Added
-- Initial release
-- 16 audit checks
-- Automatic setup with CLAUDE.md, hooks, commands, skills, rules, agents
-- Stack detection for 12 frameworks
-- JSON output mode

package/content/case-study-template.md

@@ -1,91 +0,0 @@
-# Case Study: [Project Name]
-
-## Overview
-
-| Field | Value |
-|-------|-------|
-| Project | [name] |
-| Repo type | [e.g., backend API, frontend SPA, monorepo, data pipeline] |
-| Team size | [e.g., solo, 3 developers, 15-person team] |
-| Prior Claude setup | [none / basic CLAUDE.md / mature .claude/ config] |
-| Claudex Setup version | [e.g., 1.9.0] |
-| Date | [YYYY-MM-DD] |
-
-## Before State
-
-**Audit score:** [X/100]
-**Organic score:** [X/100]
-
-What existed before running claudex-setup:
-- [ ] CLAUDE.md
-- [ ] .claude/settings.json
-- [ ] Custom commands
-- [ ] Rules
-- [ ] Hooks
-- [ ] Agents
-- [ ] MCP servers
-
-Key observations:
-- [What was good already]
-- [What was missing]
-- [What was risky or misconfigured]
-
-## What We Did
-
-**Mode used:** [discover / starter / augment / plan+apply / suggest-only]
-
-**Steps:**
-1. Ran `npx claudex-setup discover` to understand current state
-2. [Next step]
-3. [Next step]
-
-**Domain pack matched:** [e.g., backend-api]
-**MCP packs recommended:** [e.g., context7-docs, postgres-mcp]
-
-## Changes Applied
-
-| Change | Type | Risk | Applied? |
-|--------|------|------|----------|
-| [e.g., Created CLAUDE.md with architecture] | new file | low | yes |
-| [e.g., Added hooks for auto-lint] | new config | medium | yes |
-| [e.g., Added permission deny rules] | security | low | yes |
-
-**Strengths preserved:**
-- [What we explicitly kept unchanged]
-
-## After State
-
-**Audit score:** [X/100] (was [X/100])
-**Organic score:** [X/100] (was [X/100])
-**Score improvement:** +[X] points
-
-## Measured Impact
-
-| Metric | Before | After | Change |
-|--------|--------|-------|--------|
-| Audit score | X | X | +X |
-| Checks passing | X/84 | X/84 | +X |
-| Time to first productive session | Xm | Xm | -Xm |
-| [Other metric] | | | |
-
-## What Worked Well
-
-- [Specific thing that added clear value]
-- [Another]
-
-## What Could Be Better
-
-- [Specific improvement suggestion for the tool]
-- [Another]
-
-## Verdict
-
-**Would recommend:** [Yes / Yes with caveats / Not yet]
-
-**Best for:** [Who should try this based on our experience]
-
-**One-line summary:** [e.g., "Took our Claude setup from basic to production-ready in 15 minutes with zero breakage."]
-
----
-
-*Generated with claudex-setup v[version]. Case study template from CLAUDEX.*

package/content/claims-governance.md

@@ -1,37 +0,0 @@
-# Claims Governance
-
-Use this checklist before publishing product-facing claims about Claudex Setup.
-
-## Allowed only with evidence
-
-- score delta claims
-- organic score delta claims
-- time-to-value claims
-- recommendation acceptance rate claims
-- reduction in manual corrections
-- benchmark outcomes on named repo types
-
-## Evidence standard
-
-Every claim should have:
-
-- a benchmark run or pilot report
-- the repo type or cohort it applies to
-- the date the evidence was collected
-- the exact metric definition
-- the comparison method (`before/after`, `control/pilot`, or `observed over time`)
-
-## Avoid
-
-- universal productivity multipliers
-- unsupported token savings claims
-- “works for every repo” language
-- suspiciously precise numbers without a method section
-- implying quality scores are objective truth rather than framework coverage
-
-## Safer phrasing
-
-- "In benchmark mode, this repo improved from 41/100 to 60/100."
-- "Starter-safe artifacts improved readiness on an isolated temp copy."
-- "Suggest-only mode gives mature teams a zero-write review path."
-- "Use governance mode to select permission profiles and inspect shipped hooks."

package/content/claude-code/audit-repo/SKILL.md

@@ -1,20 +0,0 @@
----
-name: audit-repo
-description: Run claudex-setup on the current repo and summarize the score, top gaps, and next command
----
-
-Run `npx claudex-setup --json` in the current project directory and summarize the result.
-
-Your output should include:
-
-1. The overall score and organic score
-2. The top 3 next actions from `topNextActions`
-3. The suggested next command from `suggestedNextCommand`
-4. A short explanation of what the repo already does well if there are notable strengths
-
-Behavior rules:
-
-- If the user asks for the shortest version, run `npx claudex-setup --lite`
-- If the user wants deeper no-write analysis, run `npx claudex-setup augment --json`
-- If the score is below 50, explicitly recommend `npx claudex-setup setup`
-- Never apply changes automatically from this skill

package/content/claude-native-integration.md

@@ -1,60 +0,0 @@
-# Using claudex-setup from inside Claude Code
-
-## Skill: Audit Repo
-
-Add this to `.claude/skills/audit-repo.md` in any project:
-
-```markdown
----
-name: audit-repo
-description: Run claudex-setup audit on the current project and show score + top gaps
----
-
-Run `npx claudex-setup --json` on the current project directory.
-Parse the JSON output and present:
-1. Score X/100
-2. Top 3 critical/high gaps with fix descriptions
-3. Suggest next command based on score
-
-$ARGUMENTS — optional: --lite for quick scan
-```
-
-## Hook: Auto-audit on SessionStart
-
-Add to `.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "type": "command",
-        "command": "node -e \"try{const r=require('child_process').execSync('npx claudex-setup --json 2>/dev/null',{timeout:15000}).toString();const d=JSON.parse(r);if(d.score<50)console.log(JSON.stringify({systemMessage:'⚠️ Claude Code setup score: '+d.score+'/100. Consider running: npx claudex-setup --lite'}))}catch(e){console.log('{}')}\"",
-        "timeout": 20,
-        "statusMessage": "Checking Claude Code setup..."
-      }
-    ]
-  }
-}
-```
-
-## Agent: Setup Advisor
-
-Add to `.claude/agents/setup-advisor.md`:
-
-```markdown
----
-name: setup-advisor
-description: Analyzes Claude Code setup and recommends improvements
-tools: [Bash, Read, Glob, Grep]
-model: haiku
-maxTurns: 10
----
-
-You are a Claude Code setup advisor.
-
-1. Run `npx claudex-setup augment --json` on the current project
-2. Analyze gaps and strengths
-3. Recommend top 5 improvements with rationale
-4. If user approves, guide them through applying changes
-```

package/content/devto-article.json

@@ -1,9 +0,0 @@
-{
-  "article": {
-    "title": "Your Claude Code project scores 10/100. Here's how to fix it in 60 seconds.",
-    "published": false,
-    "tags": ["claude", "ai", "productivity", "devtools"],
-    "series": "Claude Code Optimization",
-    "body_markdown": "After cataloging **1,107 Claude Code entries** and verifying **948 with real evidence**, I found that most projects use barely 10% of what's available.\n\nI built a CLI that scores your project:\n\n```bash\nnpx claudex-setup\n```\n\nMost projects score **10-20 out of 100**. After running setup, they jump to **70+**.\n\n## The Top 10 Things You're Missing\n\n### 1. CLAUDE.md (Critical)\n\nClaude reads this file at the start of every session. Without it, Claude doesn't know your build commands, code style, or project rules.\n\nOur tool generates a smart CLAUDE.md that detects your framework, TypeScript config, and creates a Mermaid architecture diagram automatically.\n\n### 2. Mermaid Architecture Diagrams (73% Token Savings)\n\nA Mermaid diagram in CLAUDE.md gives Claude your project structure in a fraction of the tokens that prose requires.\n\n### 3. Hooks > CLAUDE.md Rules (100% vs 80%)\n\nCLAUDE.md instructions are advisory (~80% compliance). Hooks are deterministic (100%). Auto-lint after every edit. Every time.\n\n### 4. Custom Commands\n\nStop typing the same prompts. Create `/test`, `/deploy`, `/review` in `.claude/commands/`.\n\n### 5. Verification Loops (The #1 Best Practice)\n\n> *This is the single highest-leverage thing you can do.* — Anthropic Best Practices\n\nClaude performs dramatically better when it can verify its own work.\n\n### 6. XML Tags (30% Quality Boost)\n\nUse `<constraints>`, `<validation>` in CLAUDE.md for unambiguous instructions.\n\n### 7. Secrets Protection\n\nClaude Code loads `.env` automatically. Add deny rules to prevent reading sensitive files.\n\n### 8. /security-review\n\nBuilt-in OWASP Top 10 scanning. Most people don't know this command exists.\n\n### 9. Custom Agents\n\nSpecialized subagents: security-reviewer, test-writer in `.claude/agents/`.\n\n### 10. Skills (On-Demand Knowledge)\n\nReusable skills package expertise that Claude can load on demand.\n\n## Try It Now\n\n```bash\nnpx claudex-setup --lite       # Quick scan\nnpx claudex-setup              # Full audit\nnpx claudex-setup --snapshot   # Save evidence artifact\nnpx claudex-setup governance --out governance.md\n```\n\nFree, open source, zero dependencies.\n\n**GitHub:** [github.com/DnaFin/claudex-setup](https://github.com/DnaFin/claudex-setup)\n**npm:** [npmjs.com/package/claudex-setup](https://www.npmjs.com/package/claudex-setup)\n\n---\n\n*Built from a research catalog of 1,107 Claude Code entries, 948 verified with evidence.*"
-  }
-}