@adonis-agora/filter 1.0.0-rc.0 → 1.0.0-rc.2

package/dist/src/dev_tools/explain.js

@@ -0,0 +1,168 @@
+import { specToFilterConfig } from '../filter_spec.js';
+import { filterableFieldPaths, sortableFieldPaths } from '../generate_client.js';
+import { FILTER_OPERATORS, OPERATOR_ALIASES } from '../operators.js';
+import { parseFilterRequest } from '../parse_request.js';
+import { applyFilter } from '../runner.js';
+import { parseQueryString } from './query_string.js';
+const MAX_VALUE = 200;
+function show(value) {
+    if (typeof value === 'string')
+        return value.length > MAX_VALUE ? `${value.slice(0, MAX_VALUE)}…` : value;
+    if (Array.isArray(value))
+        return value.slice(0, 50).map(show);
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value).slice(0, 50))
+            out[k] = show(v);
+        return out;
+    }
+    return value;
+}
+/**
+ * A query builder that records every call instead of running SQL: the dry-run target. Callback
+ * arguments (sub-queries, `whereHas`) are run against a nested recorder and kept as `calls`.
+ */
+export function recordingBuilder(calls = []) {
+    const qb = new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== 'string' || prop === 'then')
+                return undefined;
+            return (...args) => {
+                const recorded = args.map((arg) => {
+                    if (typeof arg !== 'function')
+                        return show(arg);
+                    const nested = recordingBuilder();
+                    arg(nested.qb);
+                    return { callback: nested.calls };
+                });
+                calls.push({ method: prop, args: recorded });
+                return qb;
+            };
+        },
+    });
+    return { qb, calls };
+}
+function attempt(input, config) {
+    try {
+        applyFilter(recordingBuilder().qb, input, config);
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+/**
+ * Dry-run a query string against a spec, through the same parse, alias, validation, allow-list
+ * and builder code a request runs, with no database: what is kept, what is dropped or refused, and
+ * the builder calls it would make.
+ */
+export function explainFilterQuery(spec, query) {
+    const decoded = parseQueryString(query);
+    const parsed = parseFilterRequest(decoded);
+    const config = specToFilterConfig(spec);
+    const strict = { ...config, throwOnInvalid: true };
+    const input = (!parsed.sort || parsed.sort.length === 0) && spec.defaultSort.length > 0
+        ? { ...parsed, sort: [...spec.defaultSort] }
+        : parsed;
+    const issues = [];
+    const check = (part, subject, single) => {
+        const asConfigured = attempt(single, config);
+        if (asConfigured !== null) {
+            issues.push({ part, subject, message: asConfigured, effect: 'rejected' });
+            return;
+        }
+        const asStrict = attempt(single, strict);
+        if (asStrict !== null)
+            issues.push({ part, subject, message: asStrict, effect: 'dropped' });
+    };
+    for (const filter of parsed.filters ?? []) {
+        const subject = filter.field || (filter.AND ? 'AND group' : filter.OR ? 'OR group' : '?');
+        check('filter', subject, { filters: [filter] });
+    }
+    for (const sort of parsed.sort ?? [])
+        check('sort', sort.field, { sort: [sort] });
+    for (const field of parsed.distinct ?? [])
+        check('distinct', field, { distinct: [field] });
+    if (parsed.search !== undefined && !spec.fullText && spec.searchable.length === 0) {
+        issues.push({
+            part: 'search',
+            subject: parsed.search,
+            message: 'the spec declares no `searchable` fields or `fullText`, so `search` does nothing',
+            effect: 'ignored',
+        });
+    }
+    const maxSize = spec.maxSize ?? 100;
+    if (parsed.size !== undefined && (parsed.size > maxSize || parsed.size < 1)) {
+        issues.push({
+            part: 'size',
+            subject: String(parsed.size),
+            message: `size is clamped to 1..${maxSize}`,
+            effect: 'clamped',
+        });
+    }
+    const recorder = recordingBuilder();
+    let rejection = null;
+    let pagination = null;
+    try {
+        pagination = applyFilter(recorder.qb, input, config);
+    }
+    catch (error) {
+        rejection = error instanceof Error ? error.message : String(error);
+    }
+    return {
+        decoded,
+        parsed,
+        rejected: rejection !== null,
+        rejection,
+        issues,
+        calls: rejection === null ? recorder.calls : [],
+        pagination,
+        serverScope: {
+            tenantColumn: spec.tenant?.column ?? null,
+            defaultFilters: spec.defaultFilters.map(show),
+        },
+    };
+}
+/** The spec as data: allow-lists with field types and operators, relations and defaults. */
+export function describeSpec(spec, name) {
+    return {
+        name,
+        filterable: spec.filterable,
+        sortable: spec.sortable,
+        /** Every filterable path, relation-dotted (`'*'` lists contribute none). */
+        filterablePaths: filterableFieldPaths(spec),
+        sortablePaths: sortableFieldPaths(spec),
+        operators: [...FILTER_OPERATORS],
+        operatorAliases: { ...OPERATOR_ALIASES },
+        searchable: [...spec.searchable],
+        fullText: spec.fullText ? { column: spec.fullText.column } : null,
+        fieldTypes: spec.fieldTypes ?? {},
+        relations: describeRelations(spec.relations),
+        maxDepth: spec.maxDepth,
+        aliases: spec.aliases ?? {},
+        computed: spec.computed
+            ? Object.fromEntries(Object.entries(spec.computed).map(([key, source]) => [
+                key,
+                typeof source === 'string' ? source : '(function)',
+            ]))
+            : {},
+        tenantColumn: spec.tenant?.column ?? null,
+        defaultFilters: spec.defaultFilters.map(show),
+        defaultSort: [...spec.defaultSort],
+        defaultSize: spec.defaultSize ?? null,
+        maxSize: spec.maxSize ?? null,
+        throwOnInvalid: spec.throwOnInvalid,
+    };
+}
+function describeRelations(relations) {
+    const out = {};
+    for (const [key, rel] of Object.entries(relations)) {
+        out[key] = {
+            filterable: rel.filterable,
+            sortable: rel.sortable ?? rel.filterable,
+            relations: rel.relations ? describeRelations(rel.relations) : {},
+        };
+    }
+    return out;
+}
+//# sourceMappingURL=explain.js.map

package/dist/src/dev_tools/explain.js.map

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

package/dist/src/dev_tools/query_string.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A small, safe decoder for a filter query string (`filter[name][contains]=Al&sort=-age&page=2`)
+ * into the nested object `ctx.request.qs()` returns: bracket keys become nested objects, numeric
+ * indexes and `[]` become arrays. Used by the dev tools, which receive the query as a string.
+ */
+/** Decode `query` (with or without a leading `?`) into a nested object. */
+export declare function parseQueryString(query: string): Record<string, unknown>;
+//# sourceMappingURL=query_string.d.ts.map

package/dist/src/dev_tools/query_string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query_string.d.ts","sourceRoot":"","sources":["../../../src/dev_tools/query_string.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiDH,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA+BvE"}

package/dist/src/dev_tools/query_string.js

@@ -0,0 +1,102 @@
+/**
+ * A small, safe decoder for a filter query string (`filter[name][contains]=Al&sort=-age&page=2`)
+ * into the nested object `ctx.request.qs()` returns: bracket keys become nested objects, numeric
+ * indexes and `[]` become arrays. Used by the dev tools, which receive the query as a string.
+ */
+const BLOCKED = new Set(['__proto__', 'constructor', 'prototype']);
+const MAX_PARAMS = 1000;
+const MAX_DEPTH = 20;
+function decode(part) {
+    try {
+        return decodeURIComponent(part.replace(/\+/g, ' '));
+    }
+    catch {
+        return part;
+    }
+}
+/** `filter[name][contains]` → `['filter', 'name', 'contains']`; `a[]` → `['a', '']`. */
+function keyPath(key) {
+    const open = key.indexOf('[');
+    if (open === -1)
+        return [key];
+    const path = [key.slice(0, open)];
+    const re = /\[([^\]]*)\]/g;
+    re.lastIndex = open;
+    let end = open;
+    for (let match = re.exec(key); match !== null; match = re.exec(key)) {
+        if (match.index !== end)
+            break;
+        path.push(match[1]);
+        end = re.lastIndex;
+        if (path.length > MAX_DEPTH)
+            return null;
+    }
+    if (end !== key.length)
+        path.push(key.slice(end));
+    return path;
+}
+/** Objects whose keys are all array indexes become arrays (in index order). */
+function compact(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    const node = value;
+    for (const key of Object.keys(node))
+        node[key] = compact(node[key]);
+    const keys = Object.keys(node);
+    if (keys.length > 0 && keys.every((k) => /^\d+$/.test(k))) {
+        return keys
+            .map(Number)
+            .sort((a, b) => a - b)
+            .map((k) => node[String(k)]);
+    }
+    return node;
+}
+/** Decode `query` (with or without a leading `?`) into a nested object. */
+export function parseQueryString(query) {
+    const root = {};
+    const text = query.startsWith('?') ? query.slice(1) : query;
+    const pairs = text.split('&').filter((p) => p !== '');
+    for (const pair of pairs.slice(0, MAX_PARAMS)) {
+        const eq = pair.indexOf('=');
+        const rawKey = decode(eq === -1 ? pair : pair.slice(0, eq));
+        const value = eq === -1 ? '' : decode(pair.slice(eq + 1));
+        const path = keyPath(rawKey);
+        if (path === null || path[0] === '' || path.some((seg) => BLOCKED.has(seg)))
+            continue;
+        let node = root;
+        for (let i = 0; i < path.length; i++) {
+            let seg = path[i];
+            const last = i === path.length - 1;
+            if (seg === '')
+                seg = String(Object.keys(node).length);
+            if (last) {
+                const existing = node[seg];
+                if (existing === undefined)
+                    node[seg] = value;
+                else if (Array.isArray(existing))
+                    existing.push(value);
+                else if (typeof existing === 'string')
+                    node[seg] = [existing, value];
+                break;
+            }
+            const next = node[seg];
+            if (next === undefined || typeof next !== 'object' || next === null || Array.isArray(next)) {
+                node[seg] = Object.create(null);
+            }
+            node = node[seg];
+        }
+    }
+    return toPlain(compact(root));
+}
+/** Null-prototype nodes back to plain objects (so `toEqual` and spreading behave). */
+function toPlain(value) {
+    if (Array.isArray(value))
+        return value.map(toPlain);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const out = {};
+    for (const [key, inner] of Object.entries(value))
+        out[key] = toPlain(inner);
+    return out;
+}
+//# sourceMappingURL=query_string.js.map

package/dist/src/dev_tools/query_string.js.map

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

package/dist/src/dev_tools/tools.d.ts

@@ -0,0 +1,25 @@
+import type { ManifestLoad } from '../manifest.js';
+import type { DevTool } from './contract.js';
+/** How the tools reach the app's `filters` manifest (resolved at call time). */
+export interface FilterDevToolsDeps {
+    manifest: () => Promise<ManifestLoad>;
+}
+/** One page of `items` in the `{ items, next }` shape every dev-tools list returns. */
+export declare function pageOf<T>(items: readonly T[], input: Record<string, unknown>): {
+    items: T[];
+    next: number | null;
+};
+/** The filter developer tools (all read-only, no database). */
+export declare function filterDevTools(deps: FilterDevToolsDeps): DevTool[];
+/** The slice of the AdonisJS container {@link registerFilterDevTools} uses. */
+export interface DevToolsContainer {
+    hasBinding(binding: string): boolean;
+    make(binding: string): Promise<unknown>;
+}
+/**
+ * Register the filter tools into the dev-tools hub, when the agent's MCP provider bound one and it
+ * can gate a lib without a console (`supports('endpoint-authorize')`). Never throws: returns why it
+ * did not register.
+ */
+export declare function registerFilterDevTools(container: DevToolsContainer, deps: FilterDevToolsDeps): Promise<'registered' | 'no-hub' | 'unsupported' | 'failed'>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/src/dev_tools/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/dev_tools/tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAqC,MAAM,eAAe,CAAC;AAIhF,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;CACvC;AAwBD,uFAAuF;AACvF,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAKzE,KAAK;IACL,IAAI;EAEP;AA6BD,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,EAAE,CAkElE;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACrC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzC;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,iBAAiB,EAC5B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,QAAQ,CAAC,CAa7D"}

package/dist/src/dev_tools/tools.js

@@ -0,0 +1,147 @@
+import { DEV_TOOLS_BINDING } from './contract.js';
+import { describeSpec, explainFilterQuery } from './explain.js';
+const limit = {
+    type: 'integer',
+    description: 'How many items to return (default 20, max 100).',
+    minimum: 1,
+    maximum: 100,
+};
+const page = {
+    type: 'integer',
+    description: 'Page number, from 1 (the `next` of the previous answer).',
+    minimum: 1,
+};
+const name = {
+    type: 'string',
+    description: 'The spec name: a key of the `filters` manifest in config/filter.ts.',
+};
+function intOf(value, fallback, max = Number.MAX_SAFE_INTEGER) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.max(1, Math.min(max, Math.floor(value)))
+        : fallback;
+}
+/** One page of `items` in the `{ items, next }` shape every dev-tools list returns. */
+export function pageOf(items, input) {
+    const size = intOf(input.limit, 20, 100);
+    const number = intOf(input.page, 1);
+    const start = (number - 1) * size;
+    return {
+        items: items.slice(start, start + size),
+        next: start + size < items.length ? number + 1 : null,
+    };
+}
+function problem(load) {
+    switch (load.status) {
+        case 'missing':
+            return `No ${load.entrypoint.replace(/\.js$/, '.ts')}: declare an exported \`filters\` manifest there to list your specs.`;
+        case 'empty':
+            return `${load.entrypoint.replace(/\.js$/, '.ts')} exports no \`filters\` manifest of defineFilter specs.`;
+        case 'failed':
+            return `${load.entrypoint.replace(/\.js$/, '.ts')} failed to load: ${load.error}`;
+    }
+}
+async function manifestOrThrow(deps) {
+    const load = await deps.manifest();
+    if (load.status !== 'loaded')
+        throw new Error(problem(load));
+    return load.manifest;
+}
+async function entryOf(deps, input) {
+    const key = typeof input.name === 'string' ? input.name.trim() : '';
+    if (key === '')
+        throw new Error('`name` is required: a spec name from filter_list_specs');
+    const manifest = await manifestOrThrow(deps);
+    if (!Object.hasOwn(manifest, key)) {
+        throw new Error(`No spec "${key}". Known: ${Object.keys(manifest).sort().join(', ')}`);
+    }
+    return { key, entry: manifest[key] };
+}
+/** The filter developer tools (all read-only, no database). */
+export function filterDevTools(deps) {
+    return [
+        {
+            name: 'filter_list_specs',
+            kind: 'read',
+            description: 'The filter specs declared in the `filters` manifest of config/filter.ts: name, how many ' +
+                'filterable/sortable fields, searchable fields and relations. Paged: { items, next }.',
+            input: { type: 'object', properties: { limit, page } },
+            async run(input) {
+                const load = await deps.manifest();
+                if (load.status !== 'loaded')
+                    return { items: [], next: null, hint: problem(load) };
+                const items = Object.entries(load.manifest)
+                    .sort(([a], [b]) => a.localeCompare(b))
+                    .map(([key, entry]) => {
+                    const spec = describeSpec(entry.spec, key);
+                    return {
+                        name: key,
+                        filterable: spec.filterable === '*' ? '*' : spec.filterablePaths.length,
+                        sortable: spec.sortable === '*' ? '*' : spec.sortablePaths.length,
+                        searchable: spec.searchable,
+                        relations: Object.keys(spec.relations),
+                        tenantScoped: spec.tenantColumn !== null,
+                    };
+                });
+                return pageOf(items, input);
+            },
+        },
+        {
+            name: 'filter_get_spec',
+            kind: 'read',
+            description: 'One filter spec in full: filterable and sortable paths (relation-dotted), field types, ' +
+                'operators, searchable/full-text, relations, maxDepth, aliases, computed fields, tenant ' +
+                'column, default filters/sort and page sizes.',
+            input: { type: 'object', properties: { name }, required: ['name'] },
+            async run(input) {
+                const { key, entry } = await entryOf(deps, input);
+                return { ...describeSpec(entry.spec, key), clientFieldTypes: entry.fieldTypes ?? {} };
+            },
+        },
+        {
+            name: 'filter_explain_query',
+            kind: 'read',
+            description: 'Dry-run a query string (filter[name][contains]=Al&sort=-age&page=2) against a spec, with ' +
+                'no database: what the server parses, which filters/sorts are dropped or make the request ' +
+                'fail and why, the query-builder calls it would make, and the resolved page/size.',
+            input: {
+                type: 'object',
+                properties: {
+                    name,
+                    query: {
+                        type: 'string',
+                        description: 'The query string, with or without the leading `?`.',
+                    },
+                },
+                required: ['name', 'query'],
+            },
+            async run(input) {
+                const { key, entry } = await entryOf(deps, input);
+                const query = typeof input.query === 'string' ? input.query : '';
+                return { spec: key, ...explainFilterQuery(entry.spec, query) };
+            },
+        },
+    ];
+}
+/**
+ * Register the filter tools into the dev-tools hub, when the agent's MCP provider bound one and it
+ * can gate a lib without a console (`supports('endpoint-authorize')`). Never throws: returns why it
+ * did not register.
+ */
+export async function registerFilterDevTools(container, deps) {
+    if (!container.hasBinding(DEV_TOOLS_BINDING))
+        return 'no-hub';
+    try {
+        const hub = (await container.make(DEV_TOOLS_BINDING));
+        if (hub?.version !== 1)
+            return 'unsupported';
+        if (typeof hub.supports !== 'function' || !hub.supports('endpoint-authorize')) {
+            return 'unsupported';
+        }
+        hub.register({ lib: 'filter', title: 'Query filters', tools: filterDevTools(deps) });
+        return 'registered';
+    }
+    catch {
+        return 'failed';
+    }
+}
+//# sourceMappingURL=tools.js.map

package/dist/src/dev_tools/tools.js.map

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

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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"}