@stacknext/cli 0.11.0 → 0.12.0

package/README.md

@@ -6,9 +6,9 @@ Next.js App Router apps and AI coding agents.
 StackNext collects OpenTelemetry spans plus Drizzle/Prisma query events and
 Next.js errors over loopback, stores them in a bounded in-memory sample, and
 exposes a dashboard, CLI and read-only MCP server. It also derives deterministic
-diagnostic findings and compares Playwright-linked runtime captures against
-saved baselines. No cloud account, hosted backend, AI API key or telemetry
-upload.
+diagnostic findings, freezes samples into redacted snapshots and compares
+Playwright-linked runtime captures against saved baselines. No cloud account,
+hosted backend, AI API key or telemetry upload.
 
 ## Quick start
 
@@ -22,12 +22,88 @@ npx stacknext dev
 `init` detects Next.js 15/16 with the App Router, writes
 `stacknext.config.json`, and creates `instrumentation.ts` (or
 `instrumentation.js` for a JavaScript project) only when none exists. Existing
-instrumentation is preserved and a manual hook is printed.
-`dev` starts the loopback collector and the app's own `dev` script.
+instrumentation is preserved and a manual hook is printed. `dev` starts the
+loopback collector and the app's own `dev` script.
 
-Add `@stacknext/drizzle`, `@stacknext/prisma`, or `@stacknext/playwright` only
+Add `@stacknext/drizzle`, `@stacknext/prisma` or `@stacknext/playwright` only
 when you use those integrations.
 
+## Commands
+
+```bash
+stacknext init [--install]
+stacknext dev [--open] [--quiet] [--token <token>] [nextArgs...]
+stacknext status [--json]
+stacknext doctor [--json]
+stacknext coverage [--json]
+stacknext diagnose [--id <id>] [--trace-id <id>] [--category <category>] [--severity <severity>] [--json]
+stacknext capture [--name <name>] -- <test command...>
+stacknext runs list|show
+stacknext baseline save|list|show|remove
+stacknext compare <baseline-id> <candidate-run-id> [--fail-on regression|inconclusive|any]
+stacknext snapshot save|list|show|export|import|delete
+stacknext export [-o <file> | --stdout]
+stacknext uninstall [--yes] [--keep-config] [--remove-data]
+stacknext mcp [--collector <url>] [--token <token>]
+stacknext skill install --client opencode|codex|claude-code
+```
+
+`dev` writes `.stacknext/run.json` (`0600`) and passes the collector URL and
+token to the app. `status`, `doctor`, `coverage`, `diagnose`, `snapshot`,
+`export` and `mcp` use that runtime state. The collector binds to loopback and
+ingestion requires the bearer token.
+
+## Configuration
+
+`stacknext.config.json` is validated by Zod. The main fields cover the project
+name, collector capacity and retention, slow-request threshold, diagnostics
+thresholds, database adapters, error/fetch capture, verbose tracing and
+snapshots. See the installed
+[configuration reference](docs/configuration.md) for every field and default.
+
+## Documentation
+
+- [CLI commands](docs/commands.md)
+- [Configuration](docs/configuration.md)
+- [Agent setup](docs/agent-setup.md)
+- [Agent Skill](docs/skill.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Installed package index](docs/packages.md)
+
+The same files ship in this package under `docs/`, so they match the installed
+version. Public guides live on the
+[documentation site](https://github.com/marrrkkk/stacknext/tree/main/apps/docs).
+
+## AI agents
+
+The CLI ships the portable `stacknext-debugging` Agent Skill and a read-only
+stdio MCP server. Start `stacknext dev`, then configure the client to run
+`stacknext mcp` from the app directory. All MCP tools are read-only and only
+perform GETs against the loopback collector. Install the skill with:
+
+```bash
+stacknext skill install --client opencode
+stacknext skill install --client codex
+stacknext skill install --client claude-code
+```
+
+See [agent setup](docs/agent-setup.md) and the public
+[AI agent guide](https://github.com/marrrkkk/stacknext/blob/main/apps/docs/ai-agents/index.md).
+
+## Development
+
+This package is part of the StackNext pnpm monorepo:
+
+```bash
+pnpm --filter @stacknext/cli build
+pnpm --filter @stacknext/cli typecheck
+pnpm test
+```
+
+The collector and CLI tests use real transport and collector behavior where
+practical. See the repository
+[testing strategy](https://github.com/marrrkkk/stacknext/blob/main/docs/testing/testing-strategy.md).
+
 ## Requirements
 
 - Node.js 20.9 or newer
@@ -35,8 +111,7 @@ when you use those integrations.
 - Playwright 1.40+ for runtime regression capture
 
 Next.js Edge runtime and the Pages Router are not supported. The package is
-ESM-only. See the [project README](https://github.com/marrrkkk/stacknext#readme),
-[getting started](https://github.com/marrrkkk/stacknext/blob/main/docs/getting-started.md)
-and [compatibility matrix](https://github.com/marrrkkk/stacknext/blob/main/docs/compatibility.md).
+ESM-only. See the [project README](https://github.com/marrrkkk/stacknext#readme)
+and [compatibility matrix](https://github.com/marrrkkk/stacknext/blob/main/apps/docs/compatibility.md).
 
 License: MIT.

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CLI_VERSION = "0.11.0";
+export declare const CLI_VERSION = "0.12.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
-export const CLI_VERSION = '0.11.0';
+export const CLI_VERSION = '0.12.0';
 //# sourceMappingURL=version.js.map

package/docs/agent-setup.md

@@ -14,7 +14,7 @@ another.
 
 | Surface | Purpose | Command |
 | --- | --- | --- |
-| Local package documentation | Version-matched API reference | Ships in the seven documented packages |
+| Local package documentation | Version-matched API reference | Ships in the ten documented packages |
 | Managed `AGENTS.md` block | Short project rules and documentation pointers | `stacknext init --agents` |
 | Agent Skill | Detailed evidence-first workflows | `stacknext skill install` |
 | MCP server | Read-only runtime evidence | `stacknext mcp` |
@@ -27,10 +27,11 @@ another.
 
 <!-- coderabbit-ai-generated-section:v1:5322f074c4bd22377289b52567028ebfbba0bcf2a8678742f28a42cbc3ec8e3c -->
 
-The seven packages listed in `DOCUMENTED_PACKAGES` ship `docs/`:
+The ten packages listed in `DOCUMENTED_PACKAGES` ship `docs/`:
 `@stacknext/cli`, `@stacknext/next`, `@stacknext/core`,
-`@stacknext/regression`, `@stacknext/playwright`, `@stacknext/drizzle` and
-`@stacknext/prisma`. Start with the CLI package's
+`@stacknext/diagnostics`, `@stacknext/regression`, `@stacknext/playwright`,
+`@stacknext/drizzle`, `@stacknext/prisma`, `@stacknext/mcp` and
+`@stacknext/dashboard`. Start with the CLI package's
 `docs/index.md`; the managed block below records its actual path, which may be
 at the workspace root. The generated [package index](packages.md) lists the
 documented packages and which docs to read.

package/docs/index.md

@@ -68,11 +68,10 @@ node_modules/@stacknext/playwright/docs/index.md
 
 <!-- coderabbit-ai-generated-section:v1:a2a2d1bacf1a7101a5884977852db99861650a2a201f6dffdf985fa4ec246abe -->
 
-`@stacknext/core` and `@stacknext/regression` are installed through the CLI
-and ship documentation. In a pnpm workspace, locate their docs using the
-relative paths listed in `packages.md`. The CLI also installs
-`@stacknext/diagnostics`, `@stacknext/mcp` and `@stacknext/dashboard`, which
-do not currently ship `docs/` directories.
+`@stacknext/core`, `@stacknext/diagnostics`, `@stacknext/regression`,
+`@stacknext/mcp` and `@stacknext/dashboard` are installed through the CLI and
+ship documentation. In a pnpm workspace, locate their docs using the relative
+paths listed in `packages.md`.
 
 <!-- /coderabbit-ai-generated:v1 -->
 
@@ -84,10 +83,6 @@ its APIs are available.
 
 <!-- coderabbit-ai-generated:v1 -->
 
-<!-- coderabbit-ai-generated-section:v1:cce8643ce7fa90852e67d36250d2daa286bf00bf29c08506b2ca194409f5b5a8 -->
-
-<!-- coderabbit-ai-generated:v1 -->
-
 <!-- coderabbit-ai-generated-section:v1:4ccde9b676836098da0c0e0810b43c6306a967030d387f11f30aed3a2b950eab -->
 
 | Task | Read |
@@ -95,7 +90,7 @@ its APIs are available.
 | Install, configure or run StackNext | `cli`, `next` |
 | Change `instrumentation.ts` or manual spans | `next` |
 | Work with shared types, redaction, transport or snapshots | `core` |
-| Change or interpret diagnostic findings | CLI [commands](commands.md) |
+| Change or interpret diagnostic findings | `diagnostics` and CLI [commands](commands.md) |
 | Work with Playwright capture, baselines or comparisons | `playwright`, `regression` |
 | Add Drizzle query evidence | `drizzle` |
 | Add Prisma query evidence | `prisma` |
@@ -103,8 +98,6 @@ its APIs are available.
 
 <!-- /coderabbit-ai-generated:v1 -->
 
-<!-- /coderabbit-ai-generated:v1 -->
-
 ## Optional and internal packages
 
 <!-- coderabbit-ai-generated:v1 -->

package/docs/packages.md

@@ -17,16 +17,16 @@ directory to confirm the installed version.
 
 | Package | Version | Visibility | Role | Documentation |
 | --- | --- | --- | --- | --- |
-| `@stacknext/cli` | 0.11.0 | public | CLI, collector and dashboard host | `index.md` |
-| `@stacknext/next` | 0.11.0 | public | Next.js instrumentation | `../../next/docs/index.md` |
-| `@stacknext/core` | 0.11.0 | internal | Shared base package | `../../core/docs/index.md` |
-| `@stacknext/diagnostics` | 0.11.0 | internal | Diagnostic engine | `@stacknext/diagnostics/docs/index.md (resolve from CLI)` |
-| `@stacknext/regression` | 0.11.0 | internal | Regression data model | `../../regression/docs/index.md` |
-| `@stacknext/playwright` | 0.11.0 | public | Playwright fixture | `../../playwright/docs/index.md` |
-| `@stacknext/drizzle` | 0.11.0 | public | Database adapter | `../../drizzle/docs/index.md` |
-| `@stacknext/prisma` | 0.11.0 | public | Database adapter | `../../prisma/docs/index.md` |
-| `@stacknext/mcp` | 0.11.0 | internal | Read-only MCP server | `@stacknext/mcp/docs/index.md (resolve from CLI)` |
-| `@stacknext/dashboard` | 0.11.0 | internal | Static dashboard | `@stacknext/dashboard/docs/index.md (resolve from CLI)` |
+| `@stacknext/cli` | 0.12.0 | public | CLI, collector and dashboard host | `index.md` |
+| `@stacknext/next` | 0.12.0 | public | Next.js instrumentation | `../../next/docs/index.md` |
+| `@stacknext/core` | 0.12.0 | internal | Shared base package | `../../core/docs/index.md` |
+| `@stacknext/diagnostics` | 0.12.0 | internal | Diagnostic engine | `@stacknext/diagnostics/docs/index.md (resolve from CLI)` |
+| `@stacknext/regression` | 0.12.0 | internal | Regression data model | `../../regression/docs/index.md` |
+| `@stacknext/playwright` | 0.12.0 | public | Playwright fixture | `../../playwright/docs/index.md` |
+| `@stacknext/drizzle` | 0.12.0 | public | Database adapter | `../../drizzle/docs/index.md` |
+| `@stacknext/prisma` | 0.12.0 | public | Database adapter | `../../prisma/docs/index.md` |
+| `@stacknext/mcp` | 0.12.0 | internal | Read-only MCP server | `@stacknext/mcp/docs/index.md (resolve from CLI)` |
+| `@stacknext/dashboard` | 0.12.0 | internal | Static dashboard | `@stacknext/dashboard/docs/index.md (resolve from CLI)` |
 
 ## How to use this index
 

package/docs/skill.md

@@ -67,7 +67,7 @@ along with package versions.
 `SKILL.md` follows the Agent Skills specification with YAML frontmatter and a
 concise body. Details live in `references/`. Keep it portable: no
 client-specific syntax in the canonical skill and no claim of support without a
-recorded test in `docs/agent-testing.md`.
+recorded test in `docs/testing/agent-compatibility.md`.
 
 ## Client paths
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacknext/cli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Local-first runtime debugging, diagnostics and Playwright regression testing for Next.js",
   "license": "MIT",
   "type": "module",
@@ -23,11 +23,11 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@stacknext/core": "0.11.0",
-    "@stacknext/dashboard": "0.11.0",
-    "@stacknext/diagnostics": "0.11.0",
-    "@stacknext/mcp": "0.11.0",
-    "@stacknext/regression": "0.11.0",
+    "@stacknext/core": "0.12.0",
+    "@stacknext/dashboard": "0.12.0",
+    "@stacknext/diagnostics": "0.12.0",
+    "@stacknext/mcp": "0.12.0",
+    "@stacknext/regression": "0.12.0",
     "commander": "14.0.3",
     "zod": "4.6.7"
   },

package/skills/stacknext-debugging/SKILL.md

@@ -4,7 +4,7 @@ description: Investigate Next.js App Router runtime behavior with StackNext's lo
 license: MIT
 compatibility: Next.js 15 or 16 App Router on the Node.js runtime, with a local StackNext collector. No cloud account, AI API key, or remote service is required.
 metadata:
-  version: "0.11.0"
+  version: "0.12.0"
   author: StackNext
 ---
 

package/skills/stacknext-debugging/references/setup.md

@@ -23,7 +23,7 @@ If the project is not set up yet:
 2. Run `pnpm exec stacknext init` in the app. Add `--agents` if the user wants a
    managed StackNext block in `AGENTS.md`.
 3. In a StackNext source checkout, run `pnpm install && pnpm build` first and
-   see `docs/getting-started/quickstart.md`.
+   see the [quickstart](https://github.com/marrrkkk/stacknext/blob/main/apps/docs/getting-started/quickstart.md).
 
 Check the collector and instrumentation:
 
@@ -177,8 +177,8 @@ pnpm exec stacknext baseline save --run <run-id> --name main
 pnpm exec stacknext compare <baseline-id> <candidate-run-id>
 ```
 
-See [runtime regression testing](../../../docs/regression-testing.md) and
-[Playwright integration](../../../docs/playwright-integration.md).
+See [runtime regression testing](https://github.com/marrrkkk/stacknext/blob/main/apps/docs/regression-testing.md)
+and [Playwright integration](https://github.com/marrrkkk/stacknext/blob/main/apps/docs/playwright-integration.md).
 
 The three snapshot tools read frozen records from `.stacknext/snapshots`. They
 cannot save, import, rotate or delete a snapshot. Save one from the dashboard

package/skills/stacknext-debugging/references/tools.md

@@ -55,8 +55,8 @@ immutable snapshots and are never deleted by these tools.
       "instrumentation": "connected",
       "instances": 1,
       "lastSeen": "2026-11-02T11:59:59.000Z",
-      "sdkVersion": "0.6.1",
-      "collectorVersion": "0.6.1"
+      "sdkVersion": "0.11.0",
+      "collectorVersion": "0.11.0"
     },
     "completeness": { "complete": true, "reasons": [] },
     "notes": []