@adonis-agora/telescope 0.8.4 → 0.9.0

package/skills/telescope-access-mcp/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: telescope-access-mcp
+description: >-
+  Dashboard access control and the MCP endpoint in @adonis-agora/telescope —
+  config/telescope_ui.ts authorize(ctx) hook vs credentials { token, basic },
+  dashboardAuth { secret, ttl, login } login screen, defaultAuthorize (allow outside
+  production, deny in production), 401-vs-403 fail-closed guard semantics,
+  redirect-wins behaviour, replay/queueActions/cpuProfiling.armEnabled mutation
+  gates, and config/telescope_mcp.ts JSON-RPC tools behind the same guard. Use for
+  "lock down the dashboard", "dashboard open in production", "401 on /telescope",
+  "login wall", "expose telescope to Claude Code", "replay returns 403".
+license: MIT
+metadata:
+  type: core
+  library: "@adonis-agora/telescope"
+  library_version: "0.8.4"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-telescope:docs/dashboard/auth.mdx"
+  - "DavideCarvalho/adonis-telescope:docs/packages/mcp.mdx"
+  - "DavideCarvalho/adonis-telescope:docs/packages/ui.mdx"
+---
+
+# Dashboard access control & MCP
+
+Every route serving recorded data runs an `authorize` guard first — every
+`<path>/api/*` endpoint, the SSE stream, metrics and the SPA routes. Out of the box
+the policy is **allow outside production, deny in production** until a credential or
+hook permits it. The MCP subpath reuses exactly the same guard.
+
+## Setup
+
+The simplest production gate is a built-in credential; either `token` or `basic`,
+or both:
+
+```ts
+// config/telescope_ui.ts
+import env from '#start/env'
+import { defineConfig } from '@adonis-agora/telescope/ui'
+
+export default defineConfig({
+  enabled: true,
+  path: '/telescope',
+  credentials: { token: env.get('TELESCOPE_UI_TOKEN') },
+})
+```
+
+```sh
+curl -H 'Authorization: Bearer s3cr3t' http://localhost:3333/telescope/api/entries
+open 'http://localhost:3333/telescope?token=s3cr3t'   # ?token= is convenient but leaky
+```
+
+Source: `docs/dashboard/auth.mdx` (Built-in credentials).
+
+## Core patterns
+
+### Pattern 1 — delegate to your app's auth
+
+When you set `authorize`, the built-in `credentials` gate is ignored — your hook IS
+the whole policy. It receives your **real** `HttpContext` through a framework-light
+declared type, so narrow it to reach `auth`/`session` at runtime.
+
+```ts
+// config/telescope_ui.ts
+export default defineConfig({
+  async authorize(ctx) {
+    const { auth } = ctx as unknown as {
+      auth: { check(): Promise<boolean>; user?: { role?: string } }
+    }
+    await auth.check()
+    return auth.user?.role === 'admin'
+  },
+})
+```
+
+Guard outcomes: denied with no credential → `401` (+ `WWW-Authenticate`); denied
+with a rejected credential → `403`; a throwing hook → `403` (fail-closed).
+
+Source: `docs/dashboard/auth.mdx` (Delegate to your app's auth, Guard behaviour).
+
+### Pattern 2 — a real login wall with dashboardAuth
+
+For shared human access: a server-rendered login page plus a signed session cookie.
+It composes WITH `authorize` (both must pass). Missing `secret` or `login` throws at
+boot rather than shipping an un-mintable gate.
+
+```ts
+// config/telescope_ui.ts
+import env from '#start/env'
+import User from '#models/user'
+import hash from '@adonisjs/core/services/hash'
+import { defineConfig } from '@adonis-agora/telescope/ui'
+
+export default defineConfig({
+  dashboardAuth: {
+    secret: env.get('TELESCOPE_DASHBOARD_SECRET'),   // HMAC-SHA256 key, 32+ bytes — required
+    ttl: '8h',
+    async login(username, password) {
+      const user = await User.findBy('email', username)
+      if (!user || !(await hash.verify(user.password, password))) return null
+      if (!user.isAdmin) return null
+      return { id: String(user.id), name: user.fullName }   // session user, or null to deny
+    },
+  },
+})
+```
+
+This mounts unguarded-by-necessity `GET/POST <path>/login` and `GET <path>/logout`
+routes (they mint/clear the session only — no recorded data sits behind them).
+An unauthenticated page navigation gets a `302` to the login; an unauthenticated API
+call gets a plain `401`.
+
+Source: `docs/dashboard/auth.mdx` (Built-in login screen).
+
+### Pattern 3 — redirect instead of answering JSON
+
+If the hook sets a `location` header and then returns `false`, the guard leaves the
+redirect alone instead of overwriting it with a `403` body.
+
+```ts
+authorize: (ctx) => {
+  const { auth } = ctx as unknown as { auth: { user?: { isAdmin?: boolean } } }
+  if (auth.user?.isAdmin === true) return true
+  ctx.response.redirect('/login?next=/telescope')
+  return false   // redirect wins only when the hook returns false
+}
+```
+
+Source: `docs/dashboard/auth.mdx` (Redirecting instead of answering JSON).
+
+### Pattern 4 — expose the store to coding agents over MCP
+
+```ts
+// config/telescope_mcp.ts
+import env from '#start/env'
+import { defineConfig } from '@adonis-agora/telescope/mcp'
+
+export default defineConfig({
+  enabled: true,
+  path: '/telescope/mcp',
+  credentials: { token: env.get('TELESCOPE_MCP_TOKEN') },   // same guard as the dashboard
+  // tools: ['list_entries', 'get_trace', 'get_health'],    // hand agents a narrower surface
+})
+```
+
+```sh
+claude mcp add --transport http telescope https://your-app.example.com/telescope/mcp \
+  --header 'Authorization: Bearer <TELESCOPE_MCP_TOKEN>'
+```
+
+Six read tools ship: `list_entries`, `get_entry`, `get_trace`, `get_waterfall`,
+`get_health`, `diagnose_exception`. Redaction and sampling are never bypassed — an
+agent sees exactly what the dashboard sees.
+
+Source: `docs/packages/mcp.mdx`.
+
+### Pattern 5 — gate the dangerous mutations
+
+Replay, CPU-arm and queue retry/enqueue are each disabled by default and answer
+`403` until their ui-config gate is flipped — even when the underlying feature is
+enabled.
+
+```ts
+export default defineConfig({
+  replay: { enabled: true },          // POST <path>/api/requests/:id/replay — re-runs a real request!
+  cpuProfiling: { armEnabled: true }, // POST <path>/api/profiles/arm
+  queueActions: { enabled: true },    // queue console retry/enqueue
+})
+```
+
+Source: `docs/packages/ui.mdx` (Configuration, Request replay),
+`docs/packages/cpu-profiling.mdx` (arming callout).
+
+## Common mistakes
+
+### CRITICAL Relying on an obscure path instead of the guard
+
+```ts
+// Wrong — renaming the prefix is defense in depth, not authentication:
+defineConfig({ path: '/__telescope' })   // production: denied anyway without a credential/hook
+```
+
+```ts
+// Correct — make a deliberate choice for production:
+defineConfig({
+  path: '/__telescope',
+  credentials: { token: env.get('TELESCOPE_UI_TOKEN') },
+})
+```
+
+Mechanism: the default policy denies production until a credential or `authorize`
+hook permits it — but that deny is the *default*, never a guarantee you can skip
+configuring; security notes call this out explicitly.
+Source: `docs/dashboard/auth.mdx` (default policy warn + Security notes).
+
+### MEDIUM Setting credentials AND an authorize hook expecting both to run
+
+```ts
+// Wrong — the token gate silently stops mattering once authorize is set.
+defineConfig({
+  credentials: { token: env.get('TELESCOPE_UI_TOKEN') },
+  authorize: () => true,   // now the whole policy; credentials ignored
+})
+```
+
+```ts
+// Correct — pick one: credentials for simple gates, authorize for real policies.
+defineConfig({ credentials: { basic: { username: 'admin', password: env.get('TELESCOPE_UI_PASSWORD') } } })
+```
+
+Mechanism: the docs state the built-in `credentials` gate is ignored whenever
+`authorize` is set — your hook replaces it entirely (`dashboardAuth`, by contrast,
+composes with `authorize`).
+Source: `docs/dashboard/auth.mdx` (Delegate to your app's auth).
+
+### MEDIUM Reaching for ctx.auth without narrowing the context
+
+```ts
+// Wrong — does not type-check: the declared parameter is a minimal HTTP slice.
+authorize: (ctx) => ctx.auth.user?.isAdmin === true
+```
+
+```ts
+// Correct — narrow to the slice you rely on; the REAL HttpContext passes through.
+authorize: (ctx) => {
+  const { auth } = ctx as unknown as { auth: { user?: { isAdmin?: boolean } } }
+  return auth.user?.isAdmin === true
+}
+```
+
+Mechanism: the guard's declared shape is framework-light (`request.qs()`,
+`request.header()`, `response`) so any server can satisfy it; `auth`/`session`
+exist at runtime only after narrowing.
+Source: `docs/dashboard/auth.mdx` (narrowing info callout).
+
+### HIGH Exposing MCP in production without a token credential
+
+```ts
+// Wrong — relies on the dev-open default; prod denials surface as opaque JSON-RPC errors.
+defineConfig({ enabled: true, path: '/telescope/mcp' })
+```
+
+```ts
+// Correct — a token/basic credential for production.
+defineConfig({
+  path: '/telescope/mcp',
+  credentials: { token: env.get('TELESCOPE_MCP_TOKEN') },
+})
+```
+
+Mechanism: MCP has no transport-level 401 — denial rides inside the JSON-RPC
+envelope as `-32001` (`MCP_UNAUTHORIZED`), which compliant clients just report as a
+failed call.
+Source: `docs/packages/mcp.mdx` (guard info callout).
+
+### MEDIUM Configuring dashboardAuth without secret or login
+
+```ts
+// Wrong — both keys are required; this throws at boot.
+defineConfig({ dashboardAuth: { secret: env.get('TELESCOPE_DASHBOARD_SECRET') } })
+defineConfig({ dashboardAuth: { login: verifyCreds } })
+```
+
+```ts
+// Correct — non-empty secret AND a login hook.
+defineConfig({
+  dashboardAuth: {
+    secret: env.get('TELESCOPE_DASHBOARD_SECRET'),
+    ttl: '8h',
+    login: verifyCreds,
+  },
+})
+```
+
+Mechanism: the cookie can never be minted without a signing key and a validator, so
+the config fails closed at startup rather than shipping an un-loginable wall.
+Source: `docs/dashboard/auth.mdx` (Built-in login screen table + warn callout).
+
+See also: `telescope-ui-dashboard/SKILL.md` — the SPA behind these gates;
+`telescope-alerts-ai/SKILL.md` — the diagnose route this guard covers.

package/skills/telescope-alerts-ai/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: telescope-alerts-ai
+description: >-
+  Alerting, AI diagnosis and client-error ingestion in @adonis-agora/telescope —
+  config/telescope_alerts.ts with AlertRule types (new-exception, every-exception,
+  exception-rate, stateful metric-threshold), channel helpers (slackChannel,
+  webhookChannel, consoleChannel, customChannel), every/cooldown/instanceId/
+  geoLookup; config/telescope_ai.ts + TelescopeAiDiagnoser Claude diagnosis cached
+  by familyHash (keyless = disabled); clientErrors sendBeacon endpoint. Use for
+  "Slack alert on new errors", "AI diagnose exceptions", "page on every error",
+  "report browser errors", "why didn't my alert fire".
+license: MIT
+metadata:
+  type: core
+  library: "@adonis-agora/telescope"
+  library_version: "0.8.4"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-telescope:docs/packages/alerts.mdx"
+  - "DavideCarvalho/adonis-telescope:docs/packages/ai.mdx"
+  - "DavideCarvalho/adonis-telescope:docs/packages/client-errors.mdx"
+  - "DavideCarvalho/adonis-telescope:packages/core/src/alerts/index.ts"
+---
+
+# Alerting, AI diagnosis & client errors
+
+The alerter polls the store on an interval, evaluates rules over recorded
+`exception` entries, and fans each fire out to every configured channel. The AI
+subpath attaches a Claude root-cause diagnosis to an exception, cached by family.
+Client-error ingestion lets browsers report their own failures into the same
+pipeline. All three are subpaths of the one package — enable them via
+`node ace configure @adonis-agora/telescope` (pick **Alerts** / **AI**).
+
+## Setup
+
+```ts
+// config/telescope_alerts.ts
+import env from '#start/env'
+import { defineConfig } from '@adonis-agora/telescope/alerts'
+
+export default defineConfig({
+  channels: [{ type: 'slack', url: env.get('TELESCOPE_SLACK_WEBHOOK') }],
+  rules: [{ type: 'new-exception', window: '1h' }],
+  dashboardUrl: 'https://telescope.example.com/', // enables Slack deep links
+  every: '30s',        // poll cadence — alerts are as late as the interval
+  cooldown: '15m',     // per-rule / per-family re-notify suppression
+})
+```
+
+```ts
+// config/telescope_ai.ts
+import env from '#start/env'
+import { defineConfig } from '@adonis-agora/telescope/ai'
+
+export default defineConfig({
+  apiKey: env.get('ANTHROPIC_API_KEY'),   // validate as Env.schema.string.optional()
+  model: 'claude-sonnet-4-6',             // default; claude-opus-4-8 / claude-haiku-4-5-20251001
+  maxTokens: 1024,
+})
+```
+
+Durations are validated at boot — an unparseable `every`/`cooldown`/`window`
+(`'15min'`, a typo) **throws**, fail-closed. Valid units: `ms`, `s`, `m`, `h`, `d`.
+
+Source: `docs/packages/alerts.mdx` (Configuration),
+`docs/packages/ai.mdx` (Configuration).
+
+## Core patterns
+
+### Pattern 1 — pick rules deliberately
+
+```ts
+rules: [
+  { type: 'new-exception', window: '1h' },   // first sighting of a family (+ recurrences after it)
+  { type: 'every-exception', window: '15m' },// EVERY server + browser error, cooldown-limited per family;
+                                             // window is display-only (labels the occurrence count)
+  { type: 'exception-rate', window: '5m', threshold: 10 },
+  {
+    type: 'metric-threshold',                // stateful raise/auto-resolve, evaluated on every poll
+    metric: 'request-p99-ms',                // or query-p95-ms, cache-hit-rate, exception-count, ...
+    window: '5m',
+    comparator: 'gte',
+    threshold: 800,
+    minSamples: 10,                          // guard percentiles against a single slow request
+  },
+]
+```
+
+`new-exception` dedup is a bounded per-process map — in a multi-replica deploy the
+same family reports "new" once per replica, so budget `cooldown` accordingly.
+
+Source: `docs/packages/alerts.mdx` (Rules, Deduplication).
+
+### Pattern 2 — diagnose an exception with its trace context
+
+`TelescopeAiDiagnoser` is always resolvable from the container — even when disabled,
+when `diagnose` resolves `null` — so you can inject it without a null check.
+
+```ts
+// app/controllers/diagnose_controller.ts
+import { inject } from '@adonisjs/core'
+import type { HttpContext } from '@adonisjs/core/http'
+import { TelescopeService } from '@adonis-agora/telescope'
+import { TelescopeAiDiagnoser } from '@adonis-agora/telescope/ai'
+
+@inject()
+export default class DiagnoseController {
+  constructor(
+    private telescope: TelescopeService,
+    private diagnoser: TelescopeAiDiagnoser,
+  ) {}
+
+  async show({ params, response }: HttpContext) {
+    const entry = await this.telescope.find(params.id)
+    if (!entry || entry.type !== 'exception') {
+      return response.notFound({ error: 'Not an exception entry' })
+    }
+    const related = entry.traceId ? await this.telescope.byTrace(entry.traceId) : []
+    const diagnosis = await this.diagnoser.diagnose(entry, { related })
+    // → { cause, fix, confidence, model, cached } | null — never throws
+    return response.json(diagnosis)
+  }
+}
+```
+
+Diagnoses cache per `familyHash` (bounded LRU, 24h TTL); pass `{ force: true }` to
+spend a fresh call after changing code.
+
+Source: `docs/packages/ai.mdx` (Use it), `docs/recipes/ai-exception-diagnosis.mdx`.
+
+### Pattern 3 — a custom channel sink
+
+Channels fan out concurrently; one failing never blocks the others.
+
+```ts
+import { defineConfig, customChannel, slackChannel } from '@adonis-agora/telescope/alerts'
+import env from '#start/env'
+
+export default defineConfig({
+  channels: [
+    slackChannel(env.get('TELESCOPE_SLACK_WEBHOOK'), { username: 'Telescope' }),
+    customChannel(async (alert) => { await pagerduty.trigger(alert) }, 'pagerduty'),
+  ],
+  rules: [{ type: 'new-exception', window: '1h' }],
+})
+```
+
+Exception alerts carry `{ cause, fix, confidence, model }` when AI is configured —
+a guarded hook, so a slow model never delays or breaks the page.
+
+Source: `docs/packages/alerts.mdx` (Channels).
+
+### Pattern 4 — ingest browser errors
+
+Disabled by default; the route only exists once you enable it. Report with
+`navigator.sendBeacon`; entries become `client_exception` records through the same
+redaction/sampling/prune pipeline as server exceptions.
+
+```ts
+// config/telescope.ts
+export default defineConfig({
+  clientErrors: {
+    enabled: true,
+    path: '/telescope/client-errors',
+    maxBodyBytes: 32_768,          // larger bodies rejected 413 before validation
+    rateLimit: { perMinute: 60 },  // per-IP token bucket; over → 429
+  },
+})
+```
+
+```ts
+// Browser reporter
+window.addEventListener('error', (event) => {
+  navigator.sendBeacon(
+    '/telescope/client-errors',
+    JSON.stringify({
+      message: event.message,
+      name: event.error?.name ?? null,
+      stack: event.error?.stack ?? null,
+      url: location.href,
+      userAgent: navigator.userAgent,
+    }),
+  )
+})
+```
+
+Only `message` is required; `clientIp` is filled server-side, never trusted from
+the body.
+
+Source: `docs/packages/client-errors.mdx`.
+
+## Common mistakes
+
+### HIGH Listing two rules of the same exception type
+
+```ts
+// Wrong — the second new-exception rule is SILENTLY ignored.
+rules: [
+  { type: 'new-exception', window: '1h' },
+  { type: 'new-exception', window: '24h' },
+]
+```
+
+```ts
+// Correct — at most one of each exception rule; express variations via window/threshold.
+rules: [
+  { type: 'new-exception', window: '1h' },
+  { type: 'exception-rate', window: '5m', threshold: 10 },
+]
+```
+
+Mechanism: `new-exception`, `every-exception` and `exception-rate` are looked up
+once by type; duplicates never evaluate (`metric-threshold` is exempt).
+Source: `docs/packages/alerts.mdx` (When rules do and don't run).
+
+### HIGH Shipping AI config without a resolvable key
+
+```ts
+// Wrong — keyless install looks configured but silently does nothing:
+export default defineConfig({ model: 'claude-opus-4-8' })   // no apiKey, no client
+const diagnosis = await diagnoser.diagnose(entry)           // always null
+```
+
+```ts
+// Correct — source the key from validated env; check isConfigured() when unsure.
+export default defineConfig({ apiKey: env.get('ANTHROPIC_API_KEY') })
+```
+
+Mechanism: a configured-but-keyless install is treated as disabled — `diagnose`
+resolves `null` forever and the dashboard hides the Diagnose button, with no error
+anywhere.
+Source: `docs/packages/ai.mdx` (warn callout), `docs/reference/configuration.mdx` (AI).
+
+### MEDIUM Expecting sampled-out exceptions to page
+
+```ts
+// Wrong — sampling drops most queries AND some exceptions before any rule sees them.
+sampling: { default: 0.1 },
+rules: [{ type: 'new-exception', window: '1h' }],
+```
+
+```ts
+// Correct — tail-sampling keeps errors/slow regardless of rate.
+sampling: { default: 0.1, exception: { rate: 0.1, keepErrors: true } },
+```
+
+Mechanism: only what was recorded is alertable — sampling and the overload shed run
+before the alerter's poll, and polling itself adds up to `every` of latency.
+Source: `docs/packages/alerts.mdx` (How it hooks in).
+
+### MEDIUM Short cooldown with every-exception
+
+```ts
+// Wrong — a tight loop of the same error re-pages once per cooldown... which is 1 minute.
+rules: [{ type: 'every-exception' }],
+cooldown: '1m',
+```
+
+```ts
+// Correct — tune cooldown to your on-call tolerance; different families still page immediately.
+rules: [{ type: 'every-exception', window: '15m' }],
+cooldown: '10m',
+```
+
+Mechanism: cooldown is the *only* thing rate-limiting repeats per family (on its own
+independent clock from `new-exception`), so a short one on a noisy family is a
+self-inflicted alert storm.
+Source: `docs/packages/alerts.mdx` (cooldown info callout).
+
+### MEDIUM Probing for the client-error endpoint while it is disabled
+
+```sh
+# Wrong — expecting a 404 that proves wiring:
+curl -X POST http://localhost:3333/telescope/client-errors
+# → generic route-not-found; can't tell whether telescope owns this prefix
+```
+
+```ts
+// Correct — enable it, then verify the 204:
+clientErrors: { enabled: true }
+// curl -X POST ... → 204 No Content once registered
+```
+
+Mechanism: unlike an always-mounted controller, the provider registers the POST
+route only when `clientErrors.enabled` is true — while off the endpoint genuinely
+does not exist.
+Source: `docs/packages/client-errors.mdx` (Disabled by default warn callout).
+
+See also: `telescope-watchers/SKILL.md` — capture gaps become alert gaps;
+`telescope-access-mcp/SKILL.md` — the diagnose endpoint rides behind the dashboard guard.