@adonis-agora/durable 1.0.0-rc.2 → 1.0.0-rc.21

package/dist/src/diagnostics/transport.js

@@ -0,0 +1,188 @@
+import { WorkflowEngine } from '../engine.js';
+import { FatalError, RunAlreadyExistsError } from '../errors.js';
+/** The internal workflow every diagnostics listener delivery runs as. */
+export const DIAGNOSTICS_LISTENER_WORKFLOW = 'durable.diagnostics.listener';
+/** The origin stamped on those runs, so the console groups them under diagnostics. */
+export const DIAGNOSTICS_LISTENER_ORIGIN = '@adonis-agora/diagnostics';
+/** The prefix of every delivery run id: `diag:<event id>:<listener id>`. */
+export const DIAGNOSTICS_RUN_PREFIX = 'diag:';
+/** The error code `ctx.invoke` rejects with when this process has no listener with that id. */
+const UNKNOWN_LISTENER = 'E_UNKNOWN_DIAGNOSTICS_LISTENER';
+/**
+ * The retry policy a listener gets when `transports.durable()` sets none: three attempts, one
+ * second apart and doubling, at most 30 seconds.
+ */
+export const DIAGNOSTICS_DEFAULT_RETRY = Object.freeze({
+    retries: 3,
+    backoff: 'exp',
+    backoffMs: 1_000,
+    backoffMaxMs: 30_000,
+});
+/** The run id of one delivery. The same event and listener always give the same id. */
+export function diagnosticsRunId(eventId, listenerId) {
+    return `${DIAGNOSTICS_RUN_PREFIX}${eventId}:${listenerId}`;
+}
+/** The tags a delivery run carries, so the console can filter by lib, event or listener. */
+export function diagnosticsRunTags(delivery) {
+    return [
+        'diagnostics',
+        `lib:${delivery.envelope.lib}`,
+        `event:${delivery.envelope.event}`,
+        `listener:${delivery.listenerId}`,
+    ];
+}
+/**
+ * Whether an engine event belongs to a delivery run. Durable does not forward those runs' own
+ * lifecycle events to the diagnostics bus: a listener on `durable` events would otherwise start a
+ * delivery run for every delivery run it caused, without end.
+ */
+export function isDiagnosticsDeliveryEvent(event) {
+    if (event.workflow !== undefined)
+        return event.workflow === DIAGNOSTICS_LISTENER_WORKFLOW;
+    return typeof event.runId === 'string' && event.runId.startsWith(DIAGNOSTICS_RUN_PREFIX);
+}
+/** Validate `transports.durable(options)` and merge it over {@link DIAGNOSTICS_DEFAULT_RETRY}. */
+export function diagnosticsStepOptions(config = {}) {
+    const options = { ...DIAGNOSTICS_DEFAULT_RETRY };
+    if (config.retries !== undefined) {
+        if (!Number.isInteger(config.retries) || config.retries < 1) {
+            throw new Error(`@adonis-agora/durable: transports.durable({ retries }) must be an integer of at least 1 (got ${String(config.retries)})`);
+        }
+        options.retries = config.retries;
+    }
+    for (const key of ['backoffMs', 'backoffMaxMs']) {
+        const value = config[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+            throw new Error(`@adonis-agora/durable: transports.durable({ ${key} }) must be a number of milliseconds of at least 0 (got ${String(value)})`);
+        }
+        options[key] = value;
+    }
+    if (config.backoff !== undefined) {
+        if (config.backoff !== 'fixed' && config.backoff !== 'exp') {
+            throw new Error(`@adonis-agora/durable: transports.durable({ backoff }) must be 'fixed' or 'exp' (got ${String(config.backoff)})`);
+        }
+        options.backoff = config.backoff;
+    }
+    if (config.jitter !== undefined)
+        options.jitter = config.jitter === true;
+    return options;
+}
+/** The delivery transports alive per engine, stopped by the durable provider before it drains. */
+const liveTransports = new WeakMap();
+/**
+ * Stop every diagnostics delivery transport created on `engine`: each one stops taking deliveries
+ * and waits for the runs it is creating. The durable provider calls it on shutdown before it drains
+ * the engine, whichever of the two providers shuts down first.
+ */
+export async function stopDiagnosticsDeliveries(engine) {
+    const transports = liveTransports.get(engine);
+    if (!transports)
+        return;
+    await Promise.all([...transports].map((transport) => transport.stop()));
+}
+/**
+ * The {@link ListenerDeliveryTransport} behind `transports.durable()`: each `(listener, event)` is a
+ * run of {@link DIAGNOSTICS_LISTENER_WORKFLOW}, which calls the listener inside the `handle` step.
+ */
+export class DurableDeliveryTransport {
+    #engine;
+    #inFlight = new Set();
+    #stopped = false;
+    constructor(engine) {
+        this.#engine = engine;
+        let transports = liveTransports.get(engine);
+        if (!transports) {
+            transports = new Set();
+            liveTransports.set(engine, transports);
+        }
+        transports.add(this);
+    }
+    /**
+     * Start one run per delivery and resolve once every run is stored. A delivery whose run already
+     * exists (the same event handed over twice) counts as delivered. When some starts fail, the others
+     * still go through and the returned promise rejects with the failures.
+     */
+    deliver(deliveries) {
+        if (this.#stopped) {
+            return Promise.reject(new Error('@adonis-agora/durable: the diagnostics delivery transport is stopped'));
+        }
+        const work = this.#startAll(deliveries);
+        this.#inFlight.add(work);
+        const forget = () => this.#inFlight.delete(work);
+        work.then(forget, forget);
+        return work;
+    }
+    async #startAll(deliveries) {
+        const results = await Promise.allSettled(deliveries.map((d) => this.#start(d)));
+        const errors = results.flatMap((r) => (r.status === 'rejected' ? [r.reason] : []));
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1) {
+            throw new AggregateError(errors, `@adonis-agora/durable: ${errors.length} of ${deliveries.length} diagnostics deliveries could not be started`);
+        }
+    }
+    async #start(delivery) {
+        const input = {
+            listenerId: delivery.listenerId,
+            envelope: delivery.envelope,
+        };
+        try {
+            await this.#engine.start(DIAGNOSTICS_LISTENER_WORKFLOW, input, diagnosticsRunId(delivery.envelope.id, delivery.listenerId), { tags: diagnosticsRunTags(delivery), origin: DIAGNOSTICS_LISTENER_ORIGIN });
+        }
+        catch (error) {
+            // `start` already reports a duplicate id as the existing run; a store that still throws it
+            // means the same thing: this delivery is already a run.
+            if (error instanceof RunAlreadyExistsError)
+                return;
+            throw error;
+        }
+    }
+    /** Stop taking deliveries and wait for the runs being created. */
+    async stop() {
+        this.#stopped = true;
+        await Promise.allSettled([...this.#inFlight]);
+        liveTransports.get(this.#engine)?.delete(this);
+    }
+}
+/**
+ * Register {@link DIAGNOSTICS_LISTENER_WORKFLOW} on `engine`. Its run calls the listener through
+ * `invoke` in a `handle` step with the given retry policy. A listener this process does not know is
+ * a {@link FatalError}: retrying cannot make it appear.
+ */
+export function registerDiagnosticsListenerWorkflow(engine, invoke, stepOptions) {
+    engine.register(DIAGNOSTICS_LISTENER_WORKFLOW, '1', async (ctx, raw) => {
+        const { listenerId, envelope } = raw;
+        await ctx.localStep('handle', async () => {
+            try {
+                await invoke(listenerId, envelope);
+            }
+            catch (error) {
+                if (error?.code === UNKNOWN_LISTENER) {
+                    throw new FatalError(error instanceof Error
+                        ? error.message
+                        : `unknown diagnostics listener ${listenerId}`, UNKNOWN_LISTENER, { listenerId });
+                }
+                throw error;
+            }
+            return null;
+        }, stepOptions);
+    }, { tags: ['diagnostics'], origin: DIAGNOSTICS_LISTENER_ORIGIN });
+}
+/** Whether a durable engine is bound in `app`'s container. */
+export function isConfigured(app) {
+    const container = app.container;
+    return typeof container.hasBinding === 'function' && container.hasBinding(WorkflowEngine);
+}
+/**
+ * Create the delivery transport for this process: register the listener workflow on the app's
+ * engine, so this process can run deliveries, and return the transport that starts them.
+ */
+export async function createDeliveryTransport(context, config = {}) {
+    const stepOptions = diagnosticsStepOptions(config);
+    const engine = await context.app.container.make(WorkflowEngine);
+    registerDiagnosticsListenerWorkflow(engine, context.invoke, stepOptions);
+    return new DurableDeliveryTransport(engine);
+}
+//# sourceMappingURL=transport.js.map

package/dist/src/diagnostics/transport.js.map

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

package/dist/src/diagnostics-bridge.d.ts

@@ -27,7 +27,8 @@ export interface DurableDiagnosticsOptions {
  * `hasSubscribers`, so an unsubscribed channel costs nothing, and it never throws back into the
  * engine. Only the events THIS instance produced are forwarded by default (see
  * {@link DurableDiagnosticsOptions.includeRemote}), so a fleet records each event once; all event
- * types are forwarded — filtering is the subscriber's job. An event of a child run
+ * types are forwarded — filtering is the subscriber's job — except those of the runs that deliver
+ * diagnostics listener calls (`transports.durable()`), which would otherwise feed themselves. An event of a child run
  * the engine started (`ctx.all`, `ctx.child`, `ctx.startChild` without a caller-chosen id) also
  * carries `parentRunId`: each child is its own run, so that field is how a subscriber (a Telescope
  * search, say) finds every child of one parent, a whole `ctx.all` fan included. An event of a run a

package/dist/src/diagnostics-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics-bridge.d.ts","sourceRoot":"","sources":["../../src/diagnostics-bridge.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC/D;AAMD,oDAAoD;AACpD,MAAM,WAAW,yBAAyB;IACxC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,kBAAkB,EAC1B,OAAO,GAAE,yBAA8B,GACtC,MAAM,IAAI,CAsBZ"}
+{"version":3,"file":"diagnostics-bridge.d.ts","sourceRoot":"","sources":["../../src/diagnostics-bridge.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAInD,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC/D;AAMD,oDAAoD;AACpD,MAAM,WAAW,yBAAyB;IACxC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,kBAAkB,EAC1B,OAAO,GAAE,yBAA8B,GACtC,MAAM,IAAI,CAyBZ"}

package/dist/src/diagnostics-bridge.js

@@ -1,3 +1,4 @@
+import { isDiagnosticsDeliveryEvent } from './diagnostics/transport.js';
 import { parentRunIdOf } from './fan-join.js';
 import { lifecycleSourceOf } from './lifecycle-events.js';
 import { isRemoteEvent } from './remote-event.js';
@@ -16,7 +17,8 @@ const EMIT_SLOT = Symbol.for('@agora/diagnostics:emit');
  * `hasSubscribers`, so an unsubscribed channel costs nothing, and it never throws back into the
  * engine. Only the events THIS instance produced are forwarded by default (see
  * {@link DurableDiagnosticsOptions.includeRemote}), so a fleet records each event once; all event
- * types are forwarded — filtering is the subscriber's job. An event of a child run
+ * types are forwarded — filtering is the subscriber's job — except those of the runs that deliver
+ * diagnostics listener calls (`transports.durable()`), which would otherwise feed themselves. An event of a child run
  * the engine started (`ctx.all`, `ctx.child`, `ctx.startChild` without a caller-chosen id) also
  * carries `parentRunId`: each child is its own run, so that field is how a subscriber (a Telescope
  * search, say) finds every child of one parent, a whole `ctx.all` fan included. An event of a run a
@@ -32,6 +34,10 @@ export function attachDurableDiagnostics(engine, options = {}) {
     return engine.subscribe((event) => {
         if (!includeRemote && isRemoteEvent(event))
             return;
+        // A run delivering a diagnostics listener call (`transports.durable()`) is not echoed back onto
+        // the bus: a listener on `durable` events would start a delivery run for each one, forever.
+        if (isDiagnosticsDeliveryEvent(event))
+            return;
         const emit = globalThis[EMIT_SLOT];
         if (typeof emit !== 'function')
             return;

package/dist/src/diagnostics-bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics-bridge.js","sourceRoot":"","sources":["../../src/diagnostics-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOlD,6GAA6G;AAC7G,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAexD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAA0B,EAC1B,OAAO,GAA8B,EAAE;IAEvC,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,KAAK,IAAI,CAAC;IACrD,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,KAAkB,EAAE,EAAE;QAC7C,IAAI,CAAC,aAAa,IAAI,aAAa,CAAC,KAAK,CAAC;YAAE,OAAO;QACnD,MAAM,IAAI,GAAI,UAAsC,CAAC,SAAS,CAAuB,CAAC;QACtF,IAAI,OAAO,IAAI,KAAK,UAAU;YAAE,OAAO;QACvC,MAAM,WAAW,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ;YAC3B,CAAC,CAAC,iBAAiB,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;YAClE,CAAC,CAAC,SAAS,CAAC;QACd,IAAI,CACF,SAAS,EACT,KAAK,CAAC,IAAI,EACV,WAAW,IAAI,MAAM;YACnB,CAAC,CAAC;gBACE,GAAG,KAAK;gBACR,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtF;YACH,CAAC,CAAC,KAAK,CACV,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"diagnostics-bridge.js","sourceRoot":"","sources":["../../src/diagnostics-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOlD,6GAA6G;AAC7G,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAexD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAA0B,EAC1B,OAAO,GAA8B,EAAE;IAEvC,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,KAAK,IAAI,CAAC;IACrD,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,KAAkB,EAAE,EAAE;QAC7C,IAAI,CAAC,aAAa,IAAI,aAAa,CAAC,KAAK,CAAC;YAAE,OAAO;QACnD,gGAAgG;QAChG,4FAA4F;QAC5F,IAAI,0BAA0B,CAAC,KAAK,CAAC;YAAE,OAAO;QAC9C,MAAM,IAAI,GAAI,UAAsC,CAAC,SAAS,CAAuB,CAAC;QACtF,IAAI,OAAO,IAAI,KAAK,UAAU;YAAE,OAAO;QACvC,MAAM,WAAW,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ;YAC3B,CAAC,CAAC,iBAAiB,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;YAClE,CAAC,CAAC,SAAS,CAAC;QACd,IAAI,CACF,SAAS,EACT,KAAK,CAAC,IAAI,EACV,WAAW,IAAI,MAAM;YACnB,CAAC,CAAC;gBACE,GAAG,KAAK;gBACR,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtF;YACH,CAAC,CAAC,KAAK,CACV,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/doctor/agora_doctor.d.ts

@@ -0,0 +1,116 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+/** The container binding the registry lives at. */
+export declare const AGORA_DOCTOR_BINDING = "agora.doctor";
+/** Bound as a VALUE under `'agora.doctor'`. Data only. */
+export interface AgoraDoctorRegistry {
+    readonly version: 1;
+    readonly checks: AgoraDoctorCheck[];
+}
+export type AgoraDoctorStatus = 'ok' | 'warn' | 'error' | 'skip';
+export interface AgoraDoctorCheck {
+    /** `'<lib>.<kebab>'`, unique and frozen for 1.x: `'durable.verify-tenant'`. */
+    id: string;
+    /** `'durable'`. The package is `@adonis-agora/<lib>` unless {@link package} says otherwise. */
+    lib: string;
+    /** The npm package, when it is not `@adonis-agora/<lib>`. */
+    package?: string;
+    title: string;
+    /** `'cheap'` (default) reads config, env and files only; `'deep'` touches a DB, Redis or the network. */
+    cost?: 'cheap' | 'deep';
+    run(app: ApplicationService): AgoraDoctorResult | AgoraDoctorResult[] | Promise<AgoraDoctorResult | AgoraDoctorResult[]>;
+}
+export interface AgoraDoctorResult {
+    status: AgoraDoctorStatus;
+    /** One line, no secrets, no stack. */
+    message: string;
+    /** One line: the exact change to make. */
+    fix?: string;
+    /** Absolute URL of the lib docs page. */
+    docs?: string;
+}
+/** One reported result. */
+export interface AgoraDoctorReportEntry extends AgoraDoctorResult {
+    id: string;
+    lib: string;
+    title: string;
+    ms: number;
+}
+/** What `agora:doctor --json` prints. */
+export interface AgoraDoctorReport {
+    version: 1;
+    env: string;
+    summary: Record<AgoraDoctorStatus, number>;
+    libs: Array<{
+        lib: string;
+        package: string;
+        version: string | null;
+    }>;
+    results: AgoraDoctorReportEntry[];
+}
+export interface AgoraDoctorOptions {
+    libs?: string[];
+    only?: string;
+    deep?: boolean;
+    /** The app was not booted (`--no-boot`): deep checks are reported as skipped, never run. */
+    noBoot?: boolean;
+    strict?: boolean;
+    /** Per-check budget in ms (default 5000, deep checks 15000). */
+    timeoutMs?: number;
+    deepTimeoutMs?: number;
+}
+/** A doctor problem that stops the run itself (exit 2). */
+export declare class AgoraDoctorUsageError extends Error {
+}
+interface ContainerLike {
+    hasBinding(binding: string): boolean;
+    bindValue(binding: string, value: unknown): void;
+    make(binding: string): Promise<unknown>;
+}
+/**
+ * Add a lib's checks to the app's doctor registry, creating it when absent. Call it from a provider's
+ * `boot()` (Adonis does not await `register()`, so an async registration there can be lost). A
+ * registry of another version is left alone; a duplicate id is skipped.
+ */
+export declare function registerDoctorChecks(container: ContainerLike, checks: readonly AgoraDoctorCheck[]): Promise<void>;
+/** The registered checks; throws {@link AgoraDoctorUsageError} on a registry of another version. */
+export declare function readDoctorChecks(container: ContainerLike): Promise<AgoraDoctorCheck[]>;
+/**
+ * The checks of every installed `@adonis-agora/*` package that publishes a `./doctor` entry
+ * (`export const agoraDoctorChecks`), imported from the app root without booting providers. A
+ * package whose entry fails to load is reported as an error (`<lib>.doctor-entry`), never skipped.
+ */
+export declare function discoverDoctorChecks(app: ApplicationService): Promise<AgoraDoctorCheck[]>;
+/** The directory of `name` as Node would find it from `from` (walking up `node_modules`), real path. */
+export declare function packageDir(name: string, from: string): Promise<string | null>;
+/** The installed version of `name` resolved from `from`, or `null` when it is not installed. */
+export declare function installedVersion(name: string, from: string): Promise<string | null>;
+/**
+ * Whether `version` satisfies `range`, with node-semver's grammar and prereleases included (like
+ * `semver.satisfies(version, range, { includePrerelease: true })`). An unparsable range is `false`.
+ */
+export declare function satisfies(version: string, range: string): boolean;
+/**
+ * The environment shown in the report, from the app itself: `production` when `app.inProduction`,
+ * `test` when `app.inTest`, else the app's node environment, and `development` when that is unset.
+ */
+export declare function environmentOf(app: Pick<ApplicationService, 'inProduction' | 'inTest' | 'nodeEnvironment'>): string;
+/** Run the checks and build the report. Throws {@link AgoraDoctorUsageError} for an unknown `--only`. */
+export declare function runAgoraDoctor(app: ApplicationService, registered: readonly AgoraDoctorCheck[], options?: AgoraDoctorOptions): Promise<{
+    report: AgoraDoctorReport;
+    exitCode: 0 | 1;
+}>;
+export interface Paint {
+    green(text: string): string;
+    yellow(text: string): string;
+    red(text: string): string;
+    dim(text: string): string;
+    bold(text: string): string;
+}
+/** The human report. `fancy` = colors and symbols (a TTY without `NO_COLOR`). */
+export declare function renderAgoraDoctor(report: AgoraDoctorReport, options?: {
+    verbose?: boolean;
+    fancy?: boolean;
+    paint?: Paint;
+}): string;
+export {};
+//# sourceMappingURL=agora_doctor.d.ts.map

package/dist/src/doctor/agora_doctor.d.ts.map

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