feat(traffic): add analytics contracts and authenticated CLI/MCP queries

[mrgoonie]

End-to-end work summary

Adds Analytics document blocks and organization-authorized product traffic to the contracts, CLI and MCP. Integrates the new MCP tool with the current OAuth delegation path and adds production MCP deployment after main CI passes.

Subagent delegation

Toolkit delivery is delegated from the traffic analytics controller. A separate reviewer dispatch was attempted but unavailable because the runtime agent limit was reached; local source review and verification completed.

Technical decisions

• get_product_traffic requires OAuth mcp:read or legacy Worker authentication. OAuth requests sign a request-bound assertion and never forward shared API keys or the access token. Existing anonymous public reads remain available.
• CLI uses existing API-key configuration and returns the full validated traffic response with --json.
• Analytics blocks opt into public aggregates when published; private breakdowns retain web organization authorization.
• Deployment follows successful main CI, uses the existing Worker configuration, and preserves Worker secrets.

Deviations from plan

The local checkout predated current OAuth support. Integrated origin/main before adapting traffic delegation and authentication. Package versions remain 0.2.0 for the first publication; no published versions were found.

Completion evidence

• Focused traffic and OAuth suites: 31 tests passed.
• Full npm test: 113 tests passed across 16 files.
• npm run build --prefix packages/contracts, packages/cli, packages/mcp: passed.
• npm run type-check --prefix packages/contracts, packages/cli, packages/mcp: passed.
• git diff --check: passed.
• Real signed-token integration verifies private-read challenge, insufficient scope, delegation claims, no credential forwarding, and credential override rejection.
• Local source review found no unresolved critical or important code issues. CI and live deployment verification follow this PR.

Checklist

• Contracts, CLI and MCP implemented and documented
• OAuth/private-read guards and regression tests verified
• Full tests, package builds and type-checks passed
• CI and deployed MCP smoke tests pending
• npm publication blocked by registry authentication

Human actions required

Registry login must be renewed or a valid repository NPM_TOKEN supplied before first package publication: local npm whoami returns E401 and the repository has no npm publishing secret. Production Cloudflare deployment credentials are being provisioned by the traffic delivery controller.

Linked Issues

Closes #9

Ship Mode

Official; target main. English prose uses the installed writing-language resolver default.

[mrgoonie]

Summary: Adds Analytics blocks, CLI traffic queries and the authenticated MCP traffic tool, with CI-gated production Worker deployment.

Risk level: Medium. The authorization and deployment paths changed; scope and credential boundaries are explicitly covered.

Findings: No unresolved Critical or Important issues in the reviewed diff. Private traffic requires OAuth mcp:read or authenticated legacy Worker context; delegated requests use the existing allowlist/redirect controls and request-bound assertion without forwarding shared API keys or OAuth tokens. Public reads retain existing behavior.

Verdict: Approve.

Evidence: Full local suite 113/113; package builds and type checks clean; all nine CI matrix jobs green at ac70bdb (run 34683891566). npm publication remains blocked by registry authentication and is not claimed complete. Independent child review dispatch was unavailable because of the runtime agent limit.

Posted as COMMENT because the authenticated account owns this PR; this is not an independent GitHub approval.

Posted by the installed review-pr skill at 2026-09-12T08:43:00Z