@zhin.js/gateway 0.0.0-stage → 1.1.1

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,222 @@
+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', ...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', '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 || schema.writeOnly === true || schema.secret === true || metadata.secret === true) {
+        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,2 @@
+export declare function readEnvFile(projectRoot: string, filename: string): Promise<string>;
+export declare function writeEnvFile(projectRoot: string, filename: string, content: string): Promise<void>;

package/lib/config/environment-files.js

@@ -0,0 +1,21 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+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}`);
+    const file = join(projectRoot, filename);
+    try {
+        return await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+}
+export async function writeEnvFile(projectRoot, filename, content) {
+    if (!ENV_FILES.has(filename))
+        throw new Error(`Invalid env file: ${filename}`);
+    await writeFile(join(projectRoot, filename), content, 'utf8');
+}

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

package/lib/config/plugin-schema-catalog.js

@@ -0,0 +1,262 @@
+import { readFile, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createConfigDocument, HOST_CONFIG_KEYS, readApplicationPluginDeclaration, HOST_CONFIG_SCHEMA, ManifestValidationError, NodePackageResolver, PackageResolutionError, } from '@zhin.js/runtime';
+import { findConfigFile } from '../project/config-file.js';
+import { isConsoleSchemaJson, jsonSchemaToConsoleSchema } from './console-schema.js';
+const HOST_CONFIG_KEY_SET = new Set(HOST_CONFIG_KEYS);
+/** Resolves schemas using the same package roots and declarations as Runtime. */
+export class PluginSchemaCatalog {
+    #projectRoot;
+    #declarations;
+    constructor(projectRoot, declarations) {
+        this.#projectRoot = projectRoot;
+        this.#declarations = declarations;
+    }
+    async read(pluginName, document) {
+        if (!pluginName)
+            return null;
+        return this.#read(pluginName, () => NodePackageResolver.create(this.#projectRoot), await this.#declarations?.(), false, document);
+    }
+    async readJson(pluginName, document) {
+        return (await this.#read(pluginName, () => NodePackageResolver.create(this.#projectRoot), await this.#declarations?.(), true, document));
+    }
+    /**
+     * 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.
+     */
+    async readJsonMany(keys, document) {
+        const list = [...keys];
+        let declarations;
+        try {
+            declarations = await this.#declarations?.();
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            return new Map(list.map(key => [key, failure]));
+        }
+        let resolver;
+        return new Map(await Promise.all(list.map(async (key) => {
+            try {
+                const schema = await this.#read(key, () => resolver ??= NodePackageResolver.create(this.#projectRoot), declarations, true, document);
+                return [key, schema];
+            }
+            catch (error) {
+                return [key, error instanceof Error ? error : new Error(String(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).
+     */
+    async readUndeclared(packageName, currentDocument) {
+        if (HOST_CONFIG_KEY_SET.has(packageName) || packageName === 'root'
+            || !/^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/u.test(packageName))
+            return undefined;
+        let target;
+        try {
+            const packages = await NodePackageResolver.create(this.#projectRoot);
+            const root = await packages.root(this.#projectRoot);
+            const file = findConfigFile(this.#projectRoot);
+            const document = currentDocument ?? (file ? (await createConfigDocument(join(this.#projectRoot, file)).read()).document : {});
+            const declaration = readApplicationPluginDeclaration(document);
+            if (declaration.version !== 2)
+                return undefined;
+            if (declaration.instances.some(item => item.instanceKey === packageName || item.package === packageName))
+                return undefined;
+            const manifest = root.packageJson;
+            if (!Object.hasOwn(manifest.dependencies ?? {}, packageName)
+                && !Object.hasOwn(manifest.optionalDependencies ?? {}, packageName))
+                return undefined;
+            try {
+                target = await resolveReference(packages, root, { package: packageName, instanceKey: packageName });
+            }
+            catch (error) {
+                // A dependency without a Zhin manifest is a plain library, not an undeclared plugin.
+                if (error instanceof ManifestValidationError)
+                    return undefined;
+                throw error;
+            }
+            // A declaration through another reference (local path, alias) that resolves to the same
+            // package root already declares this package.
+            for (const item of declaration.instances) {
+                const declared = await resolveReference(packages, root, item).catch(() => undefined);
+                if (declared && target && declared.root === target.root)
+                    return undefined;
+            }
+        }
+        catch (error) {
+            throw new Error(`Cannot resolve schema for ${packageName}: invalid or unavailable Plugin manifest`, { cause: error });
+        }
+        if (!target)
+            return undefined;
+        const schema = (await this.#declarations?.())?.get(target.root) ?? await readOwnSchema(target.root, packageName, true);
+        if (!schema)
+            return null;
+        assertSchemaStructure(schema, `config declaration for ${packageName}`);
+        const form = jsonSchemaToConsoleSchema(schema);
+        return form ? Object.freeze({ ...form, declared: false }) : null;
+    }
+    async readAll(keys, document) {
+        let resolver;
+        const declarations = await this.#declarations?.();
+        if (!document) {
+            const file = findConfigFile(this.#projectRoot);
+            if (file)
+                document = (await createConfigDocument(join(this.#projectRoot, file)).read()).document;
+        }
+        const entries = await Promise.all([...keys].map(async (key) => [
+            key,
+            await this.#read(key, () => resolver ??= NodePackageResolver.create(this.#projectRoot), declarations, false, document),
+        ]));
+        return Object.fromEntries(entries.filter((entry) => entry[1] != null));
+    }
+    async #read(pluginName, resolver, declarations, rawSchema = false, currentDocument) {
+        if (HOST_CONFIG_KEY_SET.has(pluginName)) {
+            // Host sections share the Runtime schema and its local definition scope.
+            // This is only a display projection; Runtime remains the config validator.
+            const raw = pluginName === 'plugin'
+                ? declarations?.get(await realpath(this.#projectRoot)) ?? await readOwnSchema(this.#projectRoot, 'plugin', !rawSchema)
+                : HOST_CONFIG_SCHEMA.properties[pluginName];
+            if (rawSchema)
+                return raw && pluginName !== 'plugin'
+                    ? { ...raw, $defs: HOST_CONFIG_SCHEMA.$defs } : raw ?? null;
+            if (raw && pluginName === 'plugin')
+                assertSchemaStructure(raw, 'config declaration for plugin');
+            return jsonSchemaToConsoleSchema(raw && pluginName !== 'plugin' ? { ...raw, $defs: HOST_CONFIG_SCHEMA.$defs } : raw);
+        }
+        if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/u.test(pluginName)
+            && !pluginName.split('/').every((key) => /^[a-z0-9][a-z0-9-]*$/u.test(key))) {
+            return null;
+        }
+        let target;
+        try {
+            const packages = await resolver();
+            const root = await packages.root(this.#projectRoot);
+            const file = findConfigFile(this.#projectRoot);
+            const document = currentDocument ?? (file ? (await createConfigDocument(join(this.#projectRoot, file)).read()).document : {});
+            const declaration = readApplicationPluginDeclaration(document);
+            if (declaration.version === 2) {
+                const name = pluginName.startsWith('root/') ? pluginName.slice(5) : pluginName;
+                const exact = declaration.instances.find(item => item.instanceKey === name);
+                const matches = exact ? [exact] : declaration.instances.filter(item => item.package === pluginName);
+                if (matches.length > 1)
+                    throw new Error('此包存在多个插件实例，请使用精确 instanceKey');
+                if (matches[0])
+                    target = await resolveReference(packages, root, matches[0]);
+                else if (pluginName === 'root')
+                    target = root;
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('多个插件实例'))
+                throw error;
+            throw new Error(`Cannot resolve schema for ${pluginName}: invalid or unavailable Plugin manifest`, { cause: error });
+        }
+        if (!target)
+            return null;
+        const schema = declarations?.get(target.root) ?? await readOwnSchema(target.root, pluginName, !rawSchema);
+        if (rawSchema)
+            return schema;
+        if (schema)
+            assertSchemaStructure(schema, `config declaration for ${pluginName}`);
+        return jsonSchemaToConsoleSchema(schema);
+    }
+}
+async function resolveReference(resolver, owner, reference) {
+    try {
+        const pkg = await resolver.resolve(reference.package, owner);
+        return pkg.packageJson.zhin.type === 'plugin' ? pkg : undefined;
+    }
+    catch (error) {
+        if (error instanceof PackageResolutionError)
+            return undefined;
+        throw error;
+    }
+}
+/** Missing schemas have no form; malformed schemas must not masquerade as missing. */
+async function readOwnSchema(root, name, forForm = true) {
+    let text;
+    try {
+        text = await readFile(join(root, 'schema.json'), 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return null;
+        throw new Error(`Cannot read schema.json for ${name}`, { cause: error });
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Invalid JSON in schema.json for ${name}`);
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`schema.json for ${name} must contain a JSON Schema object`);
+    }
+    const schema = value;
+    if (schema.type !== undefined && schema.type !== 'object') {
+        throw new Error(`schema.json for ${name} root schema type must be object`);
+    }
+    if (schema.properties !== undefined
+        && (!schema.properties || typeof schema.properties !== 'object' || Array.isArray(schema.properties))) {
+        throw new Error(`schema.json for ${name} properties must be an object`);
+    }
+    if (forForm)
+        assertSchemaStructure(schema, `schema.json for ${name}`);
+    return schema;
+}
+/** Reject malformed child definitions before the form converter can silently omit them. */
+function assertSchemaStructure(value, location) {
+    if (typeof value === 'boolean')
+        return;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${location} must contain a supported schema object`);
+    }
+    const schema = value;
+    if (schema.$ref !== undefined && typeof schema.$ref !== 'string')
+        throw new Error(`${location}.$ref must be a string`);
+    if (schema.type !== undefined && !(typeof schema.type === 'string' || Array.isArray(schema.type) && schema.type.every(type => typeof type === 'string')))
+        throw new Error(`${location}.type must be a string or string array`);
+    if (schema.required !== undefined) {
+        const nativeFlag = typeof schema.required === 'boolean' && isConsoleSchemaJson(schema);
+        if (!nativeFlag && (!Array.isArray(schema.required)
+            || !schema.required.every((key) => typeof key === 'string')
+            || new Set(schema.required).size !== schema.required.length)) {
+            throw new Error(`${location}.required must be a unique string array or a native Schema boolean`);
+        }
+    }
+    for (const key of ['properties', '$defs', 'definitions', 'object', 'patternProperties', 'dependentSchemas']) {
+        const children = schema[key];
+        if (children === undefined)
+            continue;
+        if (!children || typeof children !== 'object' || Array.isArray(children)) {
+            throw new Error(`${location}.${key} must be an object`);
+        }
+        for (const [name, child] of Object.entries(children)) {
+            assertSchemaStructure(child, `${location}.${key}.${name}`);
+        }
+    }
+    for (const key of ['items', 'inner', 'additionalProperties', 'additional', 'additionalItems', 'contains', 'not', 'if', 'then', 'else']) {
+        const child = schema[key];
+        if (child === undefined || (key === 'additionalProperties' && typeof child === 'boolean'))
+            continue;
+        if (key === 'items' && Array.isArray(child)) {
+            child.forEach((item, index) => assertSchemaStructure(item, `${location}.items[${index}]`));
+            continue;
+        }
+        assertSchemaStructure(child, `${location}.${key}`);
+    }
+    for (const key of ['list', 'anyOf', 'oneOf', 'allOf', 'prefixItems']) {
+        const children = schema[key];
+        if (children === undefined)
+            continue;
+        if (!Array.isArray(children) || ['anyOf', 'oneOf', 'allOf'].includes(key) && children.length === 0)
+            throw new Error(`${location}.${key} must be a non-empty schema array`);
+        children.forEach((child, index) => assertSchemaStructure(child, `${location}.${key}[${index}]`));
+    }
+}

package/lib/config.d.ts

@@ -0,0 +1,12 @@
+/** `@zhin.js/gateway/config` — raw project configuration and `.env` access. */
+export * from './config/ai-config-loader.js';
+export * from './config/configuration.js';
+export * from './config/configuration-chat-policy.js';
+export * from './config/configuration-patch.js';
+export * from './config/configuration-path.js';
+export * from './config/configuration-projection.js';
+export * from './config/configuration-redaction.js';
+export * from './config/console-schema.js';
+export * from './config/environment-files.js';
+export * from './config/plugin-package-map.js';
+export * from './config/plugin-schema-catalog.js';

package/lib/config.js

@@ -0,0 +1,12 @@
+/** `@zhin.js/gateway/config` — raw project configuration and `.env` access. */
+export * from './config/ai-config-loader.js';
+export * from './config/configuration.js';
+export * from './config/configuration-chat-policy.js';
+export * from './config/configuration-patch.js';
+export * from './config/configuration-path.js';
+export * from './config/configuration-projection.js';
+export * from './config/configuration-redaction.js';
+export * from './config/console-schema.js';
+export * from './config/environment-files.js';
+export * from './config/plugin-package-map.js';
+export * from './config/plugin-schema-catalog.js';

package/lib/database/config.d.ts

@@ -0,0 +1,22 @@
+export type ProjectDatabaseConfig = {
+    readonly dialect: string;
+} & Readonly<Record<string, unknown>>;
+/** Project-relative default when no `database` block is configured. */
+export declare const DEFAULT_PROJECT_DATABASE_FILE: string;
+/** Validates an expanded `database` block (port of `normalizeDatabaseHostConfig`). */
+export declare function normalizeProjectDatabaseConfig(input: ProjectDatabaseConfig): ProjectDatabaseConfig;
+/**
+ * Resolves the expanded root config document's `database` block. A relative SQLite file is
+ * anchored at the project root (the instance runs with the project root as cwd, so both
+ * processes open the same file).
+ */
+export declare function resolveProjectDatabaseConfig(projectRoot: string, document: unknown): Promise<ProjectDatabaseConfig>;
+/**
+ * The root config document with `${…}` expanded against process env and the project `.env`
+ * layers of `environment` (missing variables become empty, as in the instance). Only the gateway's
+ * own blocks are read from it (`database`, `console.terminal`): plugin declarations are not
+ * validated here, so a config the instance rejects still leaves the Console reachable.
+ */
+export declare function loadExpandedProjectConfig(projectRoot: string, environment?: string): Promise<Readonly<Record<string, unknown>>>;
+/** {@link resolveProjectDatabaseConfig} over {@link loadExpandedProjectConfig}. */
+export declare function loadProjectDatabaseConfig(projectRoot: string, environment?: string): Promise<ProjectDatabaseConfig>;