@adonis-agora/authkit-server 1.0.0-rc.4 → 1.0.0-rc.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @adonis-agora/authkit-server
 
+## 1.0.0-rc.5
+
+### Minor Changes
+
+- [#463](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/463) [`e9f02d8`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/e9f02d8e6858f9ec8e5cdb2b77409fd0c31cb13d) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - `node ace agora:doctor`: one health check for every installed `@adonis-agora` lib. authkit registers its checks (every `authkit:doctor` finding under a stable id such as `authkit.issuer`, plus `authkit.signing-key-age`, `authkit.console-gate`, `authkit.peers` and `authkit.agora-siblings`). Flags: `--json`, `--strict`, `--deep`, `--lib`, `--only`, `--verbose`, `--no-boot`; exit `0` / `1` (error, or warning with `--strict`) / `2` (the doctor could not run). New `@adonis-agora/authkit-server/doctor` entry exports the checks for `--no-boot`. `authkit:doctor` is unchanged.
+
 ## 1.0.0-rc.4
 
 ### Patch Changes

package/build/commands/agora_doctor.d.ts

@@ -0,0 +1,22 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import type { CommandOptions } from '@adonisjs/core/types/ace';
+/**
+ * `node ace agora:doctor`: one health check for every installed `@adonis-agora` lib. Exit code `0`
+ * when nothing is an error (`--strict`: nor a warning), `1` otherwise, `2` when the doctor itself
+ * cannot run.
+ */
+export default class AgoraDoctor extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: CommandOptions;
+    /** A `<lib>:doctor` alias sets this to pre-filter its lib. */
+    protected presetLib: string | undefined;
+    json: boolean;
+    lib?: string;
+    deep: boolean;
+    only?: string;
+    strict: boolean;
+    verbose: boolean;
+    boot: boolean;
+    run(): Promise<void>;
+}

package/build/commands/agora_doctor.js

@@ -0,0 +1,109 @@
+// agora-doctor command v1 — keep identical across libs
+// Revision 1.1 (see the canonical README for the changelog).
+// Every @adonis-agora lib ships this command (commands/agora_doctor.ts); whichever copy Ace loads
+// last wins, and they all behave the same. Each repo's CI checks its sha256 against the pinned
+// canonical one. Never edit a lib's copy: change the canonical copy, then re-copy it into every lib.
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseCommand, flags } from '@adonisjs/core/ace';
+import { AgoraDoctorUsageError, discoverDoctorChecks, readDoctorChecks, renderAgoraDoctor, runAgoraDoctor, } from '../src/doctor/agora_doctor.js';
+/**
+ * `node ace agora:doctor`: one health check for every installed `@adonis-agora` lib. Exit code `0`
+ * when nothing is an error (`--strict`: nor a warning), `1` otherwise, `2` when the doctor itself
+ * cannot run.
+ */
+export default class AgoraDoctor extends BaseCommand {
+    static commandName = 'agora:doctor';
+    static description = 'Check the configuration of every installed @adonis-agora lib';
+    // The app is booted by `run()` itself, so `--no-boot` can skip it.
+    static options = { startApp: false };
+    /** A `<lib>:doctor` alias sets this to pre-filter its lib. */
+    presetLib = undefined;
+    async run() {
+        const err = (line) => process.stderr.write(`${line}\n`);
+        try {
+            let checks;
+            if (this.boot === false) {
+                checks = await discoverDoctorChecks(this.app);
+            }
+            else {
+                if (!this.app.isReady) {
+                    try {
+                        await this.app.boot();
+                        await this.app.start(() => { });
+                    }
+                    catch (error) {
+                        const reason = error instanceof Error ? error.message : String(error);
+                        throw new AgoraDoctorUsageError(`the app did not boot (${reason}). Fix the boot error, or run with --no-boot.`);
+                    }
+                }
+                checks = await readDoctorChecks(this.app.container);
+            }
+            const libs = (this.lib ?? this.presetLib)
+                ?.split(',')
+                .map((name) => name.trim())
+                .filter(Boolean);
+            const { report, exitCode } = await runAgoraDoctor(this.app, checks, {
+                ...(libs ? { libs } : {}),
+                ...(this.only ? { only: this.only } : {}),
+                deep: this.deep === true,
+                noBoot: this.boot === false,
+                strict: this.strict === true,
+            });
+            if (this.json) {
+                process.stdout.write(`${JSON.stringify(report)}\n`);
+            }
+            else {
+                const fancy = process.stdout.isTTY === true && !process.env.NO_COLOR;
+                const c = this.colors;
+                process.stdout.write(renderAgoraDoctor(report, {
+                    verbose: this.verbose === true,
+                    fancy,
+                    paint: {
+                        green: (t) => c.green(t),
+                        yellow: (t) => c.yellow(t),
+                        red: (t) => c.red(t),
+                        dim: (t) => c.dim(t),
+                        bold: (t) => c.bold(t),
+                    },
+                }));
+            }
+            this.exitCode = exitCode;
+        }
+        catch (error) {
+            if (!(error instanceof AgoraDoctorUsageError))
+                throw error;
+            err(`agora:doctor: ${error.message}`);
+            this.exitCode = 2;
+        }
+    }
+}
+__decorate([
+    flags.boolean({ description: 'Print one JSON object to stdout' })
+], AgoraDoctor.prototype, "json", void 0);
+__decorate([
+    flags.string({ description: 'Only these libs, comma separated (durable,payments)' })
+], AgoraDoctor.prototype, "lib", void 0);
+__decorate([
+    flags.boolean({ description: 'Also run checks that touch the database, Redis or the network' })
+], AgoraDoctor.prototype, "deep", void 0);
+__decorate([
+    flags.string({ description: 'Run one check by id' })
+], AgoraDoctor.prototype, "only", void 0);
+__decorate([
+    flags.boolean({ description: 'Fail (exit 1) on warnings too' })
+], AgoraDoctor.prototype, "strict", void 0);
+__decorate([
+    flags.boolean({ description: 'Show skipped checks and every message' })
+], AgoraDoctor.prototype, "verbose", void 0);
+__decorate([
+    flags.boolean({
+        description: 'Boot the app first; --no-boot checks the config only (when boot itself fails)',
+        default: true,
+        showNegatedVariantInHelp: true,
+    })
+], AgoraDoctor.prototype, "boot", void 0);

package/build/commands/commands.json

@@ -333,6 +333,70 @@
       "args": [],
       "options": { "startApp": true },
       "filePath": "expire_scan.js"
+    },
+    {
+      "commandName": "agora:doctor",
+      "description": "Check the configuration of every installed @adonis-agora lib",
+      "namespace": "agora",
+      "aliases": [],
+      "flags": [
+        {
+          "name": "json",
+          "flagName": "json",
+          "required": false,
+          "type": "boolean",
+          "description": "Print one JSON object to stdout"
+        },
+        {
+          "name": "lib",
+          "flagName": "lib",
+          "required": false,
+          "type": "string",
+          "description": "Only these libs, comma separated (durable,payments)"
+        },
+        {
+          "name": "deep",
+          "flagName": "deep",
+          "required": false,
+          "type": "boolean",
+          "description": "Also run checks that touch the database, Redis or the network"
+        },
+        {
+          "name": "only",
+          "flagName": "only",
+          "required": false,
+          "type": "string",
+          "description": "Run one check by id"
+        },
+        {
+          "name": "strict",
+          "flagName": "strict",
+          "required": false,
+          "type": "boolean",
+          "description": "Fail (exit 1) on warnings too"
+        },
+        {
+          "name": "verbose",
+          "flagName": "verbose",
+          "required": false,
+          "type": "boolean",
+          "description": "Show skipped checks and every message"
+        },
+        {
+          "name": "boot",
+          "flagName": "boot",
+          "required": false,
+          "type": "boolean",
+          "description": "Boot the app first; --no-boot checks the config only (when boot itself fails)",
+          "default": true,
+          "showNegatedVariantInHelp": true
+        }
+      ],
+      "args": [],
+      "options": {
+        "startApp": false
+      },
+      "filePath": "agora_doctor.js"
     }
   ]
 }

package/build/commands/doctor.js

@@ -1,43 +1,6 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
 import { BaseCommand } from '@adonisjs/core/ace';
-import { DatabaseAdapter } from '../src/adapters/database_adapter.js';
-import { resolveAuthkitConfig } from '../src/commands/resolve_config.js';
-import { defaultEncryptForStore } from '../src/define_config.js';
-import { hasErrors, runAllChecks, signingKeyAgeFinding, } from '../src/doctor/checks.js';
-import { signingKeyAgeDays } from '../src/keys/keystore.js';
-import { KeystoreCodec } from '../src/keys/keystore_codec.js';
-import { loadEncryptionService } from '../src/keys/keystore_crypto.js';
-import { KeystoreManager, resolveKeystoreVault } from '../src/keys/keystore_manager.js';
-/**
- * Tenta importar um peer; `true` se importável.
- *
- * Distingue "não instalado" de "instalado mas quebrado": só um erro de
- * módulo-não-encontrado (`ERR_MODULE_NOT_FOUND`/`MODULE_NOT_FOUND`) é tratado como
- * peer ausente (silencioso — é o caso esperado). Qualquer outro erro significa que
- * o peer ESTÁ presente mas falhou ao carregar (import circular, erro de sintaxe,
- * config inválida) — isso o doctor precisa gritar, senão um peer quebrado aparece
- * como "ausente" e o diagnóstico mente.
- */
-async function canImport(specifier, logger) {
-    try {
-        await import(__rewriteRelativeImportExtension(specifier));
-        return true;
-    }
-    catch (err) {
-        const code = err?.code;
-        if (code !== 'ERR_MODULE_NOT_FOUND' && code !== 'MODULE_NOT_FOUND') {
-            logger?.warning(`⚠️  ${specifier} está instalado mas falhou ao carregar: ${err.message}`);
-        }
-        return false;
-    }
-}
+import { hasErrors, runAllChecks } from '../src/doctor/checks.js';
+import { buildDoctorInput, managedSigningKeyAgeFinding } from '../src/doctor/doctor_input.js';
 export default class AuthkitDoctor extends BaseCommand {
     static commandName = 'authkit:doctor';
     static description = 'Valida a configuração do AuthKit no host e imprime achados (✅/⚠️/❌). Sai com código !=0 se houver erros.';
@@ -48,50 +11,21 @@ export default class AuthkitDoctor extends BaseCommand {
     ];
     static options = { startApp: true };
     async run() {
-        const config = await this.app.container.make('config');
-        // `defineConfig` exporta um config provider — resolve antes de inspecionar,
-        // senão todo campo aparece como "ausente" (provider cru não tem issuer etc.).
-        let authkitConfig = null;
+        // `buildDoctorInput` resolve o config provider de `config/authkit.ts` antes de inspecionar.
+        let input;
         try {
-            authkitConfig = await resolveAuthkitConfig(this.app, config.get('authkit', null));
+            input = await buildDoctorInput(this.app, this.logger);
         }
         catch (error) {
             this.logger.logError(`❌ config/authkit.ts falhou ao resolver: ${error.message}`);
             this.exitCode = 1;
             return;
         }
-        const sessionConfig = config.get('session', null) ?? null;
-        const input = {
-            authkitConfig,
-            sessionConfig,
-            peers: {
-                session: await canImport('@adonisjs/session', this.logger),
-                shield: await canImport('@adonisjs/shield', this.logger),
-                ally: await canImport('@adonisjs/ally', this.logger),
-                limiter: await canImport('@adonisjs/limiter', this.logger),
-            },
-            __adapterClasses: { DatabaseAdapter },
-        };
         const findings = runAllChecks(input);
         // Adiciona o finding de idade da chave de assinatura managed (best-effort).
-        const jwksInput = (authkitConfig?.jwksConfig ?? authkitConfig?.jwks);
-        if (jwksInput?.source === 'managed' && jwksInput?.store) {
-            try {
-                const vault = resolveKeystoreVault(jwksInput.store, {
-                    makePath: (p) => this.app.makePath(p),
-                    container: this.app.container,
-                });
-                const encrypt = jwksInput.encrypt ?? defaultEncryptForStore(jwksInput.store);
-                const enc = encrypt ? await loadEncryptionService().catch(() => undefined) : undefined;
-                const mgr = new KeystoreManager(vault, new KeystoreCodec({ encrypt, enc }), jwksInput.algorithm ?? 'RS256');
-                const store = await mgr.read().catch(() => null);
-                const maxAge = jwksInput.rotationDays ?? 90;
-                findings.push(signingKeyAgeFinding(signingKeyAgeDays(store), maxAge));
-            }
-            catch {
-                /* idade é best-effort no doctor */
-            }
-        }
+        const keyAge = await managedSigningKeyAgeFinding(this.app, input.authkitConfig);
+        if (keyAge)
+            findings.push(keyAge);
         this.print(findings);
         if (hasErrors(findings)) {
             this.exitCode = 1;

package/build/providers/authkit_server_provider.js

@@ -17,6 +17,8 @@ import { configProvider } from '@adonisjs/core';
 import { RuntimeException } from '@adonisjs/core/exceptions';
 import { setBootedApp } from '../services/booted_app.js';
 import { defaultEncryptForStore } from '../src/define_config.js';
+import { authkitDoctorChecks } from '../src/doctor/agora_checks.js';
+import { registerDoctorChecks } from '../src/doctor/agora_doctor.js';
 import { resolveAppKey } from '../src/host/app_key.js';
 import { resolveEffectiveKeyRotation } from '../src/host/key_rotation.js';
 import { RuntimeSettings } from '../src/host/runtime_settings.js';
@@ -33,6 +35,9 @@ export default class AuthkitServerProvider {
         this.app = app;
     }
     async boot() {
+        // `node ace agora:doctor` reads these after boot, from the registry every @adonis-agora lib
+        // shares. Registered here rather than in `register()`, which AdonisJS does not await.
+        await registerDoctorChecks(this.app.container, authkitDoctorChecks());
         // EAGER + LOUD (fail-fast): se o host configurou `config/authkit.ts`, a
         // `appKey` é indispensável — o oidc-provider a usa para assinar TODOS os
         // cookies (keygrip). Antes, essa validação só rodava dentro do factory

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

@@ -0,0 +1,15 @@
+import type { AgoraDoctorCheck, AgoraDoctorResult } from './agora_doctor.js';
+import { type DoctorInput, type Finding } from './checks.js';
+export declare const AUTHKIT_DOCTOR_DOCS = "https://davidecarvalho.github.io/agora/docs/authkit/health-check";
+type CheckFn = (input: DoctorInput) => Finding | Finding[] | null;
+/**
+ * The `authkit:doctor` checks, in `runAllChecks` order, with their frozen `agora:doctor` ids
+ * (`authkit.` + the function name without `check`, in kebab case). Ids are public: never rename.
+ */
+export declare const AUTHKIT_DOCTOR_TABLE: ReadonlyArray<readonly [id: string, title: string, fn: CheckFn]>;
+export declare const AUTHKIT_DOCTOR_PACKAGE = "@adonis-agora/authkit-server";
+/** `admin.authorize` omitted: open outside production, denies every request in production. */
+export declare function consoleGateResult(authkitConfig: Record<string, any> | null, inProduction: boolean): AgoraDoctorResult;
+/** The checks authkit registers into `agora:doctor`. */
+export declare function authkitDoctorChecks(): AgoraDoctorCheck[];
+export {};

package/build/src/doctor/agora_checks.js

@@ -0,0 +1,150 @@
+import { checkAccessTokens, checkAccountExpiration, checkAccountStore, checkAccountStoreColumns, checkAdapterVolatility, checkAdmin, checkAlly, checkAuthMethodsSetting, checkBotProtection, checkClients, checkConfigResolves, checkConsoleSignIn, checkEmailChange, checkFirstPartyClients, checkIssuer, checkJwks, checkOrganizations, checkOtpLockout, checkPasskeyAutofill, checkPasswordExpiration, checkPasswordHistory, checkPasswordPepper, checkPasswordPolicy, checkRateLimit, checkRequireVerifiedEmail, checkRolesCatalog, checkSecurityNotifications, checkSession, checkSessionPolicy, checkSettings, checkShield, checkSudoMode, checkWebauthn, } from './checks.js';
+export const AUTHKIT_DOCTOR_DOCS = 'https://davidecarvalho.github.io/agora/docs/authkit/health-check';
+/**
+ * The `authkit:doctor` checks, in `runAllChecks` order, with their frozen `agora:doctor` ids
+ * (`authkit.` + the function name without `check`, in kebab case). Ids are public: never rename.
+ */
+export const AUTHKIT_DOCTOR_TABLE = [
+    ['authkit.config-resolves', 'config/authkit.ts resolves', checkConfigResolves],
+    ['authkit.issuer', 'Issuer and mount path', checkIssuer],
+    ['authkit.clients', 'OIDC clients', checkClients],
+    ['authkit.adapter-volatility', 'Persistent adapter', checkAdapterVolatility],
+    ['authkit.account-store', 'Account store capabilities', checkAccountStore],
+    ['authkit.account-store-columns', 'Account store columns', checkAccountStoreColumns],
+    ['authkit.session', 'Session', checkSession],
+    ['authkit.shield', 'Shield (CSRF)', checkShield],
+    ['authkit.ally', 'Social login (ally)', checkAlly],
+    ['authkit.rate-limit', 'Rate limiting', checkRateLimit],
+    ['authkit.admin', 'Admin console', checkAdmin],
+    ['authkit.require-verified-email', 'Verified e-mail gate', checkRequireVerifiedEmail],
+    ['authkit.bot-protection', 'Bot protection', checkBotProtection],
+    ['authkit.webauthn', 'Passkeys (WebAuthn)', checkWebauthn],
+    ['authkit.password-policy', 'Password policy', checkPasswordPolicy],
+    ['authkit.jwks', 'Signing keys (JWKS)', checkJwks],
+    ['authkit.access-tokens', 'Access tokens', checkAccessTokens],
+    ['authkit.organizations', 'Organizations', checkOrganizations],
+    ['authkit.settings', 'Runtime settings', checkSettings],
+    ['authkit.auth-methods-setting', 'Sign-in methods setting', checkAuthMethodsSetting],
+    ['authkit.email-change', 'E-mail change', checkEmailChange],
+    ['authkit.security-notifications', 'Security notifications', checkSecurityNotifications],
+    ['authkit.password-pepper', 'Password pepper', checkPasswordPepper],
+    ['authkit.password-history', 'Password history', checkPasswordHistory],
+    ['authkit.password-expiration', 'Password expiration', checkPasswordExpiration],
+    ['authkit.session-policy', 'Session policy', checkSessionPolicy],
+    ['authkit.roles-catalog', 'Roles catalog', checkRolesCatalog],
+    ['authkit.otp-lockout', 'OTP lockout', checkOtpLockout],
+    ['authkit.sudo-mode', 'Sudo mode', checkSudoMode],
+    ['authkit.account-expiration', 'Account expiration', checkAccountExpiration],
+    ['authkit.passkey-autofill', 'Passkey autofill', checkPasskeyAutofill],
+    ['authkit.first-party-clients', 'First-party clients', checkFirstPartyClients],
+    ['authkit.console-sign-in', 'Console sign-in', checkConsoleSignIn],
+];
+export const AUTHKIT_DOCTOR_PACKAGE = '@adonis-agora/authkit-server';
+/** One input per app per doctor run: every check reads the same resolved config. */
+const prepared = new WeakMap();
+function prepare(app) {
+    let entry = prepared.get(app);
+    const state = app.getState?.();
+    if (state === 'created' || state === 'initiated') {
+        return Promise.resolve({ input: null, error: null, notBooted: true });
+    }
+    if (!entry) {
+        // Loaded on demand: the provider imports this module, and the input builder pulls in adapters.
+        entry = import('./doctor_input.js')
+            .then(({ buildDoctorInput }) => buildDoctorInput(app))
+            .then((input) => ({ input, error: null }), (error) => ({
+            input: null,
+            error: error instanceof Error ? error.message : String(error),
+        }));
+        prepared.set(app, entry);
+    }
+    return entry;
+}
+function toResults(found) {
+    const list = found === null ? [] : Array.isArray(found) ? found : [found];
+    if (list.length === 0)
+        return [{ status: 'skip', message: 'not applicable to this config' }];
+    return list.map((finding) => ({
+        status: finding.level,
+        message: finding.message,
+        ...(finding.level === 'ok' ? {} : { docs: AUTHKIT_DOCTOR_DOCS }),
+    }));
+}
+/** `admin.authorize` omitted: open outside production, denies every request in production. */
+export function consoleGateResult(authkitConfig, inProduction) {
+    const admin = authkitConfig?.admin;
+    if (!admin || admin.enabled !== true) {
+        return { status: 'skip', message: 'admin console is off' };
+    }
+    if (admin.authorize) {
+        return { status: 'ok', message: 'admin console has `admin.authorize`' };
+    }
+    const fix = 'Set `admin.authorize` in config/authkit.ts';
+    return inProduction
+        ? {
+            status: 'error',
+            message: 'admin console has no `admin.authorize`: it denies every request in production',
+            fix,
+            docs: AUTHKIT_DOCTOR_DOCS,
+        }
+        : {
+            status: 'warn',
+            message: 'admin console has no `admin.authorize`: open here, denies every request in production',
+            fix,
+            docs: AUTHKIT_DOCTOR_DOCS,
+        };
+}
+/** The checks authkit registers into `agora:doctor`. */
+export function authkitDoctorChecks() {
+    const checks = AUTHKIT_DOCTOR_TABLE.map(([id, title, fn]) => ({
+        id,
+        lib: 'authkit',
+        package: AUTHKIT_DOCTOR_PACKAGE,
+        title,
+        async run(app) {
+            const { input, error, notBooted } = await prepare(app);
+            if (notBooted)
+                return [{ status: 'skip', message: 'needs a booted app (run without --no-boot)' }];
+            if (input === null) {
+                return id === 'authkit.config-resolves'
+                    ? [
+                        {
+                            status: 'error',
+                            message: `config/authkit.ts failed to resolve: ${error}`,
+                            docs: AUTHKIT_DOCTOR_DOCS,
+                        },
+                    ]
+                    : [{ status: 'skip', message: 'config/authkit.ts did not resolve' }];
+            }
+            return toResults(fn(input));
+        },
+    }));
+    checks.push({
+        id: 'authkit.signing-key-age',
+        lib: 'authkit',
+        package: AUTHKIT_DOCTOR_PACKAGE,
+        title: 'Signing key age',
+        async run(app) {
+            const { input, notBooted } = await prepare(app);
+            if (notBooted) {
+                return { status: 'skip', message: 'needs a booted app (run without --no-boot)' };
+            }
+            if (!input)
+                return toResults(null);
+            const { managedSigningKeyAgeFinding } = await import('./doctor_input.js');
+            return toResults(await managedSigningKeyAgeFinding(app, input.authkitConfig));
+        },
+    }, {
+        id: 'authkit.console-gate',
+        lib: 'authkit',
+        package: AUTHKIT_DOCTOR_PACKAGE,
+        title: 'Admin console access in production',
+        async run(app) {
+            const { input, notBooted } = await prepare(app);
+            if (notBooted)
+                return { status: 'skip', message: 'needs a booted app (run without --no-boot)' };
+            return consoleGateResult(input?.authkitConfig ?? null, app.inProduction);
+        },
+    });
+    return checks;
+}

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 {};