@adonis-agora/durable 0.1.0

package/dist/src/commands/index.d.ts

@@ -0,0 +1,3 @@
+export { type TickOptions, type TickResult, type WorkerLogger, type WorkerLoopOptions, runTick, runWorkerLoop, } from './worker.js';
+export { type ListRunsOptions, type RunLister, listRuns, renderRunsTable, retryRun, } from './runs.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,OAAO,EACP,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,QAAQ,EACR,eAAe,EACf,QAAQ,GACT,MAAM,WAAW,CAAC"}

package/dist/src/commands/index.js

@@ -0,0 +1,3 @@
+export { runTick, runWorkerLoop, } from './worker.js';
+export { listRuns, renderRunsTable, retryRun, } from './runs.js';
+//# sourceMappingURL=index.js.map

package/dist/src/commands/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,OAAO,EACP,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAGL,QAAQ,EACR,eAAe,EACf,QAAQ,GACT,MAAM,WAAW,CAAC"}

package/dist/src/commands/runs.d.ts

@@ -0,0 +1,24 @@
+import type { RunQuery, RunResult, RunStatus, WorkflowEngine, WorkflowRun } from '../index.js';
+export interface ListRunsOptions {
+    /** Filter by run status (pending | running | suspended | completed | failed | cancelled | dead). */
+    status?: RunStatus | undefined;
+    /** Filter by workflow name. */
+    workflow?: string | undefined;
+    /** Max rows. Default 50. */
+    limit?: number | undefined;
+}
+/** Anything that can list runs — both a {@link WorkflowEngine} and a raw `StateStore` satisfy it. */
+export interface RunLister {
+    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+}
+/** Query recent runs, newest activity first (the source returns its own order). */
+export declare function listRuns(source: RunLister, opts: ListRunsOptions): Promise<WorkflowRun[]>;
+/** Render a runs list as a plain-text table for the terminal. */
+export declare function renderRunsTable(runs: WorkflowRun[]): string;
+/**
+ * Retry a run: re-enqueue it for a worker to (re-)execute via the engine's `requeue` (the
+ * dispatch-model retry — sets it back to `pending`, clears any stale lease, replays its checkpoints).
+ * Returns the enqueued result, or null if the run is unknown.
+ */
+export declare function retryRun(engine: WorkflowEngine, runId: string): Promise<RunResult | null>;
+//# sourceMappingURL=runs.d.ts.map

package/dist/src/commands/runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs.d.ts","sourceRoot":"","sources":["../../../src/commands/runs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/F,MAAM,WAAW,eAAe;IAC9B,oGAAoG;IACpG,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,qGAAqG;AACrG,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CACnD;AAED,mFAAmF;AACnF,wBAAsB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAM/F;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,MAAM,CAI3D;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAE/F"}

package/dist/src/commands/runs.js

@@ -0,0 +1,39 @@
+/** Query recent runs, newest activity first (the source returns its own order). */
+export async function listRuns(source, opts) {
+    return source.listRuns({
+        ...(opts.status ? { status: opts.status } : {}),
+        ...(opts.workflow ? { workflow: opts.workflow } : {}),
+        limit: opts.limit ?? 50,
+    });
+}
+/** Render a runs list as a plain-text table for the terminal. */
+export function renderRunsTable(runs) {
+    if (runs.length === 0)
+        return 'No runs.';
+    const rows = runs.map((r) => [r.id, r.workflow, r.status, relTime(r.updatedAt)]);
+    return table(['RUN', 'WORKFLOW', 'STATUS', 'UPDATED'], rows);
+}
+/**
+ * Retry a run: re-enqueue it for a worker to (re-)execute via the engine's `requeue` (the
+ * dispatch-model retry — sets it back to `pending`, clears any stale lease, replays its checkpoints).
+ * Returns the enqueued result, or null if the run is unknown.
+ */
+export async function retryRun(engine, runId) {
+    return engine.requeue(runId);
+}
+function table(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)));
+    const fmt = (cells) => cells.map((c, i) => c.padEnd(widths[i] ?? 0)).join('  ');
+    return [fmt(headers), ...rows.map(fmt)].join('\n');
+}
+function relTime(date) {
+    const s = Math.round((Date.now() - date.getTime()) / 1000);
+    if (s < 60)
+        return `${s}s ago`;
+    if (s < 3600)
+        return `${Math.round(s / 60)}m ago`;
+    if (s < 86_400)
+        return `${Math.round(s / 3600)}h ago`;
+    return `${Math.round(s / 86_400)}d ago`;
+}
+//# sourceMappingURL=runs.js.map

package/dist/src/commands/runs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs.js","sourceRoot":"","sources":["../../../src/commands/runs.ts"],"names":[],"mappings":"AAgBA,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,MAAiB,EAAE,IAAqB;IACrE,OAAO,MAAM,CAAC,QAAQ,CAAC;QACrB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE;KACxB,CAAC,CAAC;AACL,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,eAAe,CAAC,IAAmB;IACjD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACjF,OAAO,KAAK,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,MAAsB,EAAE,KAAa;IAClE,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,KAAK,CAAC,OAAiB,EAAE,IAAgB;IAChD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAClG,MAAM,GAAG,GAAG,CAAC,KAAe,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1F,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,OAAO,CAAC,IAAU;IACzB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3D,IAAI,CAAC,GAAG,EAAE;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC;IAC/B,IAAI,CAAC,GAAG,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC;IAClD,IAAI,CAAC,GAAG,MAAM;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC;IACtD,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC;AAC1C,CAAC"}

package/dist/src/commands/worker.d.ts

@@ -0,0 +1,61 @@
+import type { WorkflowEngine } from '../index.js';
+import { type ScheduledWorkflow } from '../scheduler.js';
+/** A minimal logger the worker loop writes progress to (the ace command's `this.logger` fits). */
+export interface WorkerLogger {
+    info(message: string): void;
+    error(message: string): void;
+}
+/**
+ * Run one tick of the worker poll loop against the engine: pick up enqueued runs, recover runs left
+ * incomplete by a crash, resume runs whose durable timers are due, cancel runs past their execution
+ * timeout, and finally fire any due `schedules` (the 5th phase — see {@link TickOptions.schedules}).
+ * Returns a per-phase count of the runs each phase touched — the unit the `durable:work` command logs
+ * and the tests assert on. Each phase is awaited independently so one phase throwing does not abort the
+ * rest of the tick (the error is collected and surfaced).
+ */
+export interface TickResult {
+    pending: number;
+    recovered: number;
+    timers: number;
+    /** Run ids the schedules phase started this tick (due windows fired). */
+    scheduled: number;
+    /** Phase errors caught during the tick (e.g. a transient store hiccup), keyed by phase name. */
+    errors: {
+        phase: string;
+        error: Error;
+    }[];
+}
+/** Per-tick inputs beyond the engine. */
+export interface TickOptions {
+    /** Logical "now" (epoch ms) for the tick — passed to each phase. Defaults to the real clock. */
+    now?: number;
+    /**
+     * Recurring schedules fired after timeouts are swept (the 5th phase). `engine.start` is idempotent
+     * by each schedule's time-bucket run id, so racing workers start every window exactly once. Empty
+     * or undefined skips the phase entirely.
+     */
+    schedules?: readonly ScheduledWorkflow[];
+}
+/** Execute a single poll-loop tick. See {@link TickResult}. Never throws — phase errors are collected. */
+export declare function runTick(engine: WorkflowEngine, options?: TickOptions): Promise<TickResult>;
+/** Options for {@link runWorkerLoop}. */
+export interface WorkerLoopOptions {
+    /** Poll interval in ms between ticks. */
+    intervalMs: number;
+    /** Resolves/rejects to stop the loop gracefully (wired to SIGINT/SIGTERM by the command). */
+    stopSignal: Promise<void>;
+    logger: WorkerLogger;
+    /** Drain timeout passed to `engine.drain` on shutdown. Default 10s. */
+    drainTimeoutMs?: number;
+    /** Injectable sleep, for tests. Default a real timer that resolves after `ms`. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Recurring schedules to fire each tick (the 5th phase). See {@link TickOptions.schedules}. */
+    schedules?: readonly ScheduledWorkflow[];
+}
+/**
+ * The long-running worker loop: tick, then wait `intervalMs` (or until `stopSignal` resolves),
+ * repeat. On stop it drains in-flight executions so a deploy hands off cleanly. Returns the number of
+ * ticks executed — testable by resolving `stopSignal` after N ticks with an injected `sleep`.
+ */
+export declare function runWorkerLoop(engine: WorkflowEngine, options: WorkerLoopOptions): Promise<number>;
+//# sourceMappingURL=worker.d.ts.map

package/dist/src/commands/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/commands/worker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,KAAK,iBAAiB,EAAgB,MAAM,iBAAiB,CAAC;AAEvE,kGAAkG;AAClG,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,gGAAgG;IAChG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC1C;AAID,0GAA0G;AAC1G,wBAAsB,OAAO,CAC3B,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CAkCrB;AAMD,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,EAAE,YAAY,CAAC;IACrB,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,gGAAgG;IAChG,SAAS,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC1C;AAQD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,MAAM,CAAC,CA2BjB"}

package/dist/src/commands/worker.js

@@ -0,0 +1,74 @@
+import { runSchedules } from '../scheduler.js';
+const settledCount = (results) => results.length;
+/** Execute a single poll-loop tick. See {@link TickResult}. Never throws — phase errors are collected. */
+export async function runTick(engine, options = {}) {
+    const now = options.now;
+    const schedules = options.schedules;
+    const result = { pending: 0, recovered: 0, timers: 0, scheduled: 0, errors: [] };
+    const phase = async (name, fn) => {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            result.errors.push({ phase: name, error: toError(error) });
+            return 0;
+        }
+    };
+    result.pending = await phase('runPending', async () => settledCount(await engine.runPending(now)));
+    result.recovered = await phase('recoverIncomplete', async () => settledCount(await engine.recoverIncomplete(now)));
+    result.timers = await phase('resumeDueTimers', async () => settledCount(await engine.resumeDueTimers(now)));
+    await phase('sweepTimeouts', async () => {
+        await engine.sweepTimeouts(now);
+        return 0;
+    });
+    // 5th phase — fire any due recurring schedules (mirrors the NestJS timer poller). Skipped entirely
+    // when none are registered; idempotent by the schedule's time-bucket run id, so racing workers
+    // start each window exactly once.
+    result.scheduled = await phase('runSchedules', async () => {
+        if (!schedules || schedules.length === 0)
+            return 0;
+        const ids = await runSchedules(engine, schedules, now ?? Date.now());
+        return ids.length;
+    });
+    return result;
+}
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+const realSleep = (ms) => new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    t.unref?.();
+});
+/**
+ * The long-running worker loop: tick, then wait `intervalMs` (or until `stopSignal` resolves),
+ * repeat. On stop it drains in-flight executions so a deploy hands off cleanly. Returns the number of
+ * ticks executed — testable by resolving `stopSignal` after N ticks with an injected `sleep`.
+ */
+export async function runWorkerLoop(engine, options) {
+    const sleep = options.sleep ?? realSleep;
+    let stopped = false;
+    void options.stopSignal.then(() => {
+        stopped = true;
+    });
+    let ticks = 0;
+    while (!stopped) {
+        const result = await runTick(engine, options.schedules ? { schedules: options.schedules } : {});
+        ticks += 1;
+        const touched = result.pending + result.recovered + result.timers + result.scheduled;
+        if (touched > 0) {
+            options.logger.info(`tick: ${result.pending} pending, ${result.recovered} recovered, ${result.timers} timers, ${result.scheduled} scheduled`);
+        }
+        for (const { phase, error } of result.errors) {
+            options.logger.error(`tick phase ${phase} failed: ${error.message}`);
+        }
+        if (stopped)
+            break;
+        // Race the interval against the stop signal so shutdown is prompt, not interval-latent.
+        await Promise.race([sleep(options.intervalMs), options.stopSignal.catch(() => undefined)]);
+    }
+    options.logger.info(`draining (timeout ${options.drainTimeoutMs ?? 10_000}ms)…`);
+    await engine.drain(options.drainTimeoutMs);
+    options.logger.info(`worker stopped after ${ticks} ticks`);
+    return ticks;
+}
+//# sourceMappingURL=worker.js.map

package/dist/src/commands/worker.js.map

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

package/dist/src/completion.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The payload an external `ctx.task` / child run delivers back on its completion signal: either a
+ * value or a failure. One typed envelope so `task` and `child` share the same unwrap (instead of
+ * sniffing ad-hoc `__error` keys).
+ */
+export type Completion<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/** Read a `Completion` from a signal payload: return the value, or throw a FatalError if it failed. */
+export declare function unwrapCompletion<T>(payload: unknown, label: string): T;
+//# sourceMappingURL=completion.d.ts.map

package/dist/src/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/completion.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAElF,uGAAuG;AACvG,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAMtE"}

package/dist/src/completion.js

@@ -0,0 +1,10 @@
+import { FatalError } from './errors.js';
+/** Read a `Completion` from a signal payload: return the value, or throw a FatalError if it failed. */
+export function unwrapCompletion(payload, label) {
+    const c = payload;
+    if (c && typeof c === 'object' && 'ok' in c && c.ok === false) {
+        throw new FatalError(`${label} failed: ${c.error}`);
+    }
+    return c?.value;
+}
+//# sourceMappingURL=completion.js.map

package/dist/src/completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.js","sourceRoot":"","sources":["../../src/completion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AASzC,uGAAuG;AACvG,MAAM,UAAU,gBAAgB,CAAI,OAAgB,EAAE,KAAa;IACjE,MAAM,CAAC,GAAG,OAA+B,CAAC;IAC1C,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QAC9D,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,YAAY,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,OAAQ,CAAyB,EAAE,KAAU,CAAC;AAChD,CAAC"}

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

@@ -0,0 +1,48 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Authorization guard for the dashboard. Runs before every dashboard route
+ * (API + HTML). Return `true` to allow the request, `false` to deny it (the
+ * provider replies `403`). May be async (e.g. an auth lookup).
+ *
+ * It receives the AdonisJS {@link HttpContext}, so it can read the session,
+ * a bearer token, an IP allow-list, etc.
+ */
+export type AuthorizeHook = (ctx: HttpContext) => boolean | Promise<boolean>;
+/** Shape of `config/durable_dashboard.ts`. */
+export interface DurableDashboardConfig {
+    /**
+     * Master switch. When `false`, the provider registers no routes at all — the
+     * dashboard is completely absent. Defaults to `true`.
+     */
+    enabled?: boolean;
+    /**
+     * URL prefix the dashboard + its API mount under. Defaults to `/durable`.
+     * The HTML is served at the prefix root; the JSON API lives under
+     * `<path>/api`.
+     */
+    path?: string;
+    /**
+     * Per-request authorization guard. Defaults to {@link defaultAuthorize}:
+     * allow everything OUTSIDE production, and in production require a bearer
+     * token matching the `DURABLE_DASHBOARD_TOKEN` env var (deny if it is unset).
+     */
+    authorize?: AuthorizeHook;
+}
+/** A fully-resolved config — every field present (defaults applied). */
+export interface ResolvedDurableDashboardConfig {
+    enabled: boolean;
+    path: string;
+    authorize: AuthorizeHook;
+}
+/**
+ * The default guard: open outside production; in production it requires a
+ * bearer token equal to `DURABLE_DASHBOARD_TOKEN`. If that env var is unset in
+ * production the dashboard is denied entirely (fail-closed) — you must opt in
+ * by setting a token or supplying your own {@link AuthorizeHook}.
+ */
+export declare function defaultAuthorize(ctx: HttpContext): boolean;
+/** Apply defaults to a partial config, producing a fully-resolved one. */
+export declare function resolveConfig(config?: DurableDashboardConfig): ResolvedDurableDashboardConfig;
+/** Identity helper giving `config/durable_dashboard.ts` full type-checking. */
+export declare function defineConfig(config?: DurableDashboardConfig): DurableDashboardConfig;
+//# sourceMappingURL=define_config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../../src/dashboard/define_config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAE7E,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED,wEAAwE;AACxE,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,aAAa,CAAC;CAC1B;AA4BD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAK1D;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,MAAM,GAAE,sBAA2B,GAAG,8BAA8B,CASjG;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,MAAM,GAAE,sBAA2B,GAAG,sBAAsB,CAExF"}

package/dist/src/dashboard/define_config.js

@@ -0,0 +1,57 @@
+/**
+ * Whether the process is running in production. Mirrors how AdonisJS reads the
+ * environment without taking a hard dependency on its env service.
+ */
+function isProduction() {
+    return (process.env.NODE_ENV ?? '').toLowerCase() === 'production';
+}
+/**
+ * Extract a bearer token from an `Authorization: Bearer <token>` header, a
+ * `token` query-string param, or an `x-durable-token` header — whichever is
+ * present. Returns `undefined` when none is supplied.
+ */
+function readToken(ctx) {
+    const header = ctx.request.header('authorization');
+    if (header) {
+        const match = /^Bearer\s+(.+)$/i.exec(header);
+        if (match?.[1])
+            return match[1].trim();
+    }
+    const xHeader = ctx.request.header('x-durable-token');
+    if (xHeader)
+        return xHeader.trim();
+    const qs = ctx.request.qs().token;
+    if (typeof qs === 'string' && qs.length > 0)
+        return qs;
+    return undefined;
+}
+/**
+ * The default guard: open outside production; in production it requires a
+ * bearer token equal to `DURABLE_DASHBOARD_TOKEN`. If that env var is unset in
+ * production the dashboard is denied entirely (fail-closed) — you must opt in
+ * by setting a token or supplying your own {@link AuthorizeHook}.
+ */
+export function defaultAuthorize(ctx) {
+    if (!isProduction())
+        return true;
+    const expected = process.env.DURABLE_DASHBOARD_TOKEN;
+    if (!expected)
+        return false;
+    return readToken(ctx) === expected;
+}
+/** Apply defaults to a partial config, producing a fully-resolved one. */
+export function resolveConfig(config = {}) {
+    const rawPath = config.path ?? '/durable';
+    // Normalize: ensure a single leading slash and no trailing slash (root stays '/').
+    const trimmed = `/${rawPath.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+    return {
+        enabled: config.enabled ?? true,
+        path: trimmed === '/' ? '' : trimmed,
+        authorize: config.authorize ?? defaultAuthorize,
+    };
+}
+/** Identity helper giving `config/durable_dashboard.ts` full type-checking. */
+export function defineConfig(config = {}) {
+    return config;
+}
+//# sourceMappingURL=define_config.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../../src/dashboard/define_config.ts"],"names":[],"mappings":"AAwCA;;;GAGG;AACH,SAAS,YAAY;IACnB,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,KAAK,YAAY,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,GAAgB;IACjC,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IACnD,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9C,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACzC,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACtD,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;IACnC,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC;IAClC,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACvD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAgB;IAC/C,IAAI,CAAC,YAAY,EAAE;QAAE,OAAO,IAAI,CAAC;IACjC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;IACrD,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,SAAS,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC;AACrC,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,aAAa,CAAC,SAAiC,EAAE;IAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,IAAI,UAAU,CAAC;IAC1C,mFAAmF;IACnF,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;IACtE,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;QAC/B,IAAI,EAAE,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO;QACpC,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,gBAAgB;KAChD,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,SAAiC,EAAE;IAC9D,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/dashboard/handlers.d.ts

@@ -0,0 +1,47 @@
+import type { WorkflowEngine } from '../index.js';
+/**
+ * Framework-light JSON handlers over a {@link WorkflowEngine}.
+ *
+ * Each handler takes a {@link Deps} bundle (just the engine — runs and
+ * checkpoints are read through the engine's own read API, {@link
+ * WorkflowEngine.listRuns} / {@link WorkflowEngine.listCheckpoints}, so the
+ * dashboard never reaches for the engine's private store) plus a plain {@link
+ * ApiRequest} (a thin view of the parts of an HTTP request it needs), and
+ * returns a plain {@link ApiResponse} (status + JSON body). No AdonisJS types
+ * leak in, so the handlers are unit-testable against a real in-memory engine
+ * with no HTTP server. The provider adapts an AdonisJS `HttpContext` to these
+ * shapes.
+ */
+/** The engine the handlers operate over. */
+export interface Deps {
+    engine: WorkflowEngine;
+}
+/** The subset of an HTTP request the handlers read. */
+export interface ApiRequest {
+    /** Route params, e.g. `{ id: 'run-1' }`. */
+    params: Record<string, string | undefined>;
+    /** Parsed query string, e.g. `{ status: 'failed', limit: '20' }`. */
+    query: Record<string, string | string[] | undefined>;
+    /** Parsed JSON body (for POST actions). */
+    body?: unknown;
+}
+/** A plain JSON response: an HTTP status and a serializable body. */
+export interface ApiResponse {
+    status: number;
+    body: unknown;
+}
+/** `GET /runs` — list runs filtered by status/workflow/tag, paginated. */
+export declare function listRuns(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `GET /runs/:id` — a run's detail: the run, its step timeline, and child run ids. */
+export declare function getRun(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/**
+ * `POST /runs/:id/retry` — re-enqueue a failed/incomplete run for a worker to
+ * resume (completed steps replay from their checkpoints). Returns the enqueued
+ * state immediately; never blocks on execution.
+ */
+export declare function retryRun(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `POST /runs/:id/cancel` — cancel a run. Pass `{ compensate: true }` to undo the saga first. */
+export declare function cancelRun(deps: Deps, req: ApiRequest): Promise<ApiResponse>;
+/** `GET /health` — per-group worker health (queue backlog + live worker heartbeats). */
+export declare function health(deps: Deps): Promise<ApiResponse>;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/src/dashboard/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/dashboard/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKV,cAAc,EAEf,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;GAYG;AAEH,4CAA4C;AAC5C,MAAM,WAAW,IAAI;IACnB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC3C,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACrD,2CAA2C;IAC3C,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAuCD,0EAA0E;AAC1E,wBAAsB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAqBhF;AAED,uFAAuF;AACvF,wBAAsB,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAe9E;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAMhF;AAED,kGAAkG;AAClG,wBAAsB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAUjF;AAED,wFAAwF;AACxF,wBAAsB,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAW7D"}

package/dist/src/dashboard/handlers.js

@@ -0,0 +1,163 @@
+const ok = (body) => ({ status: 200, body });
+const notFound = (message) => ({
+    status: 404,
+    body: { error: message },
+});
+const RUN_STATUSES = [
+    'pending',
+    'running',
+    'suspended',
+    'completed',
+    'failed',
+    'cancelled',
+    'dead',
+];
+function firstQuery(value) {
+    if (Array.isArray(value))
+        return value[0];
+    return value;
+}
+/** Parse a positive integer query param, falling back to `fallback` when absent/invalid. */
+function intQuery(value, fallback) {
+    const raw = firstQuery(value);
+    if (raw === undefined)
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+/** Validate that a string is a known {@link RunStatus}, else `undefined`. */
+function parseStatus(value) {
+    if (value && RUN_STATUSES.includes(value)) {
+        return value;
+    }
+    return undefined;
+}
+/** `GET /runs` — list runs filtered by status/workflow/tag, paginated. */
+export async function listRuns(deps, req) {
+    const { engine } = deps;
+    const limit = Math.min(intQuery(req.query.limit, 50), 200);
+    const offset = intQuery(req.query.offset, 0);
+    const status = parseStatus(firstQuery(req.query.status));
+    const workflow = firstQuery(req.query.workflow);
+    const tag = firstQuery(req.query.tag);
+    // Build the query with only the predicates that are set — exactOptionalPropertyTypes
+    // forbids passing an explicit `undefined`.
+    const query = { limit, offset };
+    if (status)
+        query.status = status;
+    if (workflow)
+        query.workflow = workflow;
+    if (tag)
+        query.tag = tag;
+    const runs = await engine.listRuns(query);
+    return ok({
+        runs: runs.map(summarizeRun),
+        page: { limit, offset, count: runs.length },
+        statuses: RUN_STATUSES,
+    });
+}
+/** `GET /runs/:id` — a run's detail: the run, its step timeline, and child run ids. */
+export async function getRun(deps, req) {
+    const { engine } = deps;
+    const id = req.params.id;
+    if (!id)
+        return notFound('run id is required');
+    const run = await engine.getRun(id);
+    if (!run)
+        return notFound(`run ${id} not found`);
+    const [timeline, children] = await Promise.all([
+        engine.listCheckpoints(id),
+        engine.getRunChildren(id),
+    ]);
+    return ok({
+        run: detailRun(run),
+        timeline: timeline.map(summarizeCheckpoint),
+        children,
+    });
+}
+/**
+ * `POST /runs/:id/retry` — re-enqueue a failed/incomplete run for a worker to
+ * resume (completed steps replay from their checkpoints). Returns the enqueued
+ * state immediately; never blocks on execution.
+ */
+export async function retryRun(deps, req) {
+    const id = req.params.id;
+    if (!id)
+        return notFound('run id is required');
+    const result = await deps.engine.requeue(id);
+    if (!result)
+        return notFound(`run ${id} not found`);
+    return ok({ result });
+}
+/** `POST /runs/:id/cancel` — cancel a run. Pass `{ compensate: true }` to undo the saga first. */
+export async function cancelRun(deps, req) {
+    const id = req.params.id;
+    if (!id)
+        return notFound('run id is required');
+    const compensate = typeof req.body === 'object' &&
+        req.body !== null &&
+        req.body.compensate === true;
+    const result = await deps.engine.cancel(id, compensate ? { compensate: true } : undefined);
+    if (!result)
+        return notFound(`run ${id} not found`);
+    return ok({ result });
+}
+/** `GET /health` — per-group worker health (queue backlog + live worker heartbeats). */
+export async function health(deps) {
+    const groups = await deps.engine.workerHealth();
+    return ok({
+        groups: groups.map((g) => ({
+            group: g.group,
+            depth: g.depth,
+            liveWorkers: g.liveWorkers.length,
+            // The actionable alert state: work piling up with no consumer.
+            stalled: g.depth > 0 && g.liveWorkers.length === 0,
+        })),
+    });
+}
+/** Compact run shape for the list view. */
+function summarizeRun(run) {
+    return {
+        id: run.id,
+        workflow: run.workflow,
+        workflowVersion: run.workflowVersion,
+        status: run.status,
+        tags: run.tags ?? [],
+        createdAt: run.createdAt.toISOString(),
+        updatedAt: run.updatedAt.toISOString(),
+    };
+}
+/** Fuller run shape for the detail view. */
+function detailRun(run) {
+    return {
+        ...summarizeRun(run),
+        input: run.input,
+        output: run.output,
+        error: run.error,
+        searchAttributes: run.searchAttributes,
+        wakeAt: run.wakeAt,
+        recoveryAttempts: run.recoveryAttempts,
+    };
+}
+/** Compact checkpoint shape for the timeline. */
+function summarizeCheckpoint(cp) {
+    const durationMs = cp.finishedAt.getTime() - cp.startedAt.getTime();
+    const queueMs = cp.startedAt.getTime() - cp.enqueuedAt.getTime();
+    return {
+        seq: cp.seq,
+        name: cp.name,
+        kind: cp.kind,
+        status: cp.status,
+        attempts: cp.attempts,
+        workerGroup: cp.workerGroup,
+        output: cp.output,
+        error: cp.error,
+        events: cp.events ?? [],
+        enqueuedAt: cp.enqueuedAt.toISOString(),
+        startedAt: cp.startedAt.toISOString(),
+        finishedAt: cp.finishedAt.toISOString(),
+        durationMs: durationMs >= 0 ? durationMs : 0,
+        queueMs: queueMs >= 0 ? queueMs : 0,
+    };
+}
+//# sourceMappingURL=handlers.js.map

package/dist/src/dashboard/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../src/dashboard/handlers.ts"],"names":[],"mappings":"AA4CA,MAAM,EAAE,GAAG,CAAC,IAAa,EAAe,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;AACnE,MAAM,QAAQ,GAAG,CAAC,OAAe,EAAe,EAAE,CAAC,CAAC;IAClD,MAAM,EAAE,GAAG;IACX,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE;CACzB,CAAC,CAAC;AAEH,MAAM,YAAY,GAAyB;IACzC,SAAS;IACT,SAAS;IACT,WAAW;IACX,WAAW;IACX,QAAQ;IACR,WAAW;IACX,MAAM;CACP,CAAC;AAEF,SAAS,UAAU,CAAC,KAAoC;IACtD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1C,OAAO,KAAK,CAAC;AACf,CAAC;AAED,4FAA4F;AAC5F,SAAS,QAAQ,CAAC,KAAoC,EAAE,QAAgB;IACtE,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACvC,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AACrD,CAAC;AAED,6EAA6E;AAC7E,SAAS,WAAW,CAAC,KAAyB;IAC5C,IAAI,KAAK,IAAK,YAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACjE,OAAO,KAAkB,CAAC;IAC5B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,0EAA0E;AAC1E,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAU,EAAE,GAAe;IACxD,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAEtC,qFAAqF;IACrF,2CAA2C;IAC3C,MAAM,KAAK,GAAa,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAC1C,IAAI,MAAM;QAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;IAClC,IAAI,QAAQ;QAAE,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC;IACxC,IAAI,GAAG;QAAE,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC;IAEzB,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC1C,OAAO,EAAE,CAAC;QACR,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC;QAC5B,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE;QAC3C,QAAQ,EAAE,YAAY;KACvB,CAAC,CAAC;AACL,CAAC;AAED,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAU,EAAE,GAAe;IACtD,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE;QAAE,OAAO,QAAQ,CAAC,oBAAoB,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACjD,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC7C,MAAM,CAAC,eAAe,CAAC,EAAE,CAAC;QAC1B,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;KAC1B,CAAC,CAAC;IACH,OAAO,EAAE,CAAC;QACR,GAAG,EAAE,SAAS,CAAC,GAAG,CAAC;QACnB,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,mBAAmB,CAAC;QAC3C,QAAQ;KACT,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAU,EAAE,GAAe;IACxD,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE;QAAE,OAAO,QAAQ,CAAC,oBAAoB,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM;QAAE,OAAO,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACpD,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;AACxB,CAAC;AAED,kGAAkG;AAClG,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAU,EAAE,GAAe;IACzD,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE;QAAE,OAAO,QAAQ,CAAC,oBAAoB,CAAC,CAAC;IAC/C,MAAM,UAAU,GACd,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;QAC5B,GAAG,CAAC,IAAI,KAAK,IAAI;QAChB,GAAG,CAAC,IAAgC,CAAC,UAAU,KAAK,IAAI,CAAC;IAC5D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC3F,IAAI,CAAC,MAAM;QAAE,OAAO,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACpD,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;AACxB,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAU;IACrC,MAAM,MAAM,GAAkB,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;IAC/D,OAAO,EAAE,CAAC;QACR,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACzB,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC,MAAM;YACjC,+DAA+D;YAC/D,OAAO,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC;SACnD,CAAC,CAAC;KACJ,CAAC,CAAC;AACL,CAAC;AAED,2CAA2C;AAC3C,SAAS,YAAY,CAAC,GAAgB;IACpC,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,eAAe,EAAE,GAAG,CAAC,eAAe;QACpC,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE;QACpB,SAAS,EAAE,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE;QACtC,SAAS,EAAE,GAAG,CAAC,SAAS,CAAC,WAAW,EAAE;KACvC,CAAC;AACJ,CAAC;AAED,4CAA4C;AAC5C,SAAS,SAAS,CAAC,GAAgB;IACjC,OAAO;QACL,GAAG,YAAY,CAAC,GAAG,CAAC;QACpB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;QACtC,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;KACvC,CAAC;AACJ,CAAC;AAED,iDAAiD;AACjD,SAAS,mBAAmB,CAAC,EAAkB;IAC7C,MAAM,UAAU,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IACpE,MAAM,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;IACjE,OAAO;QACL,GAAG,EAAE,EAAE,CAAC,GAAG;QACX,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,MAAM,EAAE,EAAE,CAAC,MAAM;QACjB,QAAQ,EAAE,EAAE,CAAC,QAAQ;QACrB,WAAW,EAAE,EAAE,CAAC,WAAW;QAC3B,MAAM,EAAE,EAAE,CAAC,MAAM;QACjB,KAAK,EAAE,EAAE,CAAC,KAAK;QACf,MAAM,EAAE,EAAE,CAAC,MAAM,IAAI,EAAE;QACvB,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,WAAW,EAAE;QACvC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE;QACrC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,WAAW,EAAE;QACvC,UAAU,EAAE,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC5C,OAAO,EAAE,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;KACpC,CAAC;AACJ,CAAC"}

package/dist/src/dashboard/html.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Render the dashboard HTML with the JSON API base path injected, so the
+ * single-page client knows where to fetch from regardless of the configured
+ * mount prefix.
+ */
+export declare function renderDashboard(apiBase: string): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/src/dashboard/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../../src/dashboard/html.ts"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD"}