coderefineranalytic

Terminal-based hybrid runtime analysis for Next.js apps. One command runs an end-to-end pipeline: route discovery → parallel Lighthouse + Chrome DevTools Protocol (CDP) audits → deterministic scoring → compact payloads for AI root-cause analysis (Cursor CLI + Chrome DevTools MCP) → merged JSON / Markdown / HTML reports → publish to the codeRefiner analytics database (shown in the dashboard's Scheduled analysis mode).

The key architectural idea: deterministic automation first, AI reasoning last. Healthy pages never reach the AI — a page is flagged only when it has at least one Critical violation, or 2+ Moderate violations (minModerateViolations); Minimal-only or single-Moderate pages stay healthy. Flagged pages are additionally capped at 50% of all scanned pages (maxFlaggedRatio) — when more pages fail, only the worst-ranked ones (Critical first, then by weighted violation score) keep the flagged slots. Both knobs are tunable via --config.

The tool never writes into the user's codebase: all report artifacts go to a temporary directory outside the project (pass --out <dir> to opt into a specific location), and the results are published to the analytics database.

Pipeline

┌─────────────────┐   ┌──────────────────────┐   ┌──────────────────┐
│ 1. Route         │   │ 2. Parallel scanning │   │ 3. Deterministic │
│    discovery     │──▶│    Lighthouse + CDP  │──▶│    scoring        │
│  app/ or pages/  │   │    N Chrome workers  │   │    thresholds     │
└─────────────────┘   └──────────────────────┘   └───────┬──────────┘
                                                  healthy │ flagged
                                                 ┌────────┴─────────┐
                                                 ▼                  ▼
                                          stored for report  ┌──────────────┐
                                                              │ 4. AI agent  │
                                                              │  Cursor CLI  │
                                                              │  + DevTools  │
                                                              │    MCP       │
                                                              └──────┬───────┘
                                                                     ▼
                                                          ┌──────────────────┐
                                                          │ 5. Final report  │
                                                          │  JSON · MD · HTML│
                                                          └──────────────────┘

Requirements

• Node.js ≥ 18.17 (uses built-in fetch and util.parseArgs)
• Google Chrome (or Chromium) installed — found automatically via chrome-launcher
• The target app running at the base URL (next dev or next start)
• Optional, for the AI stage: Cursor CLI (cursor-agent) or Claude Code (--agent-cmd claude), with the Chrome DevTools MCP server configured in ~/.cursor/mcp.json under the key chrome-devtools, and CURSOR_API_KEY set for headless runs

Install

npm install -g coderefineranalytic

Or run once without installing:

npx coderefineranalytic

For local development inside this repo:

npm install
npm link           # optional: makes `coderefineranalytic` available globally

Usage

Interactive wizard (recommended)

Run with no arguments from any directory. You will be prompted for three fields:

coderefineranalytic

CodeRefiner Analytic — Next.js runtime analysis

Project / repo path [.]: .
App path (relative to project) [apps/website]: apps/website
Base URL [http://localhost:3000]: http://localhost:3001

Starting analysis...

This is equivalent to:

coderefineranalytic \
  --project . \
  --app apps/website \
  --base-url http://localhost:3001

Results are published to https://coderefiner-server.onrender.com by default.

Advanced CLI (flags)

Pass any CLI flag to skip the wizard and use full options:

# Monorepo app
coderefineranalytic \
  --project ~/work/shop-monorepo \
  --app apps/storefront \
  --base-url http://localhost:3000

# Standalone app, deterministic-only (no AI stage)
coderefineranalytic --project . --app . --base-url http://localhost:3000 --no-ai

# Preview which routes were discovered, without scanning
coderefineranalytic --project . --app . --base-url http://localhost:3000 --dry-run

# Trial run: 5 pages, 2 parallel Chrome instances, mobile emulation
coderefineranalytic --project . --app . --base-url http://localhost:3000 \
  --limit 5 --concurrency 2 --form-factor mobile

The coderefiner-runtime command is also available as a backward-compatible alias (always uses the flag-based CLI, no wizard).

Without npm link, replace coderefineranalytic with node bin/coderefineranalytic.js.

Resolving dynamic routes

Static routes are scanned automatically. Dynamic routes (/blog/[slug]) are resolved from, in priority order:

1. --params file you provide:

   {
     "/blog/[slug]": [{ "slug": "hello-world" }, { "slug": "second-post" }],
     "/shop/[category]/[id]": [{ "category": "shoes", "id": "42" }],
     "/docs/[...path]": [{ "path": ["guides", "install"] }]
   }

2. .next/prerender-manifest.json — reflects generateStaticParams / getStaticPaths output (run next build first to populate it)
3. .next/routes-manifest.json
4. sitemap.xml fetched from the base URL

Anything still unresolved is skipped and reported so results stay deterministic.

Custom thresholds

Pass --config thresholds.json:

{
  "thresholds": {
    "performanceScore": 85,
    "lcpMs": 2000,
    "clsMax": 0.05,
    "maxConsoleErrors": 2,
    "maxDomNodes": 3500
  }
}

See src/scoring.js (DEFAULT_THRESHOLDS) for every available key.

The AI stage

For each flagged page a compact payload (violations, CWV, console errors, exceptions, failed requests, long tasks, memory stats, DOM complexity, coverage, layout-shift sources) is written to flagged-payloads.json. The tool then invokes cursor-agent in batches (default 5 pages per session) so each agent run can fully execute Chrome DevTools MCP on every URL in the batch:

cursor-agent -p --trust --output-format stream-json --approve-mcps --force "<prompt>"

Before Stage 4, the tool runs an MCP preflight check (~/.cursor/mcp.json must contain a valid chrome-devtools entry; warns if CURSOR_API_KEY is unset).

The agent runs at full capability with cwd set to your project so it can drive the DevTools MCP server (user-chrome-devtools) and search the source code. To keep your codebase clean, the tool snapshots the file tree before each batch and deletes any stray files the agent creates afterwards.

Output is streamed as stream-json, so the terminal shows a live trace — MCP navigations, performance traces, file reads, greps — logged with an [ai] prefix. When multiple batches run, artifacts are saved per batch:

| File | Contents | |------|----------| | agent-prompt-batch-N.txt | Prompt for batch N | | agent-stream-batch-N.jsonl | Raw event stream for batch N | | flagged-payloads-batch-N.json | Payloads for batch N |

The prompt embeds zero-hallucination guardrails, mandatory MCP runtime rules, and the full codeRefiner parameter strategy playbooks (src/parameter-strategies.js). The agent must execute every runtime strategy on each flagged page in the batch via Chrome DevTools MCP, then correlate evidence with source files using compile-time strategies.

• Adjust batch size: --ai-batch-size 5 or { "aiBatchSize": 5 } in --config
• Use a different agent: --agent-cmd claude
• Skip entirely: --no-ai

The agent does not write files. It ends its response with one structured JSON result (between <<<CODEREFINER_RESULT>>> markers) where every finding carries: severity, the exact problem, the root cause (why), the concrete fix (suggestion + numbered action steps), file location/line, before/after code, verification evidence, pageUrl, expectedImpact, and confidence. The tool parses that JSON, renders ai-analysis.md from it, and includes it in the published payload.

• The full prompt sent to the agent is saved to agent-prompt.txt (or agent-prompt-batch-N.txt)
• The raw agent event stream is saved to agent-stream.jsonl (or agent-stream-batch-N.jsonl)

Publishing to the analytics database

After the report stage the results are POSTed to the codeRefiner analytics server (/api/v1/ingest/runtime) into collections dedicated to scheduled runtime analysis — completely separate from the VS Code extension's daily-analysis data. The dashboard's Scheduled analysis mode lists each app with its page routes, web-vitals scores, issue counts, threshold violations, and the AI findings with root causes and fixes.

• Identify the app: --app-key my-storefront (defaults to the app's package.json name)
• Point at a different server: --server-url http://localhost:4000 (default: https://coderefiner-server.onrender.com)
• Skip publishing: --no-publish

Output

Everything lands in a fresh temporary directory (printed at the end of the run) so the user's workspace is never touched; pass --out <dir> to choose a location explicitly:

| File | Contents | | ----------------------- | ----------------------------------------------------- | | report.json | Full merged deterministic dataset (for DB ingestion) | | report.md | Human-readable Markdown summary | | report.html | Self-contained visual dashboard | | flagged-payloads.json | Compact AI payloads (only when pages were flagged) | | ai-analysis.md | AI root-cause report (only when the AI stage ran) | | agent-prompt.txt | Exact prompt sent to the AI agent | | agent-stream.jsonl | Raw agent event stream (every step it took) |

All options

Run coderefineranalytic --help for the full list: --concurrency, --params, --config, --out, --form-factor, --limit, --include, --timeout, --agent-cmd, --ai-batch-size, --no-interact, --no-lighthouse, --no-ai, --dry-run, --chrome-path.

CI/CD

The command is non-interactive and exits 0 on completion, so it drops straight into a scheduled job or pipeline step.

GitLab (scheduled every 5 hours): see docs/GITLAB_SETUP.md and copy templates/gitlab-scheduled-analysis.yml into your repo's .gitlab-ci.yml. The job installs Chrome, cursor-agent, Chrome DevTools MCP, runs the full AI pipeline, and publishes to the analytics server.

GitHub Actions (deterministic-only example):

- run: npx next build && npx next start &          # start the app
- run: npx wait-on http://localhost:3000
- run: npx coderefineranalytic --project . --app . \
         --base-url http://localhost:3000 --no-ai --concurrency 2
- uses: actions/upload-artifact@v4
  with: { name: coderefiner-report, path: coderefiner-report/ }

Parse report.json (summary.bySeverity.Critical) to fail builds on regressions.