@zhin.js/gateway 0.0.1-bootstrap.0 → 1.1.2

package/lib/config/console-schema.d.ts

@@ -0,0 +1,11 @@
+type Schema = Record<string, unknown>;
+/** The one JSON Schema union that existing string Select fields can represent exactly. */
+export declare function readStringLiteralOptions(input: Record<string, unknown>): readonly {
+    label: string;
+    value: string;
+    'x-i18n'?: Record<string, unknown>;
+}[] | null;
+/** Display projection only. Runtime retains the original JSON Schema validator. */
+export declare function jsonSchemaToConsoleSchema(input: unknown, key?: string): Schema | null;
+export declare function isConsoleSchemaJson(schema: Schema): boolean;
+export {};

package/lib/config/console-schema.js

@@ -0,0 +1,223 @@
+import { isSecretConfigSchema } from '@zhin.js/runtime';
+const record = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));
+const own = (value, key) => Object.hasOwn(value, key);
+const jsonTypes = new Set(['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']);
+const unsupportedKeywords = ['not', 'if', 'then', 'else', 'dependentSchemas', '$dynamicRef', 'patternProperties', 'contains'];
+/** The one JSON Schema union that existing string Select fields can represent exactly. */
+export function readStringLiteralOptions(input) {
+    if (!Array.isArray(input.anyOf) || input.anyOf.length === 0 || input.anyOf.length > 64)
+        return null;
+    const annotations = ['title', 'description', 'x-descriptionZh', 'x-i18n', '$comment'];
+    const parentKeys = ['anyOf', 'type', 'default', 'writeOnly', 'readOnly', 'deprecated', 'x-zhin-config', 'x-zhin-secret', ...annotations];
+    if (Object.keys(input).some(key => !parentKeys.includes(key))
+        || (input.type !== undefined && input.type !== 'string'))
+        return null;
+    const values = new Set();
+    const options = [];
+    for (const branch of input.anyOf) {
+        if (!branch || typeof branch !== 'object' || Array.isArray(branch))
+            return null;
+        const item = branch;
+        if (Object.keys(item).some(key => !['const', 'type', 'default', ...annotations].includes(key))
+            || !Object.prototype.hasOwnProperty.call(item, 'const')
+            || typeof item.const !== 'string' || item.const.length === 0 || item.const.length > 256
+            || values.has(item.const) || (item.type !== undefined && item.type !== 'string')
+            || (Object.prototype.hasOwnProperty.call(item, 'default') && item.default !== item.const))
+            return null;
+        values.add(item.const);
+        const label = [item['x-descriptionZh'], item.title, item.description].find(value => typeof value === 'string');
+        const translations = item['x-i18n'];
+        options.push({ label: typeof label === 'string' ? label : item.const, value: item.const,
+            ...(translations && typeof translations === 'object' && !Array.isArray(translations)
+                ? { 'x-i18n': structuredClone(translations) } : {}) });
+    }
+    if (Object.prototype.hasOwnProperty.call(input, 'default')
+        && (typeof input.default !== 'string' || !values.has(input.default)))
+        return null;
+    const metadata = input['x-zhin-config'];
+    if (metadata && typeof metadata === 'object' && 'options' in metadata) {
+        const custom = metadata.options;
+        if (!Array.isArray(custom) || custom.length !== options.length
+            || new Set(custom.map(item => item?.value)).size !== options.length
+            || custom.some(item => !item || typeof item !== 'object'
+                || typeof item.label !== 'string' || !values.has(item.value)))
+            return null;
+    }
+    return options;
+}
+/** Display projection only. Runtime retains the original JSON Schema validator. */
+export function jsonSchemaToConsoleSchema(input, key) {
+    if (input === undefined || input === null)
+        return null;
+    return convert(input, key, { root: input, references: new Set(), depth: 0, budget: { remaining: 8192 } });
+}
+function convert(input, key, context) {
+    const fallback = (reason) => ({ type: 'any', ...(key === undefined ? {} : { key }), ...(reason ? { reason } : {}) });
+    if (--context.budget.remaining < 0 || context.depth > 64)
+        return fallback('projection-limit');
+    if (typeof input === 'boolean')
+        return input ? fallback() : fallback('never-schema');
+    if (!record(input))
+        return fallback('malformed-schema');
+    const schema = input;
+    const properties = new Set([...context.properties ?? [], ...Object.keys(record(schema.properties) ? schema.properties : {})]);
+    const child = (value, name, references = context.references) => convert(value, name, { ...context, depth: context.depth + 1, references, properties: undefined });
+    const sameValue = (value, references = context.references) => convert(value, undefined, { ...context, depth: context.depth + 1, references, properties });
+    const finish = (value) => annotate(value, schema, key);
+    if (typeof schema.$ref === 'string') {
+        const reference = schema.$ref;
+        if (reference !== '#' && !reference.startsWith('#/'))
+            return finish(fallback('external-reference'));
+        if (context.references.has(reference))
+            return finish(fallback('cyclic-reference'));
+        let target = context.root;
+        try {
+            for (const raw of reference === '#' ? [] : reference.slice(2).split('/')) {
+                const part = decodeURIComponent(raw).replaceAll('~1', '/').replaceAll('~0', '~');
+                if (!record(target) || !own(target, part))
+                    return finish(fallback('unresolved-reference'));
+                target = target[part];
+            }
+        }
+        catch {
+            return finish(fallback('unresolved-reference'));
+        }
+        const references = new Set(context.references);
+        references.add(reference);
+        const resolved = sameValue(target, references);
+        const { $ref: _reference, ...siblings } = schema;
+        const validations = Object.keys(siblings).filter(name => !annotationKeys.has(name) && !['$defs', 'definitions', '$id', '$schema', '$comment'].includes(name));
+        return finish(validations.length ? { type: 'intersect', list: [resolved, sameValue(siblings)] } : resolved);
+    }
+    // Unsupported semantics stay editable as JSON at this field; siblings never disappear.
+    if (unsupportedKeywords.some(name => own(schema, name))) {
+        if (properties.size && validationOnly(schema, properties)) {
+            const constraint = { type: 'constraint', reason: 'host-validation' };
+            const { if: _if, then: _then, else: _else, not: _not, ...base } = schema;
+            return finish(schema.properties ? { type: 'intersect', list: [constraint, sameValue(base)] } : constraint);
+        }
+        return finish(fallback('unsupported-construct'));
+    }
+    const literalOptions = readStringLiteralOptions(schema);
+    if (literalOptions)
+        return finish({ type: 'string', options: literalOptions });
+    if (isConsoleSchemaJson(schema)) {
+        const result = { ...schema };
+        if (record(schema.object))
+            result.object = Object.fromEntries(Object.entries(schema.object).map(([name, value]) => [name, child(value)]));
+        if (Array.isArray(schema.list))
+            result.list = schema.list.map(value => child(value));
+        if (schema.inner !== undefined)
+            result.inner = schema.inner === false ? false : child(schema.inner);
+        if (schema.additional !== undefined)
+            result.additional = schema.additional === false ? false : child(schema.additional);
+        if (schema.type === 'const' && !own(schema, 'value') && own(schema, 'default'))
+            result.value = schema.default;
+        return finish(result);
+    }
+    for (const [keyword, type] of [['allOf', 'intersect'], ['anyOf', 'union'], ['oneOf', 'union']]) {
+        if (!Array.isArray(schema[keyword]))
+            continue;
+        if (schema[keyword].length === 0)
+            return finish(fallback('malformed-schema'));
+        const { [keyword]: _branches, ...siblings } = schema;
+        const list = schema[keyword].map(value => sameValue(value));
+        const structuralSibling = ['properties', 'items', 'prefixItems', 'additionalProperties'].some(name => own(siblings, name));
+        const composed = { type, list, ...(type === 'union' ? { mode: keyword } : {}) };
+        return finish(structuralSibling ? { type: 'intersect', list: [composed, sameValue(siblings)] } : composed);
+    }
+    if (Array.isArray(schema.type)) {
+        const { type: _types, ...constraints } = schema;
+        return finish({ type: 'union', list: schema.type.map(type => child({ ...constraints, type })) });
+    }
+    if (own(schema, 'const'))
+        return finish({ type: 'const', value: schema.const });
+    const type = typeof schema.type === 'string' ? schema.type : schema.properties ? 'object' : schema.items || schema.prefixItems ? 'array' : undefined;
+    if (type === 'object') {
+        const properties = record(schema.properties) ? schema.properties : {};
+        const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+        const object = Object.fromEntries(Object.entries(properties).map(([name, value]) => [name, { ...child(value, name), ...(required.has(name) ? { required: true } : {}) }]));
+        const additional = schema.additionalProperties === false ? false : child(schema.additionalProperties ?? true);
+        return finish(Object.keys(object).length === 0 && record(schema.additionalProperties)
+            ? { type: 'dict', inner: additional } : { type: 'object', object, additional });
+    }
+    if (type === 'array') {
+        const prefix = Array.isArray(schema.prefixItems) ? schema.prefixItems : Array.isArray(schema.items) ? schema.items : undefined;
+        return finish(prefix ? { type: 'tuple', list: prefix.map(value => child(value)), inner: schema.items === false || schema.additionalItems === false ? false : child(Array.isArray(schema.items) ? schema.additionalItems ?? true : schema.items ?? true) }
+            : { type: 'list', inner: child(schema.items ?? true) });
+    }
+    const inferred = type ?? (Array.isArray(schema.enum) && schema.enum.length ? (schema.enum[0] === null ? 'null' : typeof schema.enum[0]) : 'any');
+    return finish({ type: inferred === 'integer' ? 'number' : jsonTypes.has(inferred) ? inferred : 'any', ...(inferred === 'integer' ? { integer: true } : {}) });
+}
+const annotationKeys = new Set(['title', 'description', 'x-descriptionZh', 'x-i18n', 'default', 'readOnly', 'writeOnly', 'examples', 'deprecated', 'x-zhin-config', 'x-zhin-secret', 'key', 'hidden', 'component', 'options', 'effect', 'secret']);
+function annotate(result, schema, key) {
+    const output = { ...result };
+    if (record(schema['x-i18n']))
+        output['x-i18n'] = schema['x-i18n'];
+    for (const name of ['key', 'title', 'default', 'min', 'max', 'step', 'integer', 'pattern', 'minLength', 'maxLength', 'minItems', 'maxItems', 'minimum', 'maximum', 'multipleOf', 'uniqueItems', 'minProperties', 'maxProperties', 'exclusiveMinimum', 'exclusiveMaximum', 'readOnly', 'deprecated', 'format', 'unevaluatedProperties'])
+        if (own(schema, name))
+            output[name] = schema[name];
+    if (key !== undefined && output.key === undefined)
+        output.key = key;
+    const description = typeof schema['x-descriptionZh'] === 'string' ? schema['x-descriptionZh'] : schema.description;
+    if (typeof description === 'string')
+        output.description = description;
+    // Existing bilingual Host schemas already keep the English original beside x-descriptionZh.
+    if (typeof schema['x-descriptionZh'] === 'string' && typeof schema.description === 'string') {
+        const catalog = record(output['x-i18n']) ? output['x-i18n'] : {};
+        const english = record(catalog.en) ? catalog.en : {};
+        output['x-i18n'] = { ...catalog, en: { description: schema.description, ...english } };
+    }
+    if (typeof schema.required === 'boolean')
+        output.required = schema.required;
+    if (Array.isArray(schema.enum))
+        output.options = schema.enum.map(value => ({ label: String(value), value }));
+    for (const name of ['hidden', 'component', 'options', 'effect'])
+        if (schema[name] !== undefined)
+            output[name] = schema[name];
+    const metadata = record(schema['x-zhin-config']) ? schema['x-zhin-config'] : {};
+    for (const name of ['hidden', 'component', 'options', 'effect'])
+        if (metadata[name] !== undefined)
+            output[name] = metadata[name];
+    if (output.secret !== true && typeof schema.secret === 'boolean')
+        output.secret = schema.secret;
+    if (output.secret === true || isSecretConfigSchema(schema)) {
+        output.secret = true;
+        if (output.component !== 'textarea')
+            output.component = 'password';
+    }
+    const bounds = schema.type === 'string' ? ['minLength', 'maxLength'] : schema.type === 'array' ? ['minItems', 'maxItems'] : ['minimum', 'maximum'];
+    if (typeof schema[bounds[0]] === 'number')
+        output.min = schema[bounds[0]];
+    if (typeof schema[bounds[1]] === 'number')
+        output.max = schema[bounds[1]];
+    if (typeof schema.multipleOf === 'number')
+        output.step = schema.multipleOf;
+    return output;
+}
+export function isConsoleSchemaJson(schema) {
+    if (schema.object !== undefined || schema.list !== undefined || schema.inner !== undefined || schema.additional !== undefined)
+        return true;
+    return typeof schema.type === 'string' && (['dict', 'union', 'tuple', 'intersect', 'const', 'any', 'date', 'regexp', 'list'].includes(schema.type)
+        || ['string', 'number', 'boolean', 'null'].includes(schema.type) && (schema.key !== undefined || typeof schema.required === 'boolean' || ['hidden', 'component', 'options', 'effect', 'secret'].some(name => own(schema, name))) && !['const', 'anyOf', 'oneOf', 'allOf', '$ref'].some(name => own(schema, name)));
+}
+/** Validation-only branches do not own a second editable copy of the same value. */
+function validationOnly(schema, properties) {
+    if (['$ref', '$dynamicRef', 'default', 'items', 'prefixItems', 'additionalProperties', 'patternProperties', 'contains', 'dependentSchemas'].some(name => own(schema, name)))
+        return false;
+    if (Array.isArray(schema.required) && schema.required.some(name => !properties.has(String(name))))
+        return false;
+    if (record(schema.properties)) {
+        for (const [name, definition] of Object.entries(schema.properties)) {
+            if (!properties.has(name) || !record(definition) || !validationOnly(definition, new Set()))
+                return false;
+        }
+    }
+    for (const name of ['if', 'then', 'else', 'not'])
+        if (own(schema, name) && (!record(schema[name]) || !validationOnly(schema[name], properties)))
+            return false;
+    for (const name of ['allOf', 'anyOf', 'oneOf'])
+        if (Array.isArray(schema[name]) && !schema[name].every(value => record(value) && validationOnly(value, properties)))
+            return false;
+    return true;
+}

package/lib/config/environment-files.d.ts

@@ -0,0 +1,3 @@
+export declare function readEnvFile(projectRoot: string, filename: string): Promise<string>;
+/** Locked, atomic replacement that keeps the file mode (`0600` when new); ADR 0057 §4. */
+export declare function writeEnvFile(projectRoot: string, filename: string, content: string): Promise<void>;

package/lib/config/environment-files.js

@@ -0,0 +1,14 @@
+import { join } from 'node:path';
+import { readDotenvFile, writeDotenvFile } from '@zhin.js/runtime';
+const ENV_FILES = new Set(['.env', '.env.development', '.env.production']);
+export async function readEnvFile(projectRoot, filename) {
+    if (!ENV_FILES.has(filename))
+        throw new Error(`Invalid env file: ${filename}`);
+    return readDotenvFile(join(projectRoot, filename));
+}
+/** Locked, atomic replacement that keeps the file mode (`0600` when new); ADR 0057 §4. */
+export async function writeEnvFile(projectRoot, filename, content) {
+    if (!ENV_FILES.has(filename))
+        throw new Error(`Invalid env file: ${filename}`);
+    await writeDotenvFile(join(projectRoot, filename), content);
+}

package/lib/config/literal-secrets.d.ts

@@ -0,0 +1,34 @@
+import { type LiteralConfigSecret } from '@zhin.js/runtime';
+import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
+/**
+ * Secret paths holding literals in `document`, using the Host schema, the root `schema.json`
+ * and each declared instance's `schema.json` (annotations), plus the field-name fallback.
+ * Plugins whose schema is only inline (`definePlugin({ config })`) use the name fallback here.
+ */
+export declare function findProjectLiteralSecrets(projectRoot: string, document: RuntimeConfigDocument): Promise<readonly LiteralConfigSecret[]>;
+/** `ZHIN_<PATH_UPPER_SNAKE>`: `http.token` → `ZHIN_HTTP_TOKEN`, `qq.endpoints[0].appSecret` → `ZHIN_QQ_ENDPOINTS_0_APP_SECRET`. */
+export declare function literalSecretEnvironmentName(path: readonly string[]): string;
+export interface LiteralSecretMove {
+    readonly path: readonly string[];
+    readonly variable: string;
+    /** The variable already held this exact value; `.env` was not changed for it. */
+    readonly reused: boolean;
+}
+export interface LiteralSecretSkip {
+    readonly path: readonly string[];
+    readonly reason: string;
+}
+export interface LiteralSecretFixResult {
+    readonly moved: readonly LiteralSecretMove[];
+    readonly skipped: readonly LiteralSecretSkip[];
+}
+/**
+ * Moves every literal secret of `configFile` into `<projectRoot>/.env`.
+ *
+ * Order: `.env` first (locked, atomic; a variable that already holds the same value is reused,
+ * a name taken by another value gets `_2`, `_3`, …), then the config file through
+ * ConfigFileDocument (revision check, lock, atomic). If the config changed in between, the
+ * write is refused with a conflict and nothing in the config changes; the next run reuses the
+ * variables already written, so the operation is idempotent.
+ */
+export declare function moveLiteralSecretsToEnv(projectRoot: string, configFile: string): Promise<LiteralSecretFixResult>;

package/lib/config/literal-secrets.js

@@ -0,0 +1,136 @@
+/**
+ * ADR 0057 §4: literal secrets in the YAML/JSON config move to `.env`.
+ * `zhin doctor` reports them; `zhin doctor --fix` writes each literal into `.env` as
+ * `ZHIN_<PATH>` and replaces the config value with `${ZHIN_<PATH>}`.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseDotenv } from 'dotenv';
+import { HOST_CONFIG_SCHEMA, createConfigDocument, findLiteralConfigSecrets, readApplicationPluginDeclaration, updateDotenvFile, } from '@zhin.js/runtime';
+import { PluginSchemaCatalog } from './plugin-schema-catalog.js';
+/**
+ * Secret paths holding literals in `document`, using the Host schema, the root `schema.json`
+ * and each declared instance's `schema.json` (annotations), plus the field-name fallback.
+ * Plugins whose schema is only inline (`definePlugin({ config })`) use the name fallback here.
+ */
+export async function findProjectLiteralSecrets(projectRoot, document) {
+    let instanceKeys = [];
+    try {
+        instanceKeys = readApplicationPluginDeclaration(document).instances.map(item => item.instanceKey);
+    }
+    catch { /* Invalid declarations are reported elsewhere; still scan with the name fallback. */ }
+    const schemas = await new PluginSchemaCatalog(projectRoot).readJsonMany(['plugin', ...instanceKeys], document);
+    const plugins = [];
+    for (const [key, schema] of schemas) {
+        if (schema && !(schema instanceof Error))
+            plugins.push([[key], schema]);
+    }
+    return findLiteralConfigSecrets(document, { host: HOST_CONFIG_SCHEMA, plugins });
+}
+/** `ZHIN_<PATH_UPPER_SNAKE>`: `http.token` → `ZHIN_HTTP_TOKEN`, `qq.endpoints[0].appSecret` → `ZHIN_QQ_ENDPOINTS_0_APP_SECRET`. */
+export function literalSecretEnvironmentName(path) {
+    const body = path
+        .map(segment => segment.replace(/([a-z0-9])([A-Z])/gu, '$1_$2'))
+        .join('_')
+        .replace(/[^A-Za-z0-9]+/gu, '_')
+        .replace(/^_+|_+$/gu, '')
+        .toUpperCase();
+    return `ZHIN_${body || 'SECRET'}`;
+}
+/**
+ * Moves every literal secret of `configFile` into `<projectRoot>/.env`.
+ *
+ * Order: `.env` first (locked, atomic; a variable that already holds the same value is reused,
+ * a name taken by another value gets `_2`, `_3`, …), then the config file through
+ * ConfigFileDocument (revision check, lock, atomic). If the config changed in between, the
+ * write is refused with a conflict and nothing in the config changes; the next run reuses the
+ * variables already written, so the operation is idempotent.
+ */
+export async function moveLiteralSecretsToEnv(projectRoot, configFile) {
+    const config = createConfigDocument(configFile);
+    const snapshot = await config.read();
+    const secrets = await findProjectLiteralSecrets(projectRoot, snapshot.document);
+    if (secrets.length === 0)
+        return Object.freeze({ moved: Object.freeze([]), skipped: Object.freeze([]) });
+    // `.env.<environment>` overrides `.env`: a name used there with another value is taken.
+    const overlays = await Promise.all(['.env.development', '.env.production'].map(name => readOptional(join(projectRoot, name))));
+    const shadowing = overlays.map(source => parseDotenv(source));
+    const moved = [];
+    const skipped = [];
+    await updateDotenvFile(join(projectRoot, '.env'), current => {
+        moved.length = 0;
+        skipped.length = 0;
+        const existing = { ...parseDotenv(current) };
+        const lines = [];
+        for (const secret of secrets) {
+            const value = readPath(snapshot.document, secret.path);
+            if (typeof value !== 'string')
+                continue;
+            const line = (name) => dotenvLine(name, value);
+            if (!line('ZHIN_PROBE')) {
+                skipped.push(Object.freeze({ path: secret.path, reason: '值含换行或无法安全写入 .env，请手动迁移' }));
+                continue;
+            }
+            const base = literalSecretEnvironmentName(secret.path);
+            let variable = base;
+            for (let suffix = 2;; suffix += 1) {
+                const taken = existing[variable] !== undefined && existing[variable] !== value
+                    || shadowing.some(layer => layer[variable] !== undefined && layer[variable] !== value);
+                if (!taken)
+                    break;
+                variable = `${base}_${suffix}`;
+            }
+            const reused = existing[variable] === value;
+            if (!reused) {
+                lines.push(line(variable));
+                existing[variable] = value;
+            }
+            moved.push(Object.freeze({ path: secret.path, variable, reused }));
+        }
+        if (lines.length === 0)
+            return undefined;
+        const separator = current === '' || current.endsWith('\n') ? '' : '\n';
+        return `${current}${separator}${current.trim() ? '\n' : ''}# zhin doctor --fix：从 ${configFileLabel(configFile)} 移入的密钥（ADR 0057）\n${lines.join('\n')}\n`;
+    });
+    if (moved.length) {
+        const patches = moved.map(item => ({ op: 'set', path: item.path, value: `\${${item.variable}}` }));
+        const prepared = await config.prepare(snapshot, patches);
+        await prepared.commit();
+    }
+    return Object.freeze({ moved: Object.freeze(moved), skipped: Object.freeze(skipped) });
+}
+/** A `NAME=value` dotenv line that parses back to exactly `value`, or undefined when none does. */
+function dotenvLine(name, value) {
+    if (/[\r\n]/u.test(value))
+        return undefined;
+    for (const quote of ["'", '`', '"']) {
+        if (value.includes(quote))
+            continue;
+        const line = `${name}=${quote}${value}${quote}`;
+        if (parseDotenv(line)[name] === value)
+            return line;
+    }
+    return undefined;
+}
+function readPath(document, path) {
+    let current = document;
+    for (const segment of path) {
+        if (!current || typeof current !== 'object' || !Object.hasOwn(current, segment))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function configFileLabel(file) {
+    return file.split(/[\\/]/u).pop() ?? file;
+}
+async function readOptional(file) {
+    try {
+        return await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+}

package/lib/config/plugin-package-map.d.ts

@@ -0,0 +1,2 @@
+/** Reads only the application's instance declaration authority. */
+export declare function readPluginPackageMap(projectRoot: string, currentDocument?: Readonly<Record<string, unknown>>): Promise<ReadonlyMap<string, string>>;

package/lib/config/plugin-package-map.js

@@ -0,0 +1,14 @@
+import { join } from 'node:path';
+import { createConfigDocument, readApplicationPluginDeclaration } from '@zhin.js/runtime';
+import { findConfigFile } from '../project/config-file.js';
+/** Reads only the application's instance declaration authority. */
+export async function readPluginPackageMap(projectRoot, currentDocument) {
+    let document = currentDocument;
+    if (!document) {
+        const file = findConfigFile(projectRoot);
+        if (!file)
+            throw new Error('Missing configVersion: 2 configuration; run zhin setup');
+        document = (await createConfigDocument(join(projectRoot, file)).read()).document;
+    }
+    return new Map(readApplicationPluginDeclaration(document).instances.map(item => [item.instanceKey, item.package]));
+}

package/lib/config/plugin-schema-catalog.d.ts

@@ -0,0 +1,22 @@
+import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
+/** Resolves schemas using the same package roots and declarations as Runtime. */
+export declare class PluginSchemaCatalog {
+    #private;
+    constructor(projectRoot: string, declarations?: () => ReadonlyMap<string, Readonly<Record<string, unknown>>> | Promise<ReadonlyMap<string, Readonly<Record<string, unknown>>>>);
+    read(pluginName?: string, document?: RuntimeConfigDocument): Promise<unknown>;
+    readJson(pluginName: string, document?: RuntimeConfigDocument): Promise<Readonly<Record<string, unknown>> | null>;
+    /**
+     * Raw JSON schemas for several keys sharing one resolver and one declaration read.
+     * A key whose schema cannot be read maps to its `Error`, so callers can fail closed per key.
+     */
+    readJsonMany(keys: Iterable<string>, document?: RuntimeConfigDocument): Promise<ReadonlyMap<string, Readonly<Record<string, unknown>> | null | Error>>;
+    /**
+     * Form schema of an installed plugin package that no instance declares yet (ADR 0053 §2 step 4):
+     * the package must be a production dependency (`dependencies` / `optionalDependencies`) of the
+     * project and a Plugin package. Returns the declared-instance form shape plus `declared: false`,
+     * `null` when such a package ships no `schema.json`, and `undefined` when `packageName` is not
+     * such a package (declared, not a dependency, not installed, not a Plugin, or not a package name).
+     */
+    readUndeclared(packageName: string, currentDocument?: RuntimeConfigDocument): Promise<Readonly<Record<string, unknown>> | null | undefined>;
+    readAll(keys: Iterable<string>, document?: RuntimeConfigDocument): Promise<Record<string, unknown>>;
+}