@adonis-agora/telescope 0.6.0 → 0.7.1

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

@@ -0,0 +1,229 @@
+/**
+ * The Live Queue Manager driver for the OPTIONAL `@adonisjs/queue` peer (whose engine is
+ * `@boringnode/queue`).
+ *
+ * ## Why this does NOT mirror `nestjs-telescope`'s `BullMqQueueManager` operation-for-operation
+ * `nestjs-telescope`'s `BullMqQueueManager` (`packages/bullmq/src/bull-mq-queue-manager.ts`) is
+ * built on BullMQ, whose `Queue` exposes: enumerate/discover queues (via Nest's `DiscoveryService`),
+ * `getJobCounts()` per state, `getJobs(state, start, end)` (paginated, BY STATE), `getJob(id)`,
+ * `job.retry()`, `job.remove()`, `job.promote()`, and `queue.add()`. `@boringnode/queue` is a
+ * DIFFERENT engine with a materially smaller public surface (checked against the published
+ * `Adapter` interface across every release from 0.5.0 through the current 0.7.1 — the `Adapter`
+ * type has not changed in that window):
+ *
+ *  - **SUPPORTED**: `Adapter.getJob(jobId, queue)` (single job by id), `Adapter.retryJob(jobId,
+ *    queue, retryAt?)`, `Adapter.sizeOf(queue)` (a PENDING-only count), and enqueue via
+ *    `Adapter.push`/`Adapter.pushOn` (the lower-level calls `Job.dispatch(payload).toQueue(name)`
+ *    resolves to).
+ *  - **NOT SUPPORTED — no such method exists on the `Adapter` interface, in any published version**:
+ *    listing/paginating jobs BY STATE (there is no `getJobs`/`listJobs`/`findByStatus`), removing a
+ *    job, promoting a delayed job, or per-state counts (`sizeOf` is pending-only; there is no
+ *    `getJobCounts` equivalent). There is also no `listQueues()` — queues are just string names
+ *    passed at dispatch time, with no registry to enumerate.
+ *
+ * Rather than fake the missing operations (a fabricated `listJobs` that silently returns `[]`, or a
+ * `remove()` that no-ops and lies about succeeding), this driver ships EXACTLY what the engine
+ * supports and advertises the rest as absent via {@link capabilities} — the same
+ * "optional-method-presence advertises capability" idea `nestjs-telescope`'s `QueueManager` SPI
+ * uses, computed here from what the resolved adapter itself exposes rather than guessed. A
+ * dashboard built against this driver gets: configured queue names + a pending count, single-job
+ * lookup by id, retry-by-id, and enqueue — a genuinely smaller but honest console.
+ *
+ * ## Why `queues` must be configured explicitly
+ * `@boringnode/queue` has no `listQueues()` / registry to enumerate — queue names only exist as
+ * strings passed at `.toQueue(name)` / dispatch time. So, like `nestjs-telescope`'s
+ * `BullMqQueueManager` constructor's OPTIONAL `queueNames` allow-list (there, discovery is the
+ * default and the list narrows it), here the list is NOT optional: there is nothing to discover, so
+ * the host declares the queue names it wants surfaced (`config/telescope_watchers.ts`'s
+ * `queueManager.queues`).
+ *
+ * ## Why the adapter is duck-typed rather than importing `@boringnode/queue`'s types
+ * `@boringnode/queue` is not installed in THIS repo (same stance as `queue_watcher.ts`'s
+ * `AcquiredJobLike`) — it is a peer the host app brings. {@link QueueAdapterLike} /
+ * {@link QueueLike} model only the fields/methods this driver reads, read defensively.
+ * {@link QueueLike.use} — resolving a specific named adapter off the top-level `queue` service via
+ * `.use(name?)` — follows the standard AdonisJS "Manager" convention used throughout the framework
+ * (`db.connection()`, `mail.use()`, `redis.connection()`, …); it was NOT directly confirmed against
+ * `@boringnode/queue`'s public `.d.ts` (the research pass that grounded `retryJob`/`getJob`/`sizeOf`/
+ * `push`/`pushOn` did not enumerate `QueueManager`'s own top-level methods), so this is a
+ * well-precedented but unverified structural assumption — if a real app's `queue` service doesn't
+ * expose `.use()`, {@link QueueManagerDriver} falls back to treating the service AS the adapter
+ * directly (see `resolveAdapter`), and degrades to `configured === false` if neither shape matches.
+ */
+/** The job-execution states `@boringnode/queue`'s own `JobStatus` type distinguishes. Named exactly
+ *  as the engine names them (NOT remapped to BullMQ's `waiting`/`paused` vocabulary) since this
+ *  driver is not pretending to be a BullMQ-compatible surface. */
+export type QueueState = 'pending' | 'active' | 'delayed' | 'failed' | 'completed';
+export declare const QUEUE_STATES: readonly QueueState[];
+export declare function isQueueState(value: unknown): value is QueueState;
+/** The mutating actions a driver MAY support; presence in {@link QueueManagerDriver.capabilities}
+ *  (not mere method presence — see the module doc) is what the UI uses to show/hide the button. */
+export type QueueActionName = 'retry' | 'remove' | 'promote' | 'enqueue';
+export declare const QUEUE_ACTIONS: readonly QueueActionName[];
+export declare function isQueueAction(value: unknown): value is QueueActionName;
+/**
+ * Per-state job counts. Every field is `number | null` (`null` = "this driver cannot report this
+ * state's count") rather than a fabricated `0`, because `@boringnode/queue` genuinely cannot report
+ * anything beyond a pending count today (see the module doc) — `0` would silently claim "empty" for
+ * states the driver simply never asked about.
+ */
+export interface QueueCounts {
+    pending: number | null;
+    active: number | null;
+    delayed: number | null;
+    failed: number | null;
+    completed: number | null;
+}
+export interface QueueSummary {
+    driver: string;
+    queue: string;
+    counts: QueueCounts;
+    /** The mutating actions available for THIS queue (currently identical across queues for this
+     *  driver — it varies per-queue only for drivers like SQS where only some queues have a DLQ). */
+    actions: QueueActionName[];
+}
+/**
+ * The structural slice of `@boringnode/queue`'s `JobRecord` this driver reads. NOT verified against
+ * installed types (the peer isn't installed here — see the module doc); every field is optional so a
+ * shape drift in the engine degrades to `null`/defaults rather than throwing.
+ */
+export interface QueueJobRecordLike {
+    id?: string | number;
+    name?: string;
+    queue?: string;
+    payload?: unknown;
+    status?: string;
+    attempts?: number;
+    maxAttempts?: number;
+    createdAt?: string | number | Date;
+    processedAt?: string | number | Date | null;
+    finishedAt?: string | number | Date | null;
+    error?: string | null;
+    result?: unknown;
+}
+export interface QueueJob {
+    id: string;
+    name: string | null;
+    /** `null` when the record's `status` isn't one of {@link QUEUE_STATES} (unknown/engine-internal). */
+    state: QueueState | null;
+    attemptsMade: number | null;
+    maxAttempts: number | null;
+    createdAt: string | null;
+    processedAt: string | null;
+    finishedAt: string | null;
+    failedReason: string | null;
+}
+export interface QueueJobDetail extends QueueJob {
+    payload: unknown;
+    result: unknown;
+}
+/**
+ * Kept for interface parity with the NestJS sibling's paginated `JobPage` and for a FUTURE driver
+ * that can genuinely list jobs (e.g. one that introspects a Knex-adapter jobs table directly rather
+ * than going through `Adapter`) — {@link QueueManagerDriver} does NOT implement `listJobs` at all
+ * (see the module doc), so this type is unused by the shipped driver today.
+ */
+export interface JobPage {
+    jobs: QueueJob[];
+    nextCursor: string | null;
+    total: number | null;
+}
+/** What the UI's `GET .../queues/live` response advertises about mutation support. */
+export interface QueueCapabilities {
+    mutationsEnabled: boolean;
+    actions: QueueActionName[];
+}
+/**
+ * SPI a queue manager driver implements. `listJobs`/`remove`/`promote` are OPTIONAL (presence would
+ * advertise capability for a future driver); {@link QueueManagerDriver} implements none of them —
+ * see the module doc for why.
+ */
+export interface QueueManager {
+    readonly driver: string;
+    listQueues(): Promise<QueueSummary[]>;
+    getJob(queue: string, id: string): Promise<QueueJobDetail | null>;
+    listJobs?(queue: string, state: QueueState, page: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<JobPage>;
+    retry?(queue: string, id: string): Promise<void>;
+    remove?(queue: string, id: string): Promise<void>;
+    promote?(queue: string, id: string): Promise<void>;
+    enqueue?(queue: string, payload: unknown, opts: {
+        name?: string;
+    }): Promise<{
+        id: string | null;
+    }>;
+    /**
+     * OPTIONAL, more precise capability advertisement than method presence: a driver whose actions
+     * depend on the RESOLVED RUNTIME adapter (not just which methods the class defines — see
+     * {@link QueueManagerDriver.capabilities}) exposes this so route handlers check it FIRST, falling
+     * back to `typeof manager[method] === 'function'` (the NestJS `BullMqQueueManager` convention,
+     * still valid for a driver whose methods are unconditionally defined) when it's absent.
+     */
+    readonly capabilities?: QueueActionName[];
+}
+/** The structural slice of `@boringnode/queue`'s `Adapter` interface this driver calls — confirmed
+ *  against the published `.d.ts` (see the module doc for exactly which methods were verified). */
+export interface QueueAdapterLike {
+    getJob(jobId: string, queue: string): Promise<QueueJobRecordLike | null>;
+    retryJob?(jobId: string, queue: string, retryAt?: Date): Promise<void>;
+    sizeOf?(queue: string): Promise<number>;
+    size?(): Promise<number>;
+    /** Enqueue onto the adapter's DEFAULT queue (the shape `Adapter.push` is documented with). */
+    push?(payload: unknown, opts?: Record<string, unknown>): Promise<unknown>;
+    /** Enqueue onto a NAMED queue (the shape `Adapter.pushOn` is documented with). Preferred over
+     *  `push` here since this driver always has an explicit target queue. */
+    pushOn?(queue: string, payload: unknown, opts?: Record<string, unknown>): Promise<unknown>;
+}
+/** The structural slice of `@adonisjs/queue`'s exported `queue` service (itself a re-export of
+ *  `@boringnode/queue`'s `QueueManager`) this driver resolves an adapter from. See the module doc's
+ *  "unverified structural assumption" note on `.use()`. */
+export interface QueueLike {
+    use?(adapterName?: string): QueueAdapterLike;
+}
+export interface QueueManagerDriverOptions {
+    /** Explicit queue names to surface — REQUIRED (see the module doc: there is no discovery API). */
+    queues: string[];
+    /** Which configured `@boringnode/queue` adapter to resolve via `queue.use(name)`. Omit to use the
+     *  manager's own default adapter (`use()` with no argument). */
+    adapter?: string;
+}
+/**
+ * The Live Queue Manager driver for `@adonisjs/queue` / `@boringnode/queue`. Constructed by
+ * `TelescopeWatchersProvider` from `config/telescope_watchers.ts`'s `queueManager` block, exactly
+ * like the queue watcher's own opt-in stance: absent config / absent peer / an unresolvable adapter
+ * all degrade to `configured === false` (an empty, clearly-labelled UI state), never a throw.
+ */
+export declare class QueueManagerDriver implements QueueManager {
+    readonly driver = "boringnode";
+    private readonly adapter;
+    private readonly queues;
+    constructor(queueService: QueueLike | null, options: QueueManagerDriverOptions);
+    /** Whether an adapter was actually resolved. `false` ⇒ every method below degrades safely
+     *  (`listQueues` returns queues with all-null counts and no actions; `getJob` resolves `null`). */
+    get configured(): boolean;
+    /** The mutating actions this driver can genuinely perform — derived from what the RESOLVED
+     *  adapter exposes, not guessed. `remove`/`promote` are never included: `@boringnode/queue`'s
+     *  `Adapter` interface exposes neither (see the module doc). */
+    get capabilities(): QueueActionName[];
+    listQueues(): Promise<QueueSummary[]>;
+    private countsFor;
+    getJob(queue: string, id: string): Promise<QueueJobDetail | null>;
+    /** Throws when the resolved adapter has no `retryJob` — the route layer only calls this when
+     *  {@link capabilities} already advertised `'retry'`, so this is a defensive backstop, not the
+     *  primary gate. */
+    retry(queue: string, id: string): Promise<void>;
+    /**
+     * Enqueue a new job. Prefers `pushOn(queue, payload, opts)` (explicit target queue) over
+     * `push(payload, opts)` (the adapter's own default queue, with `queue` passed through `opts` on a
+     * best-effort basis — some adapters read a `queue` option, some don't; see the module doc's
+     * uncertainty note). Throws when neither is available.
+     */
+    enqueue(queue: string, payload: unknown, opts?: {
+        name?: string;
+    }): Promise<{
+        id: string | null;
+    }>;
+}
+//# sourceMappingURL=queue_manager.d.ts.map

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

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

package/dist/src/watchers/queue_manager.js

@@ -0,0 +1,223 @@
+/**
+ * The Live Queue Manager driver for the OPTIONAL `@adonisjs/queue` peer (whose engine is
+ * `@boringnode/queue`).
+ *
+ * ## Why this does NOT mirror `nestjs-telescope`'s `BullMqQueueManager` operation-for-operation
+ * `nestjs-telescope`'s `BullMqQueueManager` (`packages/bullmq/src/bull-mq-queue-manager.ts`) is
+ * built on BullMQ, whose `Queue` exposes: enumerate/discover queues (via Nest's `DiscoveryService`),
+ * `getJobCounts()` per state, `getJobs(state, start, end)` (paginated, BY STATE), `getJob(id)`,
+ * `job.retry()`, `job.remove()`, `job.promote()`, and `queue.add()`. `@boringnode/queue` is a
+ * DIFFERENT engine with a materially smaller public surface (checked against the published
+ * `Adapter` interface across every release from 0.5.0 through the current 0.7.1 — the `Adapter`
+ * type has not changed in that window):
+ *
+ *  - **SUPPORTED**: `Adapter.getJob(jobId, queue)` (single job by id), `Adapter.retryJob(jobId,
+ *    queue, retryAt?)`, `Adapter.sizeOf(queue)` (a PENDING-only count), and enqueue via
+ *    `Adapter.push`/`Adapter.pushOn` (the lower-level calls `Job.dispatch(payload).toQueue(name)`
+ *    resolves to).
+ *  - **NOT SUPPORTED — no such method exists on the `Adapter` interface, in any published version**:
+ *    listing/paginating jobs BY STATE (there is no `getJobs`/`listJobs`/`findByStatus`), removing a
+ *    job, promoting a delayed job, or per-state counts (`sizeOf` is pending-only; there is no
+ *    `getJobCounts` equivalent). There is also no `listQueues()` — queues are just string names
+ *    passed at dispatch time, with no registry to enumerate.
+ *
+ * Rather than fake the missing operations (a fabricated `listJobs` that silently returns `[]`, or a
+ * `remove()` that no-ops and lies about succeeding), this driver ships EXACTLY what the engine
+ * supports and advertises the rest as absent via {@link capabilities} — the same
+ * "optional-method-presence advertises capability" idea `nestjs-telescope`'s `QueueManager` SPI
+ * uses, computed here from what the resolved adapter itself exposes rather than guessed. A
+ * dashboard built against this driver gets: configured queue names + a pending count, single-job
+ * lookup by id, retry-by-id, and enqueue — a genuinely smaller but honest console.
+ *
+ * ## Why `queues` must be configured explicitly
+ * `@boringnode/queue` has no `listQueues()` / registry to enumerate — queue names only exist as
+ * strings passed at `.toQueue(name)` / dispatch time. So, like `nestjs-telescope`'s
+ * `BullMqQueueManager` constructor's OPTIONAL `queueNames` allow-list (there, discovery is the
+ * default and the list narrows it), here the list is NOT optional: there is nothing to discover, so
+ * the host declares the queue names it wants surfaced (`config/telescope_watchers.ts`'s
+ * `queueManager.queues`).
+ *
+ * ## Why the adapter is duck-typed rather than importing `@boringnode/queue`'s types
+ * `@boringnode/queue` is not installed in THIS repo (same stance as `queue_watcher.ts`'s
+ * `AcquiredJobLike`) — it is a peer the host app brings. {@link QueueAdapterLike} /
+ * {@link QueueLike} model only the fields/methods this driver reads, read defensively.
+ * {@link QueueLike.use} — resolving a specific named adapter off the top-level `queue` service via
+ * `.use(name?)` — follows the standard AdonisJS "Manager" convention used throughout the framework
+ * (`db.connection()`, `mail.use()`, `redis.connection()`, …); it was NOT directly confirmed against
+ * `@boringnode/queue`'s public `.d.ts` (the research pass that grounded `retryJob`/`getJob`/`sizeOf`/
+ * `push`/`pushOn` did not enumerate `QueueManager`'s own top-level methods), so this is a
+ * well-precedented but unverified structural assumption — if a real app's `queue` service doesn't
+ * expose `.use()`, {@link QueueManagerDriver} falls back to treating the service AS the adapter
+ * directly (see `resolveAdapter`), and degrades to `configured === false` if neither shape matches.
+ */
+export const QUEUE_STATES = [
+    'pending',
+    'active',
+    'delayed',
+    'failed',
+    'completed',
+];
+export function isQueueState(value) {
+    return typeof value === 'string' && QUEUE_STATES.includes(value);
+}
+export const QUEUE_ACTIONS = ['retry', 'remove', 'promote', 'enqueue'];
+export function isQueueAction(value) {
+    return typeof value === 'string' && QUEUE_ACTIONS.includes(value);
+}
+/** Resolve the adapter this driver calls, or `null` when it can't be reached (peer absent / `.use`
+ *  threw / neither the Manager nor the direct-adapter shape matched) — the driver stays fully
+ *  constructible either way; `configured` reports the outcome for the UI. */
+function resolveAdapter(queueService, adapterName) {
+    if (queueService === null)
+        return null;
+    try {
+        if (typeof queueService.use === 'function') {
+            return queueService.use(adapterName);
+        }
+        // No `.use` — tolerate a `queue` service that IS itself adapter-shaped (e.g. a single-adapter
+        // setup, or a test double), rather than assuming the Manager convention unconditionally.
+        const asAdapter = queueService;
+        return typeof asAdapter.getJob === 'function' ? asAdapter : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The Live Queue Manager driver for `@adonisjs/queue` / `@boringnode/queue`. Constructed by
+ * `TelescopeWatchersProvider` from `config/telescope_watchers.ts`'s `queueManager` block, exactly
+ * like the queue watcher's own opt-in stance: absent config / absent peer / an unresolvable adapter
+ * all degrade to `configured === false` (an empty, clearly-labelled UI state), never a throw.
+ */
+export class QueueManagerDriver {
+    driver = 'boringnode';
+    adapter;
+    queues;
+    constructor(queueService, options) {
+        this.queues = options.queues;
+        this.adapter = resolveAdapter(queueService, options.adapter);
+    }
+    /** Whether an adapter was actually resolved. `false` ⇒ every method below degrades safely
+     *  (`listQueues` returns queues with all-null counts and no actions; `getJob` resolves `null`). */
+    get configured() {
+        return this.adapter !== null;
+    }
+    /** The mutating actions this driver can genuinely perform — derived from what the RESOLVED
+     *  adapter exposes, not guessed. `remove`/`promote` are never included: `@boringnode/queue`'s
+     *  `Adapter` interface exposes neither (see the module doc). */
+    get capabilities() {
+        if (this.adapter === null)
+            return [];
+        const actions = [];
+        if (typeof this.adapter.retryJob === 'function')
+            actions.push('retry');
+        if (typeof this.adapter.pushOn === 'function' || typeof this.adapter.push === 'function') {
+            actions.push('enqueue');
+        }
+        return actions;
+    }
+    async listQueues() {
+        const actions = this.capabilities;
+        return Promise.all(this.queues.map(async (queue) => ({
+            driver: this.driver,
+            queue,
+            counts: await this.countsFor(queue),
+            actions,
+        })));
+    }
+    async countsFor(queue) {
+        const counts = {
+            pending: null,
+            active: null,
+            delayed: null,
+            failed: null,
+            completed: null,
+        };
+        if (this.adapter && typeof this.adapter.sizeOf === 'function') {
+            try {
+                counts.pending = await this.adapter.sizeOf(queue);
+            }
+            catch {
+                // A count failure degrades to "unknown", never breaks the queue list.
+            }
+        }
+        return counts;
+    }
+    async getJob(queue, id) {
+        if (this.adapter === null)
+            return null;
+        const raw = await this.adapter.getJob(id, queue);
+        if (raw === null || raw === undefined)
+            return null;
+        return {
+            ...toJob(raw),
+            payload: raw.payload ?? null,
+            result: raw.result ?? null,
+        };
+    }
+    /** Throws when the resolved adapter has no `retryJob` — the route layer only calls this when
+     *  {@link capabilities} already advertised `'retry'`, so this is a defensive backstop, not the
+     *  primary gate. */
+    async retry(queue, id) {
+        if (!this.adapter?.retryJob) {
+            throw new Error('This queue adapter does not support retrying a job.');
+        }
+        await this.adapter.retryJob(id, queue);
+    }
+    /**
+     * Enqueue a new job. Prefers `pushOn(queue, payload, opts)` (explicit target queue) over
+     * `push(payload, opts)` (the adapter's own default queue, with `queue` passed through `opts` on a
+     * best-effort basis — some adapters read a `queue` option, some don't; see the module doc's
+     * uncertainty note). Throws when neither is available.
+     */
+    async enqueue(queue, payload, opts = {}) {
+        if (this.adapter === null) {
+            throw new Error('The queue adapter is not configured.');
+        }
+        const pushOpts = opts.name !== undefined ? { name: opts.name } : {};
+        if (typeof this.adapter.pushOn === 'function') {
+            const result = await this.adapter.pushOn(queue, payload, pushOpts);
+            return { id: idOf(result) };
+        }
+        if (typeof this.adapter.push === 'function') {
+            const result = await this.adapter.push(payload, { ...pushOpts, queue });
+            return { id: idOf(result) };
+        }
+        throw new Error('This queue adapter does not support enqueueing a job.');
+    }
+}
+/** Map a raw job record to its public {@link QueueJob} projection. */
+function toJob(raw) {
+    const status = typeof raw.status === 'string' ? raw.status : undefined;
+    return {
+        id: String(raw.id ?? ''),
+        name: typeof raw.name === 'string' ? raw.name : null,
+        state: isQueueState(status) ? status : null,
+        attemptsMade: typeof raw.attempts === 'number' ? raw.attempts : null,
+        maxAttempts: typeof raw.maxAttempts === 'number' ? raw.maxAttempts : null,
+        createdAt: toIso(raw.createdAt),
+        processedAt: toIso(raw.processedAt),
+        finishedAt: toIso(raw.finishedAt),
+        failedReason: typeof raw.error === 'string' ? raw.error : null,
+    };
+}
+function toIso(value) {
+    if (value === null || value === undefined)
+        return null;
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+/** Best-effort extraction of an id off whatever `push`/`pushOn`/`retryJob` resolve with — the exact
+ *  return shape of the `Adapter` push family wasn't confirmed (see the module doc), so this reads
+ *  defensively rather than assuming a specific shape. */
+function idOf(result) {
+    if (typeof result === 'string' || typeof result === 'number')
+        return String(result);
+    if (result && typeof result === 'object' && 'id' in result) {
+        const id = result.id;
+        if (typeof id === 'string' || typeof id === 'number')
+            return String(id);
+    }
+    return null;
+}
+//# sourceMappingURL=queue_manager.js.map

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

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

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

@@ -58,6 +58,43 @@ export interface ScheduledTaskOptions {
     /** The schedule kind. Default `'cron'`. */
     kind?: ScheduleKind;
 }
+/**
+ * A registration describing "this scheduled task EXISTS" — independent of any individual run. See
+ * {@link ScheduleWatcher.register} for why this is a separate call from {@link ScheduledRun}.
+ */
+export interface ScheduleRegistration {
+    /** The task name. Re-registering the same name REPLACES the prior registration (idempotent). */
+    name: string;
+    /** The cron/interval expression (e.g. `'0 * * * *'`), when the schedule has one. */
+    schedule?: string | null;
+    /** The schedule kind. Default `'cron'`. */
+    kind?: ScheduleKind;
+    /**
+     * IANA timezone the cron expression is evaluated in (e.g. `'America/Sao_Paulo'`). Only meaningful
+     * for `kind: 'cron'`; passed straight through to `cron-parser`. Defaults to the server's local TZ.
+     */
+    timezone?: string | null;
+}
+/**
+ * A registered schedule enriched with its computed next-run time — what
+ * {@link ScheduleWatcher.list} / {@link listRegisteredSchedules} return. Deliberately does NOT
+ * include last-run data (status/duration/lastRunAt): that lives in the recorded `scheduled_task`
+ * entries this same watcher writes, and joining the two is the UI API layer's job (it already holds
+ * a `TelescopeService` to query them) — the registry itself only knows what was registered.
+ */
+export interface RegisteredSchedule {
+    name: string;
+    kind: ScheduleKind;
+    schedule: string | null;
+    timezone: string | null;
+    /**
+     * ISO timestamp of the next fire, computed from `schedule` via `cron-parser` (see
+     * `cron_next_run.ts`). `null` when: the kind isn't `'cron'`, no `schedule` was given, the OPTIONAL
+     * `cron-parser` peer isn't installed, or the expression failed to parse — every case is a genuine
+     * "unknown", not an error.
+     */
+    nextRunAt: string | null;
+}
 /**
  * Records each scheduled-task run as a `scheduled_task` telescope entry — capturing
  * the task name, cron/interval expression, duration and outcome
@@ -86,6 +123,23 @@ export interface ScheduledTaskOptions {
  * is fire-and-forget and fully guarded: a telescope failure can never break (or
  * delay) a scheduled task.
  *
+ * ## The "Live Schedules" registry — the same explicit-integration philosophy, one layer up
+ * `recordScheduledRun`/`scheduleTask` answer "what already ran?"; they say nothing about "what
+ * schedules EXIST and when will they next fire?" — because, per the section above, AdonisJS gives us
+ * no registry of that to read (no `@Cron()` scanning, no `SchedulerRegistry`). {@link register} /
+ * {@link registerSchedule} closes that gap the same way: an EXPLICIT, idempotent call the host makes
+ * once per scheduled task (typically right next to where it wires the task into whatever scheduler
+ * it uses — `adonisjs-scheduler`, `@adonis-agora/durable`'s `@Scheduled`, a hand-rolled interval,
+ * …), analogous to how `nestjs-telescope`'s schedule package reads `@nestjs/schedule`'s
+ * `SchedulerRegistry` — except here nothing can be read, only told.
+ *
+ * `nextRunAt` is computed from the registered cron expression via the OPTIONAL `cron-parser` peer
+ * (see `cron_next_run.ts`); it is `null` for non-cron kinds or when the peer is absent — an honest
+ * "unknown" rather than a guess. There is deliberately no `running`/active-state field (unlike the
+ * NestJS `ScheduledTask.running`, which reads a real `CronJob.running` flag off `@nestjs/schedule`'s
+ * internals): AdonisJS has no equivalent object to read a running/stopped flag off, so faking one
+ * would be strictly worse than omitting it.
+ *
  * Idiomatic Adonis: a plain class, no DI decorators. The provider constructs it
  * from `config/telescope_watchers.ts` and calls {@link start} to publish it as the
  * default backing the bare {@link scheduleTask} / {@link recordScheduledRun}
@@ -95,13 +149,33 @@ export declare class ScheduleWatcher {
     readonly type: "scheduled_task";
     private readonly slowMs;
     private readonly clock;
+    private readonly registrations;
     constructor(options?: ScheduleWatcherOptions);
     /** Publish this configured instance as the default the standalone helpers
      *  inherit. Does NOT patch any global. Named `start`/`stop` to match the other
      *  watchers' provider lifecycle. */
     start(): void;
-    /** Unpublish this instance as the default (if it is). Never touches globals. */
+    /** Unpublish this instance as the default (if it is). Never touches globals. Registrations are
+     *  kept (a `stop`/`start` cycle — e.g. hot reload — shouldn't lose them), so a fresh `start()`
+     *  sees the same registry; call {@link unregister} explicitly to drop one. */
     stop(): void;
+    /**
+     * Register (or re-register — idempotent by `name`) a schedule so it shows up in
+     * {@link list} with a computed `nextRunAt`, joined against its `scheduled_task` run history by the
+     * UI layer. Call this once per scheduled task, e.g. right after wiring it into your scheduler:
+     *
+     * @example
+     *   import { registerSchedule, scheduleTask } from '@adonis-agora/telescope/watchers'
+     *   registerSchedule({ name: 'prune-sessions', schedule: '0 * * * *', kind: 'cron' })
+     *   scheduler.call(() => scheduleTask('prune-sessions', () => Session.pruneExpired(), {
+     *     schedule: '0 * * * *',
+     *   })).hourly()
+     */
+    register(registration: ScheduleRegistration): void;
+    /** Drop a registration (the task was removed / the app is shutting it down). No-op if unknown. */
+    unregister(name: string): void;
+    /** Every registered schedule, with `nextRunAt` computed from `now`. Order is registration order. */
+    list(): RegisteredSchedule[];
     /** Record one already-completed scheduled run. Fire-and-forget; never throws. */
     record(run: ScheduledRun): void;
     /**
@@ -119,6 +193,25 @@ export declare class ScheduleWatcher {
 /** Map a scheduled run to a telescope {@link RecordInput}. Exported so the entry
  *  shape can be unit-tested without a live watcher. */
 export declare function buildScheduleEntry(run: ScheduledRun, slowMs?: number): RecordInput<ScheduleEntryContent>;
+/** Map a registration + "now" to its {@link RegisteredSchedule}, computing `nextRunAt` for
+ *  `cron`-kind entries. Exported so it's unit-testable without a live watcher. */
+export declare function toRegisteredSchedule(reg: ScheduleRegistration, nowMs: number): RegisteredSchedule;
+/**
+ * Register (or re-register) a schedule through the provider-published default watcher, so it shows
+ * up in the dashboard's Live Schedules view. A NO-OP when the schedule watcher is not enabled, so
+ * it's safe to call unconditionally (e.g. at the top of a boot file that wires up cron jobs).
+ *
+ * @example
+ *   import { registerSchedule } from '@adonis-agora/telescope/watchers'
+ *   registerSchedule({ name: 'prune-sessions', schedule: '0 * * * *', kind: 'cron' })
+ */
+export declare function registerSchedule(registration: ScheduleRegistration): void;
+/** Drop a registration through the provider-published default watcher. A no-op when the schedule
+ *  watcher is not enabled or the name was never registered. */
+export declare function unregisterSchedule(name: string): void;
+/** Every registered schedule (with computed `nextRunAt`) through the provider-published default
+ *  watcher, or `[]` when the schedule watcher is not enabled. */
+export declare function listRegisteredSchedules(): RegisteredSchedule[];
 /**
  * Record one scheduled-task run through the provider-published default watcher.
  * A NO-OP when the schedule watcher is not enabled, so it is safe to call from a

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

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