@nerviq/cli 1.27.0 → 1.29.0

package/README.md

@@ -234,8 +234,8 @@ All successful operational responses are wrapped in a JSON envelope:
 {
   "data": {},
   "meta": {
-    "version": "1.27.0",
-    "timestamp": "2026-04-15T18:00:00.000Z"
+    "version": "1.29.0",
+    "timestamp": "2026-04-16T08:00:00.000Z"
   }
 }
 ```

package/SECURITY.md

@@ -0,0 +1,82 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in Nerviq, please report it responsibly.
+
+**Email:** [business@nerviq.net](mailto:business@nerviq.net) (subject: SECURITY)
+
+Please include:
+
+- Description of the vulnerability
+- Steps to reproduce
+- Affected version(s)
+- Impact assessment (if known)
+
+**Do not** open a public GitHub issue for security vulnerabilities.
+
+## Response SLA
+
+| Severity | Response Time | Fix Timeline |
+|----------|--------------|--------------|
+| **Critical** (RCE, data exfiltration) | < 24 hours | < 48 hours |
+| **High** (privilege escalation, auth bypass) | < 48 hours | < 7 days |
+| **Medium** (information disclosure, DoS) | < 7 days | < 30 days |
+| **Low** (minor issues, hardening) | < 14 days | Next release |
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.29.x | Yes |
+| 1.28.x | Yes |
+| 1.27.x | Yes |
+| 1.26.x | Yes |
+| < 1.26 | No |
+| < 1.29 | No |
+
+Only the latest patch release of each supported major.minor line receives security updates.
+
+## Dependency Policy
+
+- **Zero runtime dependencies.** Nerviq ships with no production `node_modules` — only Node.js (>=18) is required.
+- **devDependencies audited monthly** using `npm audit` and reviewed for known CVEs.
+- **SBOM published** with every release (`sbom.cdx.json`) in CycloneDX format for full dependency transparency.
+- **Lockfile integrity** checked in CI to prevent supply-chain tampering.
+- **npm provenance attestation** — every release published via the GitHub Actions release workflow is signed with an npm provenance attestation (`npm publish --provenance`). This cryptographically links the published package to a specific GitHub Actions run, repository, and commit. Consumers can verify the attestation with `npm audit signatures @nerviq/cli`.
+
+## Security Architecture
+
+- All operations run **locally** — no data is sent to external servers by default.
+- The `nerviq serve` command binds to **localhost only** (127.0.0.1), never to 0.0.0.0.
+- `deep-review` (opt-in) redacts secrets and credentials before sending config snippets to any AI provider.
+- No secrets, tokens, or API keys are stored by Nerviq.
+
+## Reporting False Positives in Checks
+
+If a Nerviq audit check produces a false positive (flags something that is not actually a problem):
+
+1. Run `nerviq audit --verbose` to identify the exact check key (e.g., `permissionDeny`).
+2. Open a GitHub issue with:
+   - The check key
+   - Your project structure (relevant files only)
+   - Why you believe it is a false positive
+3. Alternatively, use `nerviq feedback --key <checkKey> --status rejected --effect neutral --notes "false positive: <reason>"` to record it locally.
+
+False positive reports help us improve check accuracy for all users.
+
+## Acknowledgments
+
+We gratefully acknowledge security researchers who responsibly disclose vulnerabilities. With your permission, we will list you in our security acknowledgments.
+
+## Internal Response Process
+
+When a vulnerability report arrives:
+
+1. **Acknowledge** — Reply within the SLA above confirming receipt
+2. **Triage** — Classify severity (Critical/High/Medium/Low), assign to founder
+3. **Reproduce** — Verify the vulnerability exists in the latest supported version
+4. **Fix** — Develop fix on a private branch, add regression test
+5. **Release** — Publish patched version to npm, tag in GitHub
+6. **Disclose** — Notify reporter, update CHANGELOG.md with security tag, credit reporter if permitted
+7. **Post-mortem** — For Critical/High: document root cause and prevention measures in `research/`

package/contracts/audit-webhook-event.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nerviq.net/contracts/audit-webhook-event.schema.json",
+  "title": "Nerviq Audit Webhook Event",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "event",
+    "schemaVersion",
+    "generatedAt",
+    "platform",
+    "score",
+    "passed",
+    "failed",
+    "results",
+    "data",
+    "meta"
+  ],
+  "properties": {
+    "event": {
+      "const": "nerviq.audit.completed"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "platform": {
+      "type": "string"
+    },
+    "score": {
+      "type": "number"
+    },
+    "passed": {
+      "type": "integer"
+    },
+    "failed": {
+      "type": "integer"
+    },
+    "results": {
+      "type": "array"
+    },
+    "data": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "platform",
+        "score",
+        "scoreType",
+        "passed",
+        "failed",
+        "checkCount",
+        "topNextActions",
+        "quickWins",
+        "scoreCoaching"
+      ],
+      "properties": {
+        "platform": {
+          "type": "string"
+        },
+        "platformLabel": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "score": {
+          "type": "number"
+        },
+        "scoreType": {
+          "type": "string"
+        },
+        "organicScore": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "passed": {
+          "type": "integer"
+        },
+        "failed": {
+          "type": "integer"
+        },
+        "skipped": {
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "checkCount": {
+          "type": "integer"
+        },
+        "topNextActions": {
+          "type": "array"
+        },
+        "quickWins": {
+          "type": "array"
+        },
+        "scoreCoaching": {
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "suggestedNextCommand": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "cliVersion",
+        "source",
+        "webhookFormat"
+      ],
+      "properties": {
+        "cliVersion": {
+          "type": "string"
+        },
+        "source": {
+          "const": "nerviq-cli"
+        },
+        "webhookFormat": {
+          "const": "generic-audit-event"
+        }
+      }
+    }
+  }
+}

package/contracts/pack-contract.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Nerviq Domain/MCP Pack",
+  "type": "object",
+  "required": ["key", "label"],
+  "properties": {
+    "key": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "label": { "type": "string" },
+    "description": { "type": "string" },
+    "useWhen": { "type": "string" },
+    "adoption": { "type": "string" },
+    "recommendedModules": { "type": "array", "items": { "type": "string" } },
+    "benchmarkFocus": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/contracts/technique-contract.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Nerviq Technique",
+  "type": "object",
+  "required": ["id", "name", "check", "impact", "category", "fix"],
+  "properties": {
+    "id": { "type": ["string", "integer"] },
+    "name": { "type": "string", "minLength": 3 },
+    "check": { "description": "Function (ctx) => boolean|null" },
+    "impact": { "type": "string", "enum": ["critical", "high", "medium", "low"] },
+    "category": { "type": "string", "minLength": 2 },
+    "fix": { "type": "string", "minLength": 5 },
+    "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
+    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+    "sourceUrl": { "type": "string", "format": "uri" },
+    "template": {}
+  }
+}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,74 @@
+# Architecture
+
+## Data Flow
+
+```mermaid
+graph LR
+    CLI[bin/cli.js] --> Audit[audit.js]
+    CLI --> Setup[setup.js]
+    CLI --> Analyze[analyze.js]
+    CLI --> Plans[plans.js]
+    CLI --> Gov[governance.js]
+    CLI --> Bench[benchmark.js]
+
+    Context[context.js] --> Audit
+    Context --> Setup
+    Context --> Analyze
+
+    Techniques[techniques.js<br/>84 checks + 30 stacks] --> Audit
+    Techniques --> Setup
+
+    DomainPacks[domain-packs.js<br/>16 domains] --> Analyze
+    DomainPacks --> Gov
+
+    McpPacks[mcp-packs.js<br/>26 MCP packs] --> Analyze
+    McpPacks --> Gov
+    McpPacks --> Plans
+
+    Audit --> Activity[activity.js<br/>snapshots + history]
+    Bench --> Activity
+    Analyze --> Activity
+```
+
+## Module Responsibilities
+
+| Module | Role | I/O |
+|--------|------|-----|
+| **context.js** | Scans project directory, caches file reads | Dir path → ProjectContext |
+| **techniques.js** | Defines 84 checks + 30 stacks. The knowledge base | ProjectContext → check results |
+| **audit.js** | Runs checks, calculates score, builds topNextActions | Options → scored result |
+| **analyze.js** | Augment/suggest-only analysis with strengths, gaps, domains | Options → analysis report |
+| **plans.js** | Generates proposal bundles, applies with rollback | Audit result → proposals |
+| **setup.js** | Generates CLAUDE.md, hooks, commands, agents, skills, rules | Stacks + context → files |
+| **governance.js** | Permission profiles, hook registry, policy packs | Config → governance summary |
+| **benchmark.js** | Isolated before/after in temp copy | Options → benchmark report |
+| **domain-packs.js** | Detects repo type from signals | Context + stacks → domain matches |
+| **mcp-packs.js** | Recommends MCP servers per domain | Domains + signals → MCP packs |
+| **activity.js** | Snapshots, history, compare, trend export | Payloads → artifact files |
+
+## Scoring
+
+```
+Score = (earned / max) * 100
+
+Weights: critical=15, high=10, medium=5, low=2
+Organic score: excludes checks that nerviq itself generated
+```
+
+Checks return `true` (pass), `false` (fail), or `null` (not applicable / skip).
+
+## Trust-First Flow
+
+```
+User runs audit → sees score + gaps
+            ↓
+User runs plan → sees file previews + rationale
+            ↓
+User reviews → approves specific bundles
+            ↓
+apply writes files → rollback manifest created
+            ↓
+User runs audit again → sees improvement
+```
+
+No step writes without the previous step's output being reviewed.