@adonis-agora/authkit-server 1.0.0-rc.0 → 1.0.0-rc.10

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

@@ -0,0 +1,115 @@
+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 {};