@adonis-agora/telescope 0.1.0

package/dist/src/watchers/record.js

@@ -0,0 +1,48 @@
+import { currentTraceId } from '../context_accessor.js';
+import { getTelescopeRuntime } from '../registry.js';
+/**
+ * Resolve the active telescope store WITHOUT dependency injection. `@adonis-agora/telescope`'s
+ * provider publishes the live store on a cross-copy-stable global slot at boot
+ * (see its `registry.ts`); the request middleware records through that same handle.
+ * Reusing it here lets these watchers record from inside synchronous emitter
+ * subscribers — where there is no container to `inject()` from — and degrade to a
+ * no-op when telescope is disabled or not booted.
+ */
+export function resolveStore() {
+    return getTelescopeRuntime().store;
+}
+/**
+ * Record one entry through the runtime store, swallowing every failure. Watchers
+ * run inside emitter subscribers on the host's hot paths, so this is strictly
+ * fire-and-forget: a missing store, a throwing `record`, or a rejected promise can
+ * never break (or block) the emit it is observing.
+ *
+ * The active `@adonis-agora/context` trace id is backfilled when the caller did not set
+ * `traceId` explicitly, mirroring how the core watchers correlate entries.
+ */
+export function safeRecord(input, source) {
+    let store;
+    try {
+        store = resolveStore();
+    }
+    catch (err) {
+        reportError(source, err);
+        return;
+    }
+    if (!store)
+        return;
+    try {
+        const resolved = input.traceId === undefined ? { ...input, traceId: currentTraceId() } : input;
+        // Fire-and-forget: the store is async but the subscriber is sync. Swallow
+        // rejections so an observed code path is never affected by telescope.
+        void Promise.resolve(store.record(resolved)).catch((err) => reportError(source, err));
+    }
+    catch (err) {
+        reportError(source, err);
+    }
+}
+function reportError(source, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`${source}: failed to record telescope entry: ${message}`);
+}
+//# sourceMappingURL=record.js.map

package/dist/src/watchers/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../../src/watchers/record.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGrD;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,mBAAmB,EAAE,CAAC,KAAK,CAAC;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAkB,EAAE,MAAc;IAC3D,IAAI,KAA4B,CAAC;IACjC,IAAI,CAAC;QACH,KAAK,GAAG,YAAY,EAAE,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACzB,OAAO;IACT,CAAC;IACD,IAAI,CAAC,KAAK;QAAE,OAAO;IAEnB,IAAI,CAAC;QACH,MAAM,QAAQ,GACZ,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;QAChF,0EAA0E;QAC1E,sEAAsE;QACtE,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IACxF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,MAAc,EAAE,GAAY;IAC/C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,uCAAuC,OAAO,EAAE,CAAC,CAAC;AAC3E,CAAC"}

package/dist/stubs/config/telescope.stub

@@ -0,0 +1,56 @@
+{{{
+  exports({ to: app.configPath('telescope.ts') })
+}}}
+import { defineConfig, storage } from '@adonis-agora/telescope'
+
+/**
+ * Configuration for `@adonis-agora/telescope`. Everything is optional — the defaults use
+ * the in-memory store with both watchers (`request` + `diagnostics`) enabled and a
+ * 1000-entry cap.
+ */
+export default defineConfig({
+  /**
+   * Master switch. Set to `false` to disable all recording (zero overhead).
+   */
+  // enabled: true,
+
+  /**
+   * Which named store backs telescope. The active driver is selected by `store`
+   * and built from the `stores` map below.
+   */
+  store: 'memory',
+
+  /**
+   * Named store drivers, built with the `storage` factory. Each is a lazy thunk —
+   * its peer dependency is only imported when that driver is the active one.
+   *
+   * To persist entries across restarts, install `@adonisjs/lucid`, publish the
+   * migration (`node ace make:migration create_telescope_entries_table`, copying the
+   * body from this package's stub) or pass `autoCreateTable: true`, switch
+   * `store` to `'lucid'`, and uncomment the lucid driver:
+   */
+  stores: {
+    memory: storage.memory({ limit: 1000 }),
+    // lucid: storage.lucid({ connection: 'pg' }),
+  },
+
+  /**
+   * Active watchers. Omit one to disable it.
+   *  - 'request'     — records each HTTP request (method, url, status, duration).
+   *  - 'diagnostics' — records every `agora:<lib>:<event>` diagnostics publish.
+   */
+  // watchers: ['request', 'diagnostics'],
+
+  /**
+   * Sensitive-data redaction. Every entry's content is scrubbed before it is
+   * persisted — a built-in set of sensitive keys (`authorization`, `cookie`,
+   * `password`, `token`, `api_key`, `secret`, `set-cookie`, …) is masked with
+   * `[REDACTED]`, case-insensitively, at any depth. ENABLED by default.
+   *
+   * Add your own keys, or disable redaction entirely:
+   */
+  // redact: {
+  //   enabled: true,
+  //   keys: ['ssn', 'credit_card'],
+  // },
+})

package/dist/stubs/config/telescope_ai.stub

@@ -0,0 +1,36 @@
+{{{
+  exports({ to: app.configPath('telescope_ai.ts') })
+}}}
+import env from '#start/env'
+import { defineConfig } from '@adonis-agora/telescope/ai'
+
+/**
+ * Configuration for `@adonis-agora/telescope/ai`. Diagnosis is on when an Anthropic API
+ * key resolves from the environment; with no key the diagnoser is a safe no-op.
+ *
+ * Add `ANTHROPIC_API_KEY` to your `.env` and validate it in `start/env.ts`:
+ *   ANTHROPIC_API_KEY: Env.schema.string.optional()
+ */
+export default defineConfig({
+  /**
+   * Master switch. Set to `false` to disable diagnosis entirely.
+   */
+  // enabled: true,
+
+  /**
+   * The Anthropic API key — sourced from the environment, never hardcoded.
+   */
+  apiKey: env.get('ANTHROPIC_API_KEY'),
+
+  /**
+   * Claude model id. Defaults to `claude-sonnet-4-6` (best speed/intelligence
+   * balance). Use `claude-opus-4-8` for the most capable diagnosis, or
+   * `claude-haiku-4-5-20251001` for the cheapest.
+   */
+  // model: 'claude-sonnet-4-6',
+
+  /**
+   * Hard cap on generated tokens per diagnosis. Default 1024.
+   */
+  // maxTokens: 1024,
+})

package/dist/stubs/config/telescope_alerts.stub

@@ -0,0 +1,47 @@
+{{{
+  exports({ to: app.configPath('telescope_alerts.ts') })
+}}}
+import { defineConfig } from '@adonis-agora/telescope/alerts'
+
+/**
+ * Configuration for `@adonis-agora/telescope/alerts`. By default alerting is on, polls the
+ * telescope store every 30s for brand-new exception families, and logs each alert
+ * to the console. Add a Slack or generic webhook channel to ship alerts off-box.
+ */
+export default defineConfig({
+  /**
+   * Master switch. Set to `false` to disable alerting entirely.
+   */
+  // enabled: true,
+
+  /**
+   * Delivery destinations. Each fired alert is sent to every channel concurrently;
+   * one channel failing never blocks the others. Accepts declarative specs or
+   * pre-built channel objects (slackChannel/webhookChannel/customChannel).
+   */
+  // channels: [
+  //   { type: 'console' },
+  //   { type: 'slack', url: env.get('TELESCOPE_SLACK_WEBHOOK') },
+  //   { type: 'webhook', url: env.get('TELESCOPE_ALERT_WEBHOOK') },
+  // ],
+
+  /**
+   * Rules to evaluate.
+   *  - { type: 'new-exception', window } — page the first time an exception family
+   *    is seen within `window` (and again after it elapses / on resolve).
+   *  - { type: 'exception-rate', window, threshold } — page when >= threshold
+   *    exceptions are recorded in the trailing `window`.
+   */
+  // rules: [{ type: 'new-exception', window: '1h' }],
+
+  /**
+   * External dashboard URL — when set, Slack alerts include a deep link to the entry.
+   */
+  // dashboardUrl: 'https://telescope.example.com/',
+
+  /**
+   * Poll cadence and re-notify cooldown (duration strings).
+   */
+  // every: '30s',
+  // cooldown: '15m',
+})

package/dist/stubs/config/telescope_ui.stub

@@ -0,0 +1,40 @@
+{{{
+  exports({ to: app.configPath('telescope_ui.ts') })
+}}}
+import { defineConfig } from '@adonis-agora/telescope/ui'
+
+/**
+ * Configuration for `@adonis-agora/telescope/ui`. By default the dashboard mounts at
+ * `/telescope` and is reachable automatically outside production. In production it
+ * is denied unless you set a `token` / `basic` credential below, or supply your
+ * own `authorize` hook delegating to your app's auth.
+ */
+export default defineConfig({
+  /**
+   * Master switch. Set to `false` to register no routes at all.
+   */
+  // enabled: true,
+
+  /**
+   * URL prefix. The dashboard is served here; the JSON API lives at `<path>/api/*`.
+   */
+  // path: '/telescope',
+
+  /**
+   * Access-decision hook. Return `true` to allow the request, `false` to reject it
+   * (the guard answers 401 when no credential was presented, 403 when one was and
+   * was rejected). Delegate to your own app auth here, e.g.:
+   */
+  // authorize: (ctx) => ctx.auth?.user?.isAdmin === true,
+
+  /**
+   * Built-in credentials for the default policy (ignored when `authorize` is set).
+   * Gate a production dashboard without writing a hook:
+   *  - token: allow `Authorization: Bearer <token>` or `?token=<token>`
+   *  - basic: allow HTTP Basic auth
+   */
+  // credentials: {
+  //   token: env.get('TELESCOPE_UI_TOKEN'),
+  //   basic: { username: 'admin', password: env.get('TELESCOPE_UI_PASSWORD') },
+  // },
+})

package/dist/stubs/config/telescope_watchers.stub

@@ -0,0 +1,30 @@
+{{{
+  exports({ to: app.configPath('telescope_watchers.ts') })
+}}}
+import { defineConfig } from '@adonis-agora/telescope/watchers'
+
+/**
+ * Configuration for `@adonis-agora/telescope/watchers`. By default only the Lucid
+ * `query` watcher is enabled — its `db:query` event is verified against the
+ * installed `@adonisjs/lucid` types. The `mail` and `cache` watchers are opt-in.
+ */
+export default defineConfig({
+  /**
+   * Master switch. Set to `false` to start no per-technology watcher.
+   */
+  // enabled: true,
+
+  /**
+   * Active watchers. Omit one to disable it.
+   *  - 'query'       — records every Lucid SQL query (sql, bindings, duration, connection).
+   *  - 'mail'        — records every email sent (mail:sent).
+   *  - 'cache'       — records @adonisjs/cache hit/miss/write/delete events.
+   *  - 'http-client' — records every outbound fetch call (method, url, status, duration).
+   *  - 'logs'        — records AdonisJS logger output (level, message, structured fields).
+   *
+   * Note: the 'mail' and 'cache' event contracts are best-effort — those packages
+   * are not present in this repo, so their event names/payloads could not be
+   * verified against their types. See the package README.
+   */
+  // watchers: ['query'],
+})

package/dist/stubs/database/migrations/create_telescope_entries_table.stub

@@ -0,0 +1,39 @@
+{{{
+  exports({ to: app.migrationsPath(`${new Date().getTime()}_create_telescope_entries_table.ts`) })
+}}}
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+/**
+ * Creates the table the `lucid` telescope store persists entries into.
+ *
+ * `content` and `tags` are JSON text columns; `created_at` is stored as epoch
+ * milliseconds (a plain integer) so newest-first ordering and age-based pruning
+ * are driver-agnostic integer comparisons across sqlite / Postgres / MySQL.
+ */
+export default class extends BaseSchema {
+  protected tableName = 'telescope_entries'
+
+  async up() {
+    this.schema.createTable(this.tableName, (table) => {
+      table.string('id').primary().notNullable()
+      table.string('type').notNullable()
+      table.string('family_hash').nullable()
+      table.text('content').notNullable()
+      table.text('tags').notNullable()
+      table.integer('sequence').notNullable()
+      table.integer('duration_ms').nullable()
+      table.string('origin').notNullable()
+      table.string('trace_id').nullable()
+      table.bigInteger('created_at').notNullable()
+
+      table.index(['created_at'])
+      table.index(['type'])
+      table.index(['trace_id'])
+      table.index(['family_hash'])
+    })
+  }
+
+  async down() {
+    this.schema.dropTable(this.tableName)
+  }
+}

package/dist/stubs/main.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Absolute path to the published stubs directory, resolved from this compiled
+ * module's location (`dist/stubs/main.js`). Passed to `codemods.makeUsingStub`.
+ */
+export declare const stubsRoot: string;
+//# sourceMappingURL=main.d.ts.map

package/dist/stubs/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../stubs/main.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,SAAS,QAAgD,CAAC"}

package/dist/stubs/main.js

@@ -0,0 +1,7 @@
+import { fileURLToPath } from 'node:url';
+/**
+ * Absolute path to the published stubs directory, resolved from this compiled
+ * module's location (`dist/stubs/main.js`). Passed to `codemods.makeUsingStub`.
+ */
+export const stubsRoot = fileURLToPath(new URL('./', import.meta.url));
+//# sourceMappingURL=main.js.map

package/dist/stubs/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../stubs/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,140 @@
+{
+  "name": "@adonis-agora/telescope",
+  "version": "0.1.0",
+  "description": "Laravel Telescope-style headless observability for AdonisJS — records HTTP requests and every Agora diagnostics event as queryable entries, plus opt-in subpaths for per-technology watchers, a web dashboard, AI exception diagnosis, and alerting.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DavideCarvalho/adonis-telescope.git",
+    "directory": "packages/core"
+  },
+  "author": "Davi Carvalho <davi@goflip.ai>",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    },
+    "./telescope_provider": {
+      "types": "./dist/providers/telescope_provider.d.ts",
+      "import": "./dist/providers/telescope_provider.js",
+      "default": "./dist/providers/telescope_provider.js"
+    },
+    "./telescope_middleware": {
+      "types": "./dist/src/telescope_middleware.d.ts",
+      "import": "./dist/src/telescope_middleware.js",
+      "default": "./dist/src/telescope_middleware.js"
+    },
+    "./configure": {
+      "types": "./dist/configure.d.ts",
+      "import": "./dist/configure.js",
+      "default": "./dist/configure.js"
+    },
+    "./watchers": {
+      "types": "./dist/src/watchers/index.d.ts",
+      "import": "./dist/src/watchers/index.js",
+      "default": "./dist/src/watchers/index.js"
+    },
+    "./watchers_provider": {
+      "types": "./dist/providers/telescope_watchers_provider.d.ts",
+      "import": "./dist/providers/telescope_watchers_provider.js",
+      "default": "./dist/providers/telescope_watchers_provider.js"
+    },
+    "./ui": {
+      "types": "./dist/src/ui/index.d.ts",
+      "import": "./dist/src/ui/index.js",
+      "default": "./dist/src/ui/index.js"
+    },
+    "./ui_provider": {
+      "types": "./dist/providers/telescope_ui_provider.d.ts",
+      "import": "./dist/providers/telescope_ui_provider.js",
+      "default": "./dist/providers/telescope_ui_provider.js"
+    },
+    "./ai": {
+      "types": "./dist/src/ai/index.d.ts",
+      "import": "./dist/src/ai/index.js",
+      "default": "./dist/src/ai/index.js"
+    },
+    "./ai_provider": {
+      "types": "./dist/providers/telescope_ai_provider.d.ts",
+      "import": "./dist/providers/telescope_ai_provider.js",
+      "default": "./dist/providers/telescope_ai_provider.js"
+    },
+    "./alerts": {
+      "types": "./dist/src/alerts/index.d.ts",
+      "import": "./dist/src/alerts/index.js",
+      "default": "./dist/src/alerts/index.js"
+    },
+    "./alerts_provider": {
+      "types": "./dist/providers/telescope_alerts_provider.d.ts",
+      "import": "./dist/providers/telescope_alerts_provider.js",
+      "default": "./dist/providers/telescope_alerts_provider.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "//sideEffects": "registry.ts publishes the telescope runtime handle on a Symbol.for() global slot at import time — process-global state a bundler told sideEffects:false could tree-shake. The rest is pure.",
+  "sideEffects": [
+    "**/registry.js",
+    "**/registry.ts"
+  ],
+  "peerDependencies": {
+    "@adonisjs/core": "^6.12.0",
+    "@adonisjs/lucid": "^21.0.0",
+    "@adonisjs/mail": "^9.0.0",
+    "@adonisjs/cache": "^1.0.0",
+    "@anthropic-ai/sdk": "^0.32.0"
+  },
+  "peerDependenciesMeta": {
+    "@adonisjs/lucid": {
+      "optional": true
+    },
+    "@adonisjs/mail": {
+      "optional": true
+    },
+    "@adonisjs/cache": {
+      "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@adonisjs/assembler": "^7.8.0",
+    "@adonisjs/core": "^6.17.0",
+    "@adonisjs/lucid": "^21.6.1",
+    "@anthropic-ai/sdk": "^0.32.0",
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^20.0.0",
+    "better-sqlite3": "^12.0.0",
+    "luxon": "^3.4.4",
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "keywords": [
+    "adonisjs",
+    "adonis",
+    "telescope",
+    "observability",
+    "diagnostics",
+    "tracing",
+    "agora"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && pnpm run copy:stubs && pnpm run copy:assets",
+    "copy:stubs": "mkdir -p dist/stubs/config dist/stubs/database/migrations && cp stubs/config/telescope.stub dist/stubs/config/telescope.stub && cp stubs/config/telescope_watchers.stub dist/stubs/config/telescope_watchers.stub && cp stubs/config/telescope_ui.stub dist/stubs/config/telescope_ui.stub && cp stubs/config/telescope_ai.stub dist/stubs/config/telescope_ai.stub && cp stubs/config/telescope_alerts.stub dist/stubs/config/telescope_alerts.stub && cp stubs/database/migrations/create_telescope_entries_table.stub dist/stubs/database/migrations/create_telescope_entries_table.stub",
+    "copy:assets": "mkdir -p dist/src/ui && cp src/ui/dashboard.html dist/src/ui/dashboard.html",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}