@dokebi/cli 0.4.2 → 0.4.27

package/dist/option-fixes.js

@@ -0,0 +1,130 @@
+// D-0153: the `fix` of an options error names the commands that repair it. A key the plugin does
+// not know (JSON Schema `additionalProperties`) is removed with `npx dokebi config unset`; a key
+// that moved to another plugin (MOVED_OPTIONS, kept here) says where it went and how to carry its
+// settings over. Fixes name keys and commands, never values.
+/** Options that moved to another plugin, newest last. */
+export const MOVED_OPTIONS = Object.freeze([
+    Object.freeze({
+        plugin: 'dokebi-web',
+        path: Object.freeze(['files']),
+        to: 'dokebi-static.mounts',
+        package: '@dokebi/static',
+        decision: 'D-0147',
+        set: 'npx dokebi config set dokebi-static.mounts.<name>.prefix=<prefix> dokebi-static.mounts.<name>.root=<folder> for each mount',
+    }),
+]);
+const SEGMENT = /^[A-Za-z0-9_-]{1,64}$/;
+/** The option path (segments) an issue points at, with the unknown key for additionalProperties. */
+function issuePath(issue) {
+    const parts = issue.instancePath
+        .split('/')
+        .slice(1)
+        .map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'));
+    return issue.keyword === 'additionalProperties' && issue.additionalProperty !== undefined
+        ? [...parts, issue.additionalProperty]
+        : parts;
+}
+/** `<id>.<path>` of every key the plugin does not know, when the path can be unset. */
+export function unknownOptionPaths(id, issues) {
+    const paths = [];
+    let unnamed = false;
+    for (const issue of issues) {
+        if (issue.keyword !== 'additionalProperties')
+            continue;
+        const path = issuePath(issue);
+        if (issue.additionalProperty === undefined || !path.every((part) => SEGMENT.test(part))) {
+            unnamed = true;
+            continue;
+        }
+        const where = [id, ...path].join('.');
+        if (!paths.includes(where))
+            paths.push(where);
+    }
+    return { paths, unnamed };
+}
+/** The moved option a path is, or is inside of. */
+export function movedOption(id, path) {
+    return MOVED_OPTIONS.find((moved) => moved.plugin === id &&
+        moved.path.length <= path.length &&
+        moved.path.every((part, index) => path[index] === part));
+}
+/**
+ * The fix of INVALID_PLUGIN_OPTIONS for plugin `id`: the moved keys first (where they went, then
+ * show, unset, add, set), then `npx dokebi config unset` for the other unknown keys, then
+ * `fallback` (how to correct the remaining issues), which is the whole fix when no key is unknown.
+ */
+export function optionsFix(id, issues, fallback, 
+/** The section of dokebi.yaml the commands name (options.logging for the logger host). */
+section = id, 
+/** The plugin's options schema: the fix then says what the refused field expects. */
+schema) {
+    const expected = expectedShape(schema, issues, section);
+    if (expected)
+        fallback = `${fallback}; ${expected}`;
+    const { paths, unnamed } = unknownOptionPaths(section, issues);
+    const parts = [];
+    const moved = new Map();
+    const other = [];
+    for (const where of paths) {
+        const match = movedOption(id, where.split('.').slice(1));
+        if (match)
+            moved.set(match, [match.plugin, ...match.path].join('.'));
+        else
+            other.push(where);
+    }
+    for (const [match, from] of moved)
+        parts.push(`options.${from} moved to options.${match.to} (${match.decision}): npx dokebi config show ${from} to see what it held, npx dokebi config unset ${from}, npx dokebi add ${match.package} when it is not installed, then ${match.set}`);
+    if (other.length)
+        parts.push(`remove what ${id} does not know: npx dokebi config unset ${other.join(' ')} (npx dokebi plugins info ${id} --json lists its option keys)`);
+    const rest = issues.some((issue) => issue.keyword !== 'additionalProperties') || unnamed;
+    if (!parts.length)
+        return fallback;
+    return rest ? `${parts.join('; ')}; then ${fallback}` : parts.join('; ');
+}
+const node = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : undefined;
+/** The schema of the field at an issue's instance path (properties, additionalProperties, items). */
+function fieldSchema(schema, issue) {
+    let at = node(schema);
+    for (const part of issue.instancePath.split('/').slice(1)) {
+        if (!at)
+            return undefined;
+        const key = part.replaceAll('~1', '/').replaceAll('~0', '~');
+        const properties = node(at.properties);
+        at =
+            properties && Object.hasOwn(properties, key)
+                ? node(properties[key])
+                : /^[0-9]+$/.test(key) && node(at.items)
+                    ? node(at.items)
+                    : node(at.additionalProperties);
+    }
+    return at;
+}
+/**
+ * What the first refused field expects, from the schema only (community request D3: `config set`
+ * said `(pattern)` and nothing about the shape, so the value could not be corrected). Never the
+ * value from the configuration: the description, the allowed values, the type or the bounds.
+ */
+function expectedShape(schema, issues, section) {
+    const issue = issues.find((item) => item.keyword !== 'additionalProperties' && item.keyword !== 'required');
+    if (!issue)
+        return undefined;
+    const field = fieldSchema(schema, issue);
+    if (!field)
+        return undefined;
+    const said = [];
+    if (typeof field.description === 'string')
+        said.push(field.description);
+    if (Array.isArray(field.enum))
+        said.push(`one of ${field.enum.map((value) => JSON.stringify(value)).join(', ')}`);
+    else if (field.type !== undefined && issue.keyword === 'type')
+        said.push(`type ${[field.type].flat().join(' or ')}`);
+    for (const bound of ['minimum', 'maximum', 'minLength', 'maxLength', 'minItems', 'maxItems'])
+        if (issue.keyword === bound && typeof field[bound] === 'number')
+            said.push(`${bound} ${field[bound]}`);
+    if (!said.length)
+        return undefined;
+    const where = `options.${section}${issue.instancePath.replaceAll('/', '.')}`;
+    return `${where} expects: ${said.join('; ')}`;
+}

package/dist/output.d.ts

@@ -1,3 +1,3 @@
-export declare const CLI_VERSION = "0.4.2";
+export declare const CLI_VERSION = "0.4.27";
 export declare function envelope(command: string, result: unknown, ok?: boolean): object;
 export declare function failure(command: string, error: unknown, mutationStarted: boolean): object;

package/dist/output.js

@@ -1,12 +1,12 @@
 import { CliError } from './errors.js';
-export const CLI_VERSION = '0.4.2';
+export const CLI_VERSION = '0.4.27';
 export function envelope(command, result, ok = true) {
     return { schemaVersion: 1, cliVersion: CLI_VERSION, command, ok, result, error: null };
 }
 export function failure(command, error, mutationStarted) {
     const code = error instanceof CliError ? error.code : 'INTERNAL_ERROR';
     // npm failing in the staging folder never touched the project (D-0065, AI-M01).
-    const staged = code === 'NPM_FAILED' &&
+    const staged = (code === 'NPM_FAILED' || code === 'REGISTRY_MISMATCH') &&
         error instanceof CliError &&
         error.details?.stage === 'staging';
     const phase = (error instanceof CliError ? error.phase : undefined) ??
@@ -17,9 +17,9 @@ export function failure(command, error, mutationStarted) {
                 : code === 'USAGE'
                     ? 'arguments'
                     : 'unknown');
-    // An error of the arguments phase is raised before anything is written (or before a
-    // transaction commits): the project is untouched.
-    const mutation = !mutationStarted || staged || phase === 'arguments'
+    // An error of the arguments or plan phase is raised before anything is written (or before a
+    // transaction commits): the project is untouched (D-0116).
+    const mutation = !mutationStarted || staged || phase === 'arguments' || phase === 'plan'
         ? 'none'
         : code === 'COMMIT_FAILED'
             ? 'rolled-back'

package/dist/plugin-lifecycle.d.ts

@@ -14,8 +14,14 @@ export interface LifecyclePlan extends Omit<InstallPlan, 'configDefaults'> {
     requires: string[];
     configChanges: ConfigChange[];
     /**
-     * planInstall only (D-0073): environment variables that must hold a secret. The CLI writes a
-     * generated value into the project's .env when neither the environment nor .env has one.
+     * planInstall only (D-0073 addendum 2): option paths inside the plugin's own section that must
+     * hold a secret. `add` writes a generated value there in dokebi.yaml unless one is there.
+     */
+    configSecrets: string[][];
+    /**
+     * planInstall only, deprecated (D-0073 §2, removed in 0.5): environment variables that must
+     * hold a secret. The CLI appends a generated value to the project's .env when neither the
+     * environment nor .env has one.
      */
     envSecrets: string[];
 }
@@ -41,10 +47,36 @@ export interface LifecycleInput {
 }
 /** An environment variable name a plan may ask a generated secret for. */
 export declare const ENV_NAME: RegExp;
+/**
+ * Keys a planInstall result may have. Install modules get them as `planKeys` in their context, so
+ * a plugin can tell whether this CLI takes `configSecrets` (0.4.3 and later) or only `envSecrets`.
+ */
+export declare const INSTALL_PLAN_KEYS: readonly string[];
 export declare function optionsOf(options: Record<string, unknown>, id: string): Record<string, unknown>;
 export declare function optionPath(value: unknown): string[];
 /** Static `dokebi.install` merged with the module's planInstall or planUpgrade result. */
 export declare function planLifecycle(input: LifecycleInput, phase: 'planInstall' | 'planUpgrade', extra?: Record<string, unknown>): Promise<LifecyclePlan>;
+/** One issue of a plugin's own option rules, shaped like the schema validator's (D-0162). */
+export interface PluginOptionIssue {
+    readonly instancePath: string;
+    readonly keyword: string;
+    readonly message: string;
+}
+/** D-0162: one plugin's verdict: the issues of its own rules, or why they could not run. */
+export type PluginOptionsVerdict = {
+    readonly issues: readonly PluginOptionIssue[];
+} | {
+    readonly failed: string;
+};
+/**
+ * D-0162: the plugins' own option rules on their sections, cross-field checks included
+ * (dokebi-app's `unknownDomain` must be `reject` or a key of `domains`), which the JSON schema
+ * cannot say. Every listed plugin's main entry is imported in ONE permission-restricted child, as
+ * install modules are (a child per plugin made `dokebi check` about a second slower on a blog
+ * project), and its `createPlugin.checkOptions` gets its section. A plugin without it (a parser
+ * function, an older core) is left out of the result; a plugin whose entry fails has `failed`.
+ */
+export declare function checkPluginsOptions(base: string, plugins: readonly PluginManifest[], options: Record<string, unknown>): Promise<Map<string, PluginOptionsVerdict>>;
 export declare function checkPlugin(input: LifecycleInput): Promise<CheckResult>;
 /** Runs check for every plugin and returns results by plugin id. */
 export declare function checkAll(inputs: readonly Omit<LifecycleInput, 'plugins'>[], plugins: readonly PluginManifest[]): Promise<Map<string, CheckResult>>;

package/dist/plugin-lifecycle.js

@@ -1,10 +1,13 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { debug, debugEnabled, describeError } from './diagnostics.js';
 import { CliError } from './errors.js';
 import { object } from './filesystem.js';
 import { InstallPlanningError, installReadRoots, PHASE_MISSING, runInstallModule, } from './install-module.js';
 import { readInstallPlan } from './install-plan.js';
 import { assertLayout } from './layout.js';
-import { ID } from './manifest.js';
+import { ID, optionsKey } from './manifest.js';
 import { packageDirectory, packageFile } from './workspace.js';
 // Printable single line: no control characters (log/terminal injection) and a short bound.
 const HINT = /^[^\p{Cc}]{1,200}$/u;
@@ -12,6 +15,28 @@ const CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
 const KEY = /^[A-Za-z0-9_-]{1,64}$/;
 /** An environment variable name a plan may ask a generated secret for. */
 export const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+/** The most generated secrets one plan may ask for (configSecrets, envSecrets). */
+const MAX_SECRETS = 8;
+/**
+ * Keys a planInstall result may have. Install modules get them as `planKeys` in their context, so
+ * a plugin can tell whether this CLI takes `configSecrets` (0.4.3 and later) or only `envSecrets`.
+ */
+export const INSTALL_PLAN_KEYS = Object.freeze([
+    'directories',
+    'files',
+    'entry',
+    'configDefaults',
+    'requires',
+    'configSecrets',
+    'envSecrets',
+]);
+const UPGRADE_PLAN_KEYS = Object.freeze([
+    'directories',
+    'files',
+    'entry',
+    'configChanges',
+    'requires',
+]);
 export function optionsOf(options, id) {
     const value = Object.hasOwn(options, id) ? options[id] : undefined;
     return value === undefined || value === null ? {} : object(value, 'plugin options');
@@ -40,10 +65,28 @@ export function optionPath(value) {
     }
     return [...value];
 }
+/** `configSecrets: [{ path }]`: paths inside the plugin's own options, at most 8, no repeats. */
+function configSecrets(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > MAX_SECRETS)
+        throw new Error('configSecrets');
+    const result = [];
+    for (const raw of value) {
+        const item = object(raw, 'config secret');
+        if (Object.keys(item).some((key) => key !== 'path'))
+            throw new Error('configSecrets');
+        const path = optionPath(item.path);
+        if (result.some((other) => other.join('.') === path.join('.')))
+            throw new Error('configSecrets');
+        result.push(path);
+    }
+    return result;
+}
 function envSecrets(value) {
     if (value === undefined)
         return [];
-    if (!Array.isArray(value) || value.length > 8)
+    if (!Array.isArray(value) || value.length > MAX_SECRETS)
         throw new Error('envSecrets');
     const result = [];
     for (const item of value) {
@@ -81,7 +124,8 @@ async function run(input, phase, extra = {}) {
         // the workspace root with their .env files.
         const readRoots = await installReadRoots(directory);
         return await runInstallModule(path, phase, {
-            options: optionsOf(input.options, input.plugin.id),
+            // R4CB-6: the plugin's own section: options.logging for the logger host (D-0151).
+            options: optionsOf(input.options, optionsKey(input.plugin)),
             plugins: input.plugins.map(({ id, version, packageName }) => ({
                 id,
                 version,
@@ -92,24 +136,28 @@ async function run(input, phase, extra = {}) {
         }, readRoots);
     }
     catch (error) {
-        // The caller sees only the code; debug keeps the cause of an unexpected failure.
-        if (!(error instanceof InstallPlanningError) && debugEnabled())
+        // The caller sees only the code (a module's message may carry option values, and the module
+        // is a package's code); debug keeps the cause, and the module's own words for its author
+        // (the error it threw or the end of its stderr, masked), which were dropped before.
+        if (debugEnabled())
             debug('Install module could not be run', {
                 plugin: input.plugin.id,
                 phase,
-                error: describeError(error),
+                ...(error instanceof InstallPlanningError
+                    ? { code: error.code, ...(error.detail ? { module: error.detail } : {}) }
+                    : { error: describeError(error) }),
             });
         throw new CliError('PLUGIN_INSTALL_FAILED', input.plugin.id +
             ': ' +
             (error instanceof InstallPlanningError ? error.code : 'INSTALL_MODULE_FAILED'), { details: { plugin: input.plugin.id, phase } });
     }
 }
-function invalidPlan(id) {
-    return new CliError('INVALID_MANIFEST', 'Invalid installation plan: ' + id);
+function invalidPlan(id, cause) {
+    return new CliError('INVALID_MANIFEST', 'Invalid installation plan: ' + id, cause === undefined ? undefined : { cause });
 }
 /** Static `dokebi.install` merged with the module's planInstall or planUpgrade result. */
 export async function planLifecycle(input, phase, extra = {}) {
-    const raw = await run(input, phase, extra);
+    const raw = await run(input, phase, phase === 'planInstall' ? { planKeys: [...INSTALL_PLAN_KEYS], ...extra } : extra);
     const plugin = input.plugin;
     const base = {
         files: plugin.files,
@@ -120,24 +168,32 @@ export async function planLifecycle(input, phase, extra = {}) {
     const staticDefaults = base.configDefaults ? [base.configDefaults] : [];
     if (raw === PHASE_MISSING) {
         const { configDefaults: _ignored, ...rest } = base;
-        return { ...rest, defaults: staticDefaults, requires: [], configChanges: [], envSecrets: [] };
+        return {
+            ...rest,
+            defaults: staticDefaults,
+            requires: [],
+            configChanges: [],
+            configSecrets: [],
+            envSecrets: [],
+        };
     }
     let plan;
     let requires;
     let changes;
+    let secretPaths;
     let secrets;
     try {
         plan = object(raw, 'installation plan');
-        const allowed = phase === 'planInstall'
-            ? ['directories', 'files', 'entry', 'configDefaults', 'requires', 'envSecrets']
-            : ['directories', 'files', 'entry', 'configChanges', 'requires'];
+        const allowed = phase === 'planInstall' ? INSTALL_PLAN_KEYS : UPGRADE_PLAN_KEYS;
         if (Object.keys(plan).some((key) => !allowed.includes(key)))
             throw new Error('keys');
         requires = requirements(plan.requires, plugin.id);
         changes = configChanges(plan.configChanges);
+        secretPaths = configSecrets(plan.configSecrets);
         secrets = envSecrets(plan.envSecrets);
     }
-    catch {
+    catch (error) {
+        debug('Install plan refused', { plugin: plugin.id, phase, error: describeError(error) });
         throw invalidPlan(plugin.id);
     }
     if (plan.entry !== undefined && base.entry !== undefined)
@@ -160,8 +216,8 @@ export async function planLifecycle(input, phase, extra = {}) {
             ...(plan.entry !== undefined ? { entry: dynamic.entry } : {}),
         }, plugin.id, plugin.hosts);
     }
-    catch {
-        throw invalidPlan(plugin.id);
+    catch (error) {
+        throw invalidPlan(plugin.id, error);
     }
     const { configDefaults, ...files } = dynamic;
     return {
@@ -169,9 +225,132 @@ export async function planLifecycle(input, phase, extra = {}) {
         defaults: configDefaults ? [...staticDefaults, configDefaults] : staticDefaults,
         requires,
         configChanges: changes,
+        configSecrets: secretPaths,
         envSecrets: secrets,
     };
 }
+const ISSUE_CODE = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+/** The package's main ESM entry, relative to its folder: `exports["."]` (import), else `main`. */
+async function mainEntry(directory) {
+    const pkg = object(JSON.parse(await readFile(join(directory, 'package.json'), 'utf8')), 'package');
+    const exported = pkg.exports;
+    const dot = typeof exported === 'string'
+        ? exported
+        : exported && typeof exported === 'object' && !Array.isArray(exported)
+            ? exported['.']
+            : undefined;
+    const target = typeof dot === 'string'
+        ? dot
+        : dot && typeof dot === 'object'
+            ? (dot.import ?? dot.default)
+            : pkg.main;
+    return typeof target === 'string' ? target.replace(/^\.\//, '') : undefined;
+}
+/**
+ * D-0162: the plugins' own option rules on their sections, cross-field checks included
+ * (dokebi-app's `unknownDomain` must be `reject` or a key of `domains`), which the JSON schema
+ * cannot say. Every listed plugin's main entry is imported in ONE permission-restricted child, as
+ * install modules are (a child per plugin made `dokebi check` about a second slower on a blog
+ * project), and its `createPlugin.checkOptions` gets its section. A plugin without it (a parser
+ * function, an older core) is left out of the result; a plugin whose entry fails has `failed`.
+ */
+export async function checkPluginsOptions(base, plugins, options) {
+    const verdicts = new Map();
+    const entries = [];
+    for (const plugin of plugins) {
+        const directory = await packageDirectory(base, plugin.packageName);
+        const entry = await mainEntry(directory);
+        if (entry === undefined)
+            continue;
+        entries.push({
+            id: plugin.id,
+            path: await packageFile(base, plugin.packageName, entry),
+            directory,
+            options: optionsOf(options, optionsKey(plugin)),
+        });
+    }
+    const first = entries[0];
+    if (!first)
+        return verdicts;
+    const roots = new Set();
+    for (const entry of entries)
+        for (const root of await installReadRoots(entry.directory))
+            roots.add(root);
+    let raw;
+    try {
+        raw = await runInstallModule(first.path, 'checkOptions', {
+            // Each entry carries its own section; the shared fields stay empty for this phase.
+            options: {},
+            plugins: [],
+            entries: entries.map((entry) => ({
+                url: pathToFileURL(entry.path).href,
+                options: entry.options,
+            })),
+        }, [...roots]);
+    }
+    catch (error) {
+        if (debugEnabled())
+            debug('Plugin options could not be checked', {
+                plugins: entries.map((entry) => entry.id),
+                ...(error instanceof InstallPlanningError
+                    ? { code: error.code, ...(error.detail ? { module: error.detail } : {}) }
+                    : { error: describeError(error) }),
+            });
+        throw new CliError('PLUGIN_OPTIONS_CHECK_FAILED', `Plugin options could not be checked: ${error instanceof InstallPlanningError ? error.code : 'INSTALL_MODULE_FAILED'}`, { cause: error });
+    }
+    if (!Array.isArray(raw) || raw.length !== entries.length)
+        throw new CliError('INVALID_MANIFEST', 'Invalid options check result');
+    raw.forEach((item, index) => {
+        const entry = entries[index];
+        const answer = object(item, 'options check');
+        if (answer.ok === false) {
+            if (debugEnabled())
+                debug('Plugin options could not be checked', {
+                    plugin: entry.id,
+                    code: answer.code,
+                    ...(typeof answer.message === 'string' ? { module: answer.message } : {}),
+                });
+            verdicts.set(entry.id, {
+                failed: typeof answer.code === 'string' && ISSUE_CODE.test(answer.code)
+                    ? answer.code
+                    : 'INSTALL_MODULE_FAILED',
+            });
+            return;
+        }
+        if (answer.missing === true)
+            return;
+        verdicts.set(entry.id, { issues: optionIssues(answer.result, entry.id) });
+    });
+    return verdicts;
+}
+/** The issues of one checkOptions result, shaped like the schema validator's. */
+function optionIssues(raw, id) {
+    const result = object(raw, 'options check');
+    const issues = result.issues;
+    if (typeof result.ok !== 'boolean' || !Array.isArray(issues) || issues.length > 100)
+        throw new CliError('INVALID_MANIFEST', `Invalid options check result: ${id}`);
+    return issues.map((item) => {
+        const issue = object(item, 'options issue');
+        if (typeof issue.path !== 'string' ||
+            issue.path.length > 500 ||
+            typeof issue.code !== 'string' ||
+            !ISSUE_CODE.test(issue.code) ||
+            typeof issue.message !== 'string' ||
+            issue.message.length > 500)
+            throw new CliError('INVALID_MANIFEST', `Invalid options check result: ${id}`);
+        const pointer = issue.path
+            .replace(/\[(\d+)\]/g, '.$1')
+            .split('.')
+            .filter(Boolean)
+            .map((part) => part.replaceAll('~', '~0').replaceAll('/', '~1'))
+            .join('/');
+        return {
+            instancePath: pointer ? `/${pointer}` : '',
+            keyword: issue.code,
+            message: issue.message,
+        };
+    });
+}
 export async function checkPlugin(input) {
     const raw = await run(input, 'check', {
         installation: input.installation?.entry ? { entry: input.installation.entry } : {},

package/dist/plugin-options.d.ts

@@ -1,16 +1,31 @@
-import type { PluginManifest } from './manifest.js';
+import { type PluginManifest } from './manifest.js';
+import { type OptionIssueLike } from './option-fixes.js';
 export interface OptionsCheck {
     schema: Record<string, unknown> | null;
-    errors: Array<{
-        instancePath: string;
-        keyword: string;
+    errors: OptionIssueLike[];
+}
+/** What checks options against a schema (ConfigValidator of @dokebi/config; a fake in tests). */
+export interface SchemaChecker {
+    check(schema: unknown, options: unknown): Promise<{
+        errors: OptionIssueLike[];
     }>;
 }
 export declare class PluginOptionsValidator {
     #private;
     constructor(options?: {
         allErrors?: boolean;
+        validator?: SchemaChecker;
     });
+    /**
+     * D-0155: the options of an application settings section against the schema file beside its
+     * declaration (src/shared/settings/<section>.schema.json); no schema yet checks nothing.
+     */
+    checkSettings(root: string, section: string, options: unknown): Promise<OptionsCheck>;
+    /**
+     * A settings section against a schema in hand (`settings sync` checks the options against the
+     * schema it is about to write, before the file is on disk).
+     */
+    checkSettingsWith(section: string, schema: Record<string, unknown>, options: unknown): Promise<OptionsCheck>;
     check(root: string, plugin: PluginManifest, options: unknown): Promise<OptionsCheck>;
 }
 export declare function checkPluginOptions(root: string, plugin: PluginManifest, options: unknown): Promise<OptionsCheck>;