@adonis-agora/telescope 0.4.0 → 0.5.1

package/dist/src/ui/login_page.js

@@ -0,0 +1,170 @@
+/**
+ * The built-in `dashboardAuth` login page (`GET <basePath>/login`). Deliberately a small,
+ * dependency-free, hand-authored HTML page — NOT part of the bundled dashboard SPA — so gating the
+ * dashboard shell doesn't require rebuilding or extending the bundled Vite app.
+ *
+ * `returnTo` and any error state are read CLIENT-SIDE from `location.search` (never server-echoed
+ * into the HTML), so this function's only per-request-ish input is `basePath` — a developer-
+ * controlled config value, not user input — and the page body is otherwise a static template.
+ * This sidesteps HTML-escaping entirely: there is no reflected query-param interpolation surface
+ * to get wrong.
+ *
+ * The visual language (dark zinc card, mono type, emerald accent) mirrors the Agora consoles so
+ * they feel like one family. The submit flow POSTs JSON via `fetch` and follows the JSON
+ * `redirectTo` it gets back (rather than a classic form POST + server redirect), which is why the
+ * markup keeps its own `<script>`.
+ *
+ * The password input has NO `required` attribute and the value is forwarded AS-IS (empty string
+ * when blank): the host's `login` hook — not this page — decides whether a password matters, so an
+ * email-only host (gate on username, ignore password) works with the same page as a host with real
+ * passwords.
+ */
+export function renderLoginPage(basePath) {
+    const loginAction = `${basePath}/login`;
+    const defaultReturnTo = basePath === '' ? '/' : basePath;
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex, nofollow" />
+<title>Sign in — Telescope</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0;
+    min-height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: #09090b;
+    color: #e4e4e7;
+    font: 14px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    padding: 16px;
+  }
+  .card {
+    width: 100%;
+    max-width: 384px;
+    border: 1px solid #27272a;
+    background: #18181b;
+    border-radius: 8px;
+    padding: 32px;
+    box-shadow: 0 25px 50px -12px rgb(0 0 0 / 0.5);
+  }
+  .brand {
+    margin: 0 0 24px;
+    text-align: center;
+    font-size: 18px;
+    font-weight: 600;
+    color: #34d399;
+  }
+  form { display: flex; flex-direction: column; gap: 16px; }
+  label { display: flex; flex-direction: column; gap: 6px; }
+  .field-label {
+    font-size: 11px;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    color: #71717a;
+  }
+  input {
+    border-radius: 4px;
+    border: 1px solid #3f3f46;
+    background: #09090b;
+    color: #f4f4f5;
+    padding: 8px 12px;
+    font: inherit;
+    outline: none;
+  }
+  input:focus { border-color: rgb(52 211 153 / 0.6); }
+  #error {
+    display: none;
+    margin: 0;
+    font-size: 12px;
+    color: #fb7185;
+  }
+  button {
+    margin-top: 8px;
+    border-radius: 4px;
+    border: 1px solid rgb(52 211 153 / 0.4);
+    background: rgb(52 211 153 / 0.1);
+    color: #6ee7b7;
+    padding: 8px 12px;
+    font: inherit;
+    font-size: 12px;
+    font-weight: 500;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    cursor: pointer;
+  }
+  button:hover:not(:disabled) { background: rgb(52 211 153 / 0.2); }
+  button:disabled { opacity: 0.6; cursor: default; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <p class="brand">Telescope</p>
+    <form id="login-form" autocomplete="on">
+      <label>
+        <span class="field-label">Username</span>
+        <input id="username" name="username" type="text" autocomplete="username" required autofocus />
+      </label>
+      <label>
+        <span class="field-label">Password</span>
+        <input id="password" name="password" type="password" autocomplete="current-password" />
+      </label>
+      <p id="error" role="alert">Invalid username or password.</p>
+      <button id="submit" type="submit">Sign in</button>
+    </form>
+  </div>
+<script>
+(function () {
+  var LOGIN_ACTION = ${JSON.stringify(loginAction)};
+  var DEFAULT_RETURN_TO = ${JSON.stringify(defaultReturnTo)};
+  var params = new URLSearchParams(window.location.search);
+  var errorBox = document.getElementById('error');
+  if (params.get('error')) errorBox.style.display = 'block';
+
+  function sameOriginReturnTo(value) {
+    if (typeof value !== 'string' || value === '') return DEFAULT_RETURN_TO;
+    if (value.charAt(0) !== '/' || value.charAt(1) === '/' || value.indexOf('://') !== -1) {
+      return DEFAULT_RETURN_TO;
+    }
+    return value;
+  }
+
+  var form = document.getElementById('login-form');
+  var submitButton = document.getElementById('submit');
+  form.addEventListener('submit', function (event) {
+    event.preventDefault();
+    submitButton.disabled = true;
+    errorBox.style.display = 'none';
+    var returnTo = sameOriginReturnTo(params.get('returnTo'));
+    fetch(LOGIN_ACTION, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      credentials: 'same-origin',
+      body: JSON.stringify({
+        username: document.getElementById('username').value,
+        password: document.getElementById('password').value,
+        returnTo: returnTo,
+      }),
+    })
+      .then(function (response) {
+        if (!response.ok) throw new Error('unauthorized');
+        return response.json();
+      })
+      .then(function (data) {
+        window.location.href = data.redirectTo || DEFAULT_RETURN_TO;
+      })
+      .catch(function () {
+        errorBox.style.display = 'block';
+        submitButton.disabled = false;
+      });
+  });
+})();
+</script>
+</body>
+</html>`;
+}
+//# sourceMappingURL=login_page.js.map

package/dist/src/ui/login_page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"login_page.js","sourceRoot":"","sources":["../../../src/ui/login_page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,MAAM,WAAW,GAAG,GAAG,QAAQ,QAAQ,CAAC;IACxC,MAAM,eAAe,GAAG,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;IACzD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uBAiGc,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC;4BACtB,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA6CnD,CAAC;AACT,CAAC"}

package/dist/src/ui/session_cookie.d.ts

@@ -0,0 +1,42 @@
+/** The validated dashboard session attached to a request once its cookie verifies. */
+export interface DashboardSession {
+    /** Stable user id (the session user's `id`). */
+    sub: string;
+    /** Optional display name. */
+    name?: string;
+    /** Free-form role strings; the dashboard does not interpret them. */
+    roles: string[];
+    /** Issued-at, epoch milliseconds. */
+    iat: number;
+    /** Expiry, epoch milliseconds. */
+    exp: number;
+}
+/** The session user the host `login` hook returns to mint a cookie. */
+export interface DashboardSessionUser {
+    id: string;
+    name?: string;
+    roles?: string[];
+}
+export interface SignOptions {
+    secret: string;
+    ttlMs: number;
+    /** Injectable clock (epoch ms) for deterministic tests. Defaults to `Date.now()`. */
+    now?: number;
+}
+export interface VerifyOptions {
+    secret: string;
+    /** Injectable clock (epoch ms) for deterministic tests. Defaults to `Date.now()`. */
+    now?: number;
+}
+/**
+ * Sign a session into the cookie value `base64url(payload).base64url(hmac)`. Stateless
+ * HMAC-SHA256, no store, `node:crypto` only — no JWT dependency.
+ */
+export declare function signSessionCookie(user: DashboardSessionUser, options: SignOptions): string;
+/**
+ * Verify a cookie value and return the session, or `null` for anything that's tampered,
+ * malformed, or expired (past `exp` + a 30s grace). Constant-time signature comparison. NEVER
+ * throws — any parse failure yields `null`.
+ */
+export declare function verifySessionCookie(value: string, options: VerifyOptions): DashboardSession | null;
+//# sourceMappingURL=session_cookie.d.ts.map

package/dist/src/ui/session_cookie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_cookie.d.ts","sourceRoot":"","sources":["../../../src/ui/session_cookie.ts"],"names":[],"mappings":"AAcA,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,uEAAuE;AACvE,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAcD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,CAY1F;AAeD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,GACrB,gBAAgB,GAAG,IAAI,CA4BzB"}

package/dist/src/ui/session_cookie.js

@@ -0,0 +1,97 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/**
+ * Dependency-free, framework-light signed session cookie for the dashboard's
+ * built-in {@link file://./auth.ts dashboardAuth} mechanism. Stateless
+ * HMAC-SHA256 over `node:crypto` only (no JWT dependency, no store, no
+ * AdonisJS types) — ported verbatim from `@adonis-agora/durable`'s dashboard so
+ * the cookie format is identical across the Agora dashboards and this stays
+ * unit-testable without an `HttpContext`.
+ */
+/** Clock-skew grace applied to `exp` so a marginally-late clock doesn't bounce a valid cookie. */
+const EXP_GRACE_MS = 30_000;
+function base64urlEncode(value) {
+    return Buffer.from(value, 'utf8').toString('base64url');
+}
+function base64urlDecode(value) {
+    return Buffer.from(value, 'base64url').toString('utf8');
+}
+function hmac(secret, payload) {
+    return createHmac('sha256', secret).update(payload).digest('base64url');
+}
+/**
+ * Sign a session into the cookie value `base64url(payload).base64url(hmac)`. Stateless
+ * HMAC-SHA256, no store, `node:crypto` only — no JWT dependency.
+ */
+export function signSessionCookie(user, options) {
+    const issuedAt = options.now ?? Date.now();
+    const session = {
+        sub: user.id,
+        ...(user.name !== undefined ? { name: user.name } : {}),
+        roles: user.roles ?? [],
+        iat: issuedAt,
+        exp: issuedAt + options.ttlMs,
+    };
+    const encodedPayload = base64urlEncode(JSON.stringify(session));
+    const signature = hmac(options.secret, encodedPayload);
+    return `${encodedPayload}.${signature}`;
+}
+/** Type guard for the decoded payload shape — defends against tampered/legacy payloads. */
+function isSessionPayload(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = { ...value };
+    if (typeof record.sub !== 'string')
+        return false;
+    if (record.name !== undefined && typeof record.name !== 'string')
+        return false;
+    if (!Array.isArray(record.roles))
+        return false;
+    if (!record.roles.every((role) => typeof role === 'string'))
+        return false;
+    if (typeof record.iat !== 'number' || !Number.isFinite(record.iat))
+        return false;
+    if (typeof record.exp !== 'number' || !Number.isFinite(record.exp))
+        return false;
+    return true;
+}
+/**
+ * Verify a cookie value and return the session, or `null` for anything that's tampered,
+ * malformed, or expired (past `exp` + a 30s grace). Constant-time signature comparison. NEVER
+ * throws — any parse failure yields `null`.
+ */
+export function verifySessionCookie(value, options) {
+    try {
+        const dot = value.indexOf('.');
+        if (dot <= 0 || dot === value.length - 1)
+            return null;
+        const encodedPayload = value.slice(0, dot);
+        const providedSignature = value.slice(dot + 1);
+        const expectedSignature = hmac(options.secret, encodedPayload);
+        const provided = Buffer.from(providedSignature, 'base64url');
+        const expected = Buffer.from(expectedSignature, 'base64url');
+        // timingSafeEqual throws on a length mismatch — guard it so a wrong-length (tampered)
+        // signature returns null instead of throwing.
+        if (provided.length !== expected.length)
+            return null;
+        if (!timingSafeEqual(provided, expected))
+            return null;
+        const decoded = JSON.parse(base64urlDecode(encodedPayload));
+        if (!isSessionPayload(decoded))
+            return null;
+        const now = options.now ?? Date.now();
+        if (now > decoded.exp + EXP_GRACE_MS)
+            return null;
+        const session = {
+            sub: decoded.sub,
+            ...(decoded.name !== undefined ? { name: decoded.name } : {}),
+            roles: decoded.roles,
+            iat: decoded.iat,
+            exp: decoded.exp,
+        };
+        return session;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=session_cookie.js.map

package/dist/src/ui/session_cookie.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_cookie.js","sourceRoot":"","sources":["../../../src/ui/session_cookie.ts"],"names":[],"mappings":"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"}

package/dist/src/watchers/define_config.d.ts

@@ -1,18 +1,107 @@
 /**
- * NOTE — no `'schedule'` watcher is shipped, intentionally. The NestJS original
- * (`@dudousxd/nestjs-telescope`'s schedule package) wraps `@nestjs/schedule`'s
- * `@Cron`/`@Interval`/`@Timeout` decorators via its `SchedulerRegistry`. AdonisJS
- * has NO first-party scheduler, and the popular community schedulers
- * (`adonisjs-scheduler` et al.) emit nothing on the app emitter and expose no
- * lifecycle hooks — so a generic schedule watcher could only be built by inventing
- * /wrapping a private API. It is therefore deliberately omitted. In the Agora
- * ecosystem, `@adonis-agora/durable` already bridges its scheduled/cron + workflow
- * run events onto the diagnostics bus, which the generic {@link DiagnosticsWatcher}
- * records — so scheduled-run observability is covered there, not by a bespoke
- * schedule watcher.
+ * NOTE — the `'schedule'` watcher is EXPLICIT-integration, by design. The NestJS
+ * original (`@dudousxd/nestjs-telescope`'s schedule package) wraps
+ * `@nestjs/schedule`'s `@Cron`/`@Interval`/`@Timeout` decorators via its
+ * `SchedulerRegistry`. AdonisJS has NO first-party scheduler, and the community
+ * schedulers (`adonisjs-scheduler` et al.) emit nothing on the app emitter and
+ * expose no lifecycle hook — so there is no stable event to tap. Rather than
+ * fabricate one, the schedule watcher's integration point is an explicit wrapper:
+ * `scheduleTask(name, fn)` (times a scheduled closure) / `recordScheduledRun(...)`
+ * (record an outcome you already have) — see `schedule_watcher.ts`. Enabling it
+ * publishes the config-backed default those helpers inherit. (In the Agora
+ * ecosystem, `@adonis-agora/durable` also bridges its scheduled/cron runs onto the
+ * diagnostics bus, which the {@link DiagnosticsWatcher} records.)
+ *
+ * The `'profiling'` watcher is likewise user-driven — there is no event to tap.
+ * Enabling it publishes the default backing the `profile(label, fn)` /
+ * `startProfile(label)` helpers (see `profiling_watcher.ts`); while disabled those
+ * helpers are a zero-cost no-op.
  */
 /** The per-technology watchers this package ships. */
-export type WatcherName = 'query' | 'mail' | 'cache' | 'http-client' | 'logs' | 'queue' | 'events' | 'redis';
+export type WatcherName = 'query' | 'mail' | 'cache' | 'http-client' | 'logs' | 'queue' | 'events' | 'redis' | 'profiling' | 'schedule';
+/**
+ * Tuning for the `http-client` (outbound) watcher. Outbound HTTP is opt-in
+ * instrumentation (Adonis has no single built-in client, so nothing is
+ * monkey-patched): these values back a bare `instrumentFetch(fetch)` once the
+ * provider has wired the watcher.
+ */
+export interface HttpClientWatcherConfig {
+    /** Outbound calls at/above this many ms get a `slow` tag. Default 1000. */
+    slowMs?: number;
+    /** Hosts (exact, case-insensitive; may include a port) whose calls are not recorded. */
+    ignoreHosts?: string[];
+    /** Record request/response body SIZES (bytes, never the bytes). Default `false`. */
+    captureBodies?: boolean;
+}
+/** The fully-resolved `http-client` watcher config (no optionals). */
+export interface ResolvedHttpClientWatcherConfig {
+    slowMs: number;
+    ignoreHosts: string[];
+    captureBodies: boolean;
+}
+/**
+ * Tuning for the Lucid `query` watcher — the one enabled by default. It records
+ * every SQL query Lucid emits on `db:query`; these knobs govern how much of each
+ * query is kept and which are recorded at all.
+ */
+export interface QueryWatcherConfig {
+    /** Queries at/above this many ms get a `slow` tag (feeds the Pulse slow-query
+     *  card). Default 500. */
+    slowMs?: number;
+    /**
+     * Record the raw bound parameter VALUES. Bindings routinely carry PII / secrets
+     * (emails, tokens, password hashes), so by default they are redacted to
+     * `[REDACTED]` placeholders (arity preserved) and only the normalized SQL
+     * template is kept. Turn on to capture the real values. Default `false`.
+     */
+    captureBindings?: boolean;
+    /** Connection names (exact, case-insensitive) whose queries are NOT recorded —
+     *  e.g. drop the telescope store's own connection from the timeline. */
+    ignoreConnections?: string[];
+    /**
+     * Normalize each SQL string (collapse whitespace, replace literals with `?`)
+     * into the `familyHash` grouping key so every execution of the same query
+     * template rolls up as one — the N+1 / slow-query grouping. Turn off to hash the
+     * raw SQL verbatim (no grouping across differing literals). Default `true`.
+     */
+    normalize?: boolean;
+}
+/** The fully-resolved `query` watcher config (no optionals). */
+export interface ResolvedQueryWatcherConfig {
+    slowMs: number;
+    captureBindings: boolean;
+    ignoreConnections: string[];
+    normalize: boolean;
+}
+/**
+ * Tuning for the `profiling` watcher — user-instrumented timing spans recorded via
+ * the opt-in `profile()` / `startProfile()` helpers. Nothing is captured until the
+ * watcher is enabled and those helpers are called around a code section.
+ */
+export interface ProfilingWatcherConfig {
+    /** Spans at/above this many ms get a `slow` tag. Default 100. */
+    slowMs?: number;
+    /** Spans below this many ms are discarded (too short to be worth an entry). Default 0. */
+    minDurationMs?: number;
+}
+/** The fully-resolved `profiling` watcher config (no optionals). */
+export interface ResolvedProfilingWatcherConfig {
+    slowMs: number;
+    minDurationMs: number;
+}
+/**
+ * Tuning for the `schedule` watcher — scheduled-task runs recorded via the opt-in
+ * `scheduleTask()` / `recordScheduledRun()` helpers (AdonisJS ships no scheduler
+ * event to tap, so integration is explicit — see `schedule_watcher.ts`).
+ */
+export interface ScheduleWatcherConfig {
+    /** Runs at/above this many ms get a `slow` tag. Default 1000. */
+    slowMs?: number;
+}
+/** The fully-resolved `schedule` watcher config (no optionals). */
+export interface ResolvedScheduleWatcherConfig {
+    slowMs: number;
+}
 /**
  * The shape of `config/telescope_watchers.ts`. Everything is optional: by default
  * only the Lucid `query` watcher is enabled (it is the one whose events are
@@ -34,13 +123,27 @@ export interface TelescopeWatchersConfig {
      *  - `'queue'` — records `@adonisjs/queue` job executions (optional peer).
      *  - `'events'` — records every event emitted through the core Emitter.
      *  - `'redis'` — records `@adonisjs/redis` commands (optional peer).
+     *  - `'profiling'` — publishes the `profile()`/`startProfile()` span helpers.
+     *  - `'schedule'` — publishes the `scheduleTask()`/`recordScheduledRun()` helpers.
      */
     watchers?: WatcherName[];
+    /** Tuning for the Lucid `query` watcher (slow threshold, bindings, ignore-connections, normalize). */
+    query?: QueryWatcherConfig;
+    /** Tuning for the `http-client` watcher (slow threshold, ignore-hosts, body sizes). */
+    httpClient?: HttpClientWatcherConfig;
+    /** Tuning for the `profiling` watcher (slow-span threshold, min duration floor). */
+    profiling?: ProfilingWatcherConfig;
+    /** Tuning for the `schedule` watcher (slow-run threshold). */
+    schedule?: ScheduleWatcherConfig;
 }
 /** The fully-resolved watchers config the provider acts on (no optionals). */
 export interface ResolvedTelescopeWatchersConfig {
     enabled: boolean;
     watchers: Set<WatcherName>;
+    query: ResolvedQueryWatcherConfig;
+    httpClient: ResolvedHttpClientWatcherConfig;
+    profiling: ResolvedProfilingWatcherConfig;
+    schedule: ResolvedScheduleWatcherConfig;
 }
 /** The default set of enabled watchers — the verified Lucid query watcher only. */
 export declare const DEFAULT_WATCHERS: WatcherName[];

package/dist/src/watchers/define_config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../../src/watchers/define_config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,sDAAsD;AACtD,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,MAAM,GACN,OAAO,GACP,aAAa,GACb,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;CAC1B;AAED,8EAA8E;AAC9E,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;CAC5B;AAED,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,EAAE,WAAW,EAAc,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,uBAAuB,GAAG,uBAAuB,CAErF;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAC3B,MAAM,GAAE,uBAA4B,GACnC,+BAA+B,CAKjC"}
+{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../../src/watchers/define_config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,sDAAsD;AACtD,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,MAAM,GACN,OAAO,GACP,aAAa,GACb,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,GACP,WAAW,GACX,UAAU,CAAC;AAEf;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,oFAAoF;IACpF,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,sEAAsE;AACtE,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;CACxB;AAKD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;8BAC0B;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;4EACwE;IACxE,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,gEAAgE;AAChE,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,OAAO,CAAC;IACzB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;CACpB;AAMD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,oEAAoE;AACpE,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB;AAKD;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mEAAmE;AACnE,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB;AAKD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IAEzB,sGAAsG;IACtG,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAE3B,uFAAuF;IACvF,UAAU,CAAC,EAAE,uBAAuB,CAAC;IAErC,oFAAoF;IACpF,SAAS,CAAC,EAAE,sBAAsB,CAAC;IAEnC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC;AAED,8EAA8E;AAC9E,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;IAC3B,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,+BAA+B,CAAC;IAC5C,SAAS,EAAE,8BAA8B,CAAC;IAC1C,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAED,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,EAAE,WAAW,EAAc,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,uBAAuB,GAAG,uBAAuB,CAErF;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAC3B,MAAM,GAAE,uBAA4B,GACnC,+BAA+B,CA2BjC"}

package/dist/src/watchers/define_config.js

@@ -1,16 +1,31 @@
 /**
- * NOTE — no `'schedule'` watcher is shipped, intentionally. The NestJS original
- * (`@dudousxd/nestjs-telescope`'s schedule package) wraps `@nestjs/schedule`'s
- * `@Cron`/`@Interval`/`@Timeout` decorators via its `SchedulerRegistry`. AdonisJS
- * has NO first-party scheduler, and the popular community schedulers
- * (`adonisjs-scheduler` et al.) emit nothing on the app emitter and expose no
- * lifecycle hooks — so a generic schedule watcher could only be built by inventing
- * /wrapping a private API. It is therefore deliberately omitted. In the Agora
- * ecosystem, `@adonis-agora/durable` already bridges its scheduled/cron + workflow
- * run events onto the diagnostics bus, which the generic {@link DiagnosticsWatcher}
- * records — so scheduled-run observability is covered there, not by a bespoke
- * schedule watcher.
+ * NOTE — the `'schedule'` watcher is EXPLICIT-integration, by design. The NestJS
+ * original (`@dudousxd/nestjs-telescope`'s schedule package) wraps
+ * `@nestjs/schedule`'s `@Cron`/`@Interval`/`@Timeout` decorators via its
+ * `SchedulerRegistry`. AdonisJS has NO first-party scheduler, and the community
+ * schedulers (`adonisjs-scheduler` et al.) emit nothing on the app emitter and
+ * expose no lifecycle hook — so there is no stable event to tap. Rather than
+ * fabricate one, the schedule watcher's integration point is an explicit wrapper:
+ * `scheduleTask(name, fn)` (times a scheduled closure) / `recordScheduledRun(...)`
+ * (record an outcome you already have) — see `schedule_watcher.ts`. Enabling it
+ * publishes the config-backed default those helpers inherit. (In the Agora
+ * ecosystem, `@adonis-agora/durable` also bridges its scheduled/cron runs onto the
+ * diagnostics bus, which the {@link DiagnosticsWatcher} records.)
+ *
+ * The `'profiling'` watcher is likewise user-driven — there is no event to tap.
+ * Enabling it publishes the default backing the `profile(label, fn)` /
+ * `startProfile(label)` helpers (see `profiling_watcher.ts`); while disabled those
+ * helpers are a zero-cost no-op.
  */
+/** Default outbound slow-call threshold (ms). */
+const DEFAULT_HTTP_CLIENT_SLOW_MS = 1000;
+/** Default slow-query threshold (ms). Databases are hotter than outbound HTTP, so
+ *  this is lower than the http-client default. */
+const DEFAULT_QUERY_SLOW_MS = 500;
+/** Default slow-span threshold (ms) for profiling. */
+const DEFAULT_PROFILING_SLOW_MS = 100;
+/** Default slow-run threshold (ms) for scheduled tasks. */
+const DEFAULT_SCHEDULE_SLOW_MS = 1000;
 /** The default set of enabled watchers — the verified Lucid query watcher only. */
 export const DEFAULT_WATCHERS = ['query'];
 /**
@@ -22,9 +37,31 @@ export function defineConfig(config) {
 }
 /** Apply defaults to a (possibly partial) config. */
 export function resolveConfig(config = {}) {
+    const query = config.query ?? {};
+    const httpClient = config.httpClient ?? {};
+    const profiling = config.profiling ?? {};
+    const schedule = config.schedule ?? {};
     return {
         enabled: config.enabled ?? true,
         watchers: new Set(config.watchers ?? DEFAULT_WATCHERS),
+        query: {
+            slowMs: query.slowMs ?? DEFAULT_QUERY_SLOW_MS,
+            captureBindings: query.captureBindings ?? false,
+            ignoreConnections: query.ignoreConnections ?? [],
+            normalize: query.normalize ?? true,
+        },
+        httpClient: {
+            slowMs: httpClient.slowMs ?? DEFAULT_HTTP_CLIENT_SLOW_MS,
+            ignoreHosts: httpClient.ignoreHosts ?? [],
+            captureBodies: httpClient.captureBodies ?? false,
+        },
+        profiling: {
+            slowMs: profiling.slowMs ?? DEFAULT_PROFILING_SLOW_MS,
+            minDurationMs: Math.max(0, profiling.minDurationMs ?? 0),
+        },
+        schedule: {
+            slowMs: schedule.slowMs ?? DEFAULT_SCHEDULE_SLOW_MS,
+        },
     };
 }
 //# sourceMappingURL=define_config.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../../src/watchers/define_config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA6CH,mFAAmF;AACnF,MAAM,CAAC,MAAM,gBAAgB,GAAkB,CAAC,OAAO,CAAC,CAAC;AAEzD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAA+B;IAC1D,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,aAAa,CAC3B,SAAkC,EAAE;IAEpC,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;QAC/B,QAAQ,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,gBAAgB,CAAC;KACvD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../../src/watchers/define_config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAqCH,iDAAiD;AACjD,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAsCzC;kDACkD;AAClD,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAoBlC,sDAAsD;AACtD,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAiBtC,2DAA2D;AAC3D,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAoDtC,mFAAmF;AACnF,MAAM,CAAC,MAAM,gBAAgB,GAAkB,CAAC,OAAO,CAAC,CAAC;AAEzD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAA+B;IAC1D,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,aAAa,CAC3B,SAAkC,EAAE;IAEpC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;IACjC,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC;IAC3C,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;IACvC,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;QAC/B,QAAQ,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,gBAAgB,CAAC;QACtD,KAAK,EAAE;YACL,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,qBAAqB;YAC7C,eAAe,EAAE,KAAK,CAAC,eAAe,IAAI,KAAK;YAC/C,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,IAAI,EAAE;YAChD,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;SACnC;QACD,UAAU,EAAE;YACV,MAAM,EAAE,UAAU,CAAC,MAAM,IAAI,2BAA2B;YACxD,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,EAAE;YACzC,aAAa,EAAE,UAAU,CAAC,aAAa,IAAI,KAAK;SACjD;QACD,SAAS,EAAE;YACT,MAAM,EAAE,SAAS,CAAC,MAAM,IAAI,yBAAyB;YACrD,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,aAAa,IAAI,CAAC,CAAC;SACzD;QACD,QAAQ,EAAE;YACR,MAAM,EAAE,QAAQ,CAAC,MAAM,IAAI,wBAAwB;SACpD;KACF,CAAC;AACJ,CAAC"}