@dokebi/cli 0.4.2 → 0.4.27

package/dist/config-show.js

@@ -0,0 +1,563 @@
+// `dokebi config show [<plugin-id>[.<path>]]` (AI-M05): the options of dokebi.yaml with every
+// secret replaced by a marker, so an agent never has to cat or sed the file (one did, masked
+// by hand, missed a value and printed a CSRF secret into its log). A value is a secret when
+//   - the plugin's options schema marks it (`writeOnly`, from `o.string({ secret: true })`; the
+//     same marking `dokebi check` secret-in-config reads), a list of them as one secret,
+//   - its key is named like one by core's rule, the one the logs use (`redaction.isSecretField`
+//     of @dokebi/core/libraries, D-0047: password, secret, token, apiKey, authorization, cookie,
+//     credentials, pin …), unless the schema marks the option plain (`x-dokebi-secret: false`,
+//     core option `plain`); an object whose schema declares its fields is judged field by field,
+//   - it is the recipe's first admin password (first-admin.initialPassword, or the older
+//     blog-admin.initialPassword, D-0115),
+//   - or it holds credentials by core's `redaction.maskCredentials` (the password of a
+//     `scheme://user:password@host` URL, `Password=…` of a connection string; only that part).
+// A plugin whose schema cannot be read shows no string at all (fail closed). Values are never
+// put into the result, errors or debug logs; only option paths and counts are.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadSchema } from '@dokebi/config';
+import { reloadOptions } from '@dokebi/core';
+import { redaction } from '@dokebi/core/libraries';
+import { Document, isCollection, isMap, isNode, isScalar } from 'yaml';
+import { CONFIG_FILE, configTarget, missingConfig, parseProjectConfig, readNamedSettings, readProjectConfigSource, } from './configuration.js';
+import { aliasTargets } from './configuration-scaffold.js';
+import { debug, describeError, isMissing } from './diagnostics.js';
+import { envFileWarnings } from './env-file.js';
+import { CliError } from './errors.js';
+import { parseObject } from './filesystem.js';
+import { adminSections } from './first-admin.js';
+import { optionsKey } from './manifest.js';
+import { readState } from './project-state.js';
+import { ADMIN_PASSWORD_KEY, ADMIN_SECTIONS } from './recipe-login.js';
+import { CORE_LOGGING_SCHEMA, RELOADABLE_MARK, reloadableAt } from './reloadable.js';
+import { CONVENTION_SECTIONS, catalogPackageOf, readSettingsSchema, undeclaredSection, undeclaredSectionError, } from './settings.js';
+import { packageFile } from './workspace.js';
+/** A list index as config set, unset and secret read one (resolveItems). */
+const ITEM_INDEX = /^(?:0|[1-9][0-9]{0,5})$/;
+/** What a hidden value is replaced with. */
+export const SECRET_MARKER = '<secret: set>';
+/** What the password of a URL is replaced with: `scheme://user:<secret>@host`. */
+export const URL_SECRET_MARKER = '<secret>';
+/**
+ * A credential written as a placeholder, the documented shape of a secret to fill in:
+ * `scheme://user:<password>@host`, `Password=<password>`. Not a credential.
+ */
+const CREDENTIAL_PLACEHOLDER = /(\/\/)[^\s/@:]*:<[^<>\s@]*>@|\b(?:password|pwd)\s*=\s*<[^<>;]*>/gi;
+/**
+ * Text with its credentials hidden by core's rule (`redaction.maskCredentials`: the password of
+ * a URL, also one with a raw `/` or `@` in it, and `Password=…` of a connection string), or
+ * undefined when it holds none. The URL keeps its user: `scheme://user:<secret>@host`.
+ */
+export function hideCredentials(text) {
+    const value = text.trim();
+    const probe = value.replace(CREDENTIAL_PLACEHOLDER, (_match, slashes) => slashes ? '//' : '');
+    if (redaction.maskCredentials(probe) === probe)
+        return undefined;
+    const masked = redaction.maskCredentials(value);
+    const at = masked.indexOf('//***@');
+    if (at !== -1 && masked.split('***').length === 2) {
+        // One masked part: the user is what the original has before the password.
+        const rest = masked.slice(at + 6);
+        const userinfo = value.slice(at + 2, value.length - rest.length - 1);
+        const colon = userinfo.indexOf(':');
+        if (value.startsWith(masked.slice(0, at)) && value.endsWith(`@${rest}`))
+            return `${masked.slice(0, at)}//${colon > 0 ? `${userinfo.slice(0, colon)}:` : ''}${URL_SECRET_MARKER}@${rest}`;
+    }
+    return masked
+        .replaceAll('//***@', `//${URL_SECRET_MARKER}@`)
+        .replace(/\b(password|pwd)(\s*=\s*)\*\*\*/gi, `$1$2${URL_SECRET_MARKER}`);
+}
+/** The topmost reloadable paths present in `value` (a section's shown options). */
+function reloadablePaths(value, schema, path, section, into) {
+    const visit = (node, at) => {
+        if (at.length && reloadableAt(schema, at)) {
+            into.push([section, ...at].join('.'));
+            return;
+        }
+        if (Array.isArray(node))
+            for (const [index, item] of node.entries())
+                visit(item, [...at, index]);
+        else if (isObject(node))
+            for (const [key, item] of Object.entries(node))
+                visit(item, [...at, key]);
+    };
+    visit(value, path);
+}
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/**
+ * The schema nodes that apply at one place: the node and its anyOf/oneOf/allOf branches.
+ * `conditional` (secrets only, R4CA-9): also the `then`/`else` and `dependentSchemas` forms, which
+ * may apply — a secret mark there hides the value; their defaults are never filled in.
+ */
+function expand(schemas, depth = 0, conditional = false) {
+    const nodes = [];
+    for (const schema of schemas) {
+        if (!isObject(schema))
+            continue;
+        nodes.push(schema);
+        if (depth >= 8)
+            continue;
+        const forms = [];
+        for (const key of ['anyOf', 'oneOf', 'allOf'])
+            if (Array.isArray(schema[key]))
+                forms.push(...schema[key]);
+        if (conditional) {
+            forms.push(schema.then, schema.else);
+            if (isObject(schema.dependentSchemas))
+                forms.push(...Object.values(schema.dependentSchemas));
+        }
+        nodes.push(...expand(forms, depth + 1, conditional));
+    }
+    return nodes;
+}
+/** Whether a patternProperties pattern names `key` (one that does not compile: fail closed). */
+function patternNames(pattern, key) {
+    try {
+        return new RegExp(pattern, 'u').test(key);
+    }
+    catch (error) {
+        debug('config show: a patternProperties pattern does not compile; taken to apply', {
+            error: describeError(error),
+        });
+        return true;
+    }
+}
+/**
+ * The schemas of the property `key` (JSON Schema 2020-12): its `properties` entry and every
+ * `patternProperties` entry whose pattern matches it; `additionalProperties` only when neither
+ * does. R4CA-9: patternProperties were not followed, so a secret marked there was printed.
+ */
+function childSchemas(nodes, key) {
+    return nodes.flatMap((node) => {
+        const properties = isObject(node.properties) ? node.properties : {};
+        const named = Object.hasOwn(properties, key) ? [properties[key]] : [];
+        const patterns = isObject(node.patternProperties)
+            ? Object.entries(node.patternProperties)
+                .filter(([pattern]) => patternNames(pattern, key))
+                .map(([, schema]) => schema)
+            : [];
+        if (named.length || patterns.length)
+            return [...named, ...patterns];
+        return isObject(node.additionalProperties) ? [node.additionalProperties] : [];
+    });
+}
+/** The schemas of item `index` of a list: its `prefixItems` entry, else `items` (R4CA-9). */
+function itemSchemas(nodes, index) {
+    return nodes.flatMap((node) => Array.isArray(node.prefixItems) && index < node.prefixItems.length
+        ? [node.prefixItems[index]]
+        : isObject(node.items)
+            ? [node.items]
+            : []);
+}
+/**
+ * Whether an option named `key` that holds `value` is a secret by its name: core's rule, the one
+ * the logs use (`redaction.isSecretField`, D-0047). Text, a list or an object under a secret name
+ * is; a number only under a password, PIN or code name; a boolean never. Where the schema marks
+ * the option plain (`x-dokebi-secret: false`) the name is not asked.
+ */
+export function secretOption(key, value) {
+    return redaction.isSecretField(key, value);
+}
+/**
+ * The name rule at one option: `secretOption`, except that an object (or a list of objects) whose
+ * schema declares its fields is judged field by field (a cookie's name and path, auth's
+ * tokens.driver: AI-M24), and a plain option (`x-dokebi-secret: false`) never.
+ */
+function secretByName(key, value, nodes) {
+    if (/^\d+$/.test(key) || nodes.some((node) => node['x-dokebi-secret'] === false))
+        return false;
+    if (!secretOption(key, value))
+        return false;
+    if (isObject(value) && nodes.some((node) => isObject(node.properties)))
+        return false;
+    if (Array.isArray(value) &&
+        expand(nodes.map((node) => node.items)).some((node) => isObject(node.properties)))
+        return false;
+    return true;
+}
+/** Fills schema defaults of unset properties into objects that are shown (a copy). */
+function withDefaults(value, schemas, path, defaults, 
+/** Keys of this object an old name (D-0071 alias) of the parent already sets: no default. */
+aliased = new Set()) {
+    if (!isObject(value))
+        return value;
+    const nodes = expand(schemas);
+    const result = { ...value };
+    // An alias that is set gives its target the value: the target's default does not apply.
+    const taken = new Set(aliased);
+    const below = new Map();
+    for (const node of nodes)
+        for (const [alias, [first, second]] of aliasTargets(node)) {
+            if (!Object.hasOwn(value, alias))
+                continue;
+            if (second === undefined)
+                taken.add(first);
+            else
+                below.set(first, new Set([...(below.get(first) ?? []), second]));
+        }
+    for (const [key, child] of Object.entries(result))
+        result[key] = withDefaults(child, childSchemas(nodes, key), [...path, key], defaults, below.get(key));
+    for (const node of nodes) {
+        if (!isObject(node.properties))
+            continue;
+        for (const [key, property] of Object.entries(node.properties)) {
+            if (Object.hasOwn(result, key) || !isObject(property) || property.default === undefined)
+                continue;
+            if (taken.has(key) || property.writeOnly === true)
+                continue;
+            // A default the name rule would hide is not filled in (it would read as a secret set).
+            if (secretByName(key, property.default, expand([property])))
+                continue;
+            let filled = structuredClone(property.default);
+            const inside = below.get(key);
+            if (inside && isObject(filled))
+                filled = Object.fromEntries(Object.entries(filled).filter(([name]) => !inside.has(name)));
+            result[key] = filled;
+            defaults.push([...path, key].join('.'));
+        }
+    }
+    return result;
+}
+/**
+ * A copy of `value` with its leaves hidden (null and empty strings say nothing and stay).
+ * `strings`: only text is hidden (a list or object under a secret name may hold counts).
+ */
+function hide(value, strings) {
+    let hidden = false;
+    const walk = (item) => {
+        if (Array.isArray(item))
+            return item.map(walk);
+        if (isObject(item))
+            return Object.fromEntries(Object.entries(item).map(([key, child]) => [key, walk(child)]));
+        if (item === null || item === undefined || item === '')
+            return item;
+        if (strings && typeof item !== 'string')
+            return item;
+        hidden = true;
+        return SECRET_MARKER;
+    };
+    const result = walk(value);
+    return { value: result, hidden };
+}
+/**
+ * A copy of `value` with the secrets hidden. `unknown`: no schema could be read for this part,
+ * so every string is hidden (numbers and booleans still show).
+ */
+function mask(value, schemas, path, unknown, secrets) {
+    // Every form that may apply, the conditional ones too: a secret mark anywhere hides (R4CA-9).
+    const nodes = expand(schemas, 0, true);
+    const key = path[path.length - 1] ?? '';
+    // A $ref is not followed: what it points at is treated as unknown (fail closed).
+    const blind = unknown || nodes.some((node) => node.$ref !== undefined);
+    const schemaMarked = nodes.some((node) => node.writeOnly === true) ||
+        (Array.isArray(value) &&
+            expand(nodes.map((node) => node.items)).some((node) => node.writeOnly === true)) ||
+        (path.length === 2 && ADMIN_SECTIONS.includes(path[0] ?? '') && key === ADMIN_PASSWORD_KEY);
+    // `x-dokebi-secret: false` (core option `plain`) is honoured by secretByName.
+    if (schemaMarked || (path.length > 1 && secretByName(key, value, nodes))) {
+        // A secret value is hidden whole; inside a list or object under a secret name, its text.
+        const hidden = hide(value, !schemaMarked && (Array.isArray(value) || isObject(value)));
+        if (hidden.hidden) {
+            secrets.push(path.join('.'));
+            return hidden.value;
+        }
+    }
+    if (Array.isArray(value))
+        return value.map((item, index) => mask(item, itemSchemas(nodes, index), [...path, String(index)], blind, secrets));
+    if (isObject(value))
+        return Object.fromEntries(Object.entries(value).map(([child, item]) => [
+            child,
+            mask(item, childSchemas(nodes, child), [...path, child], blind, secrets),
+        ]));
+    if (typeof value === 'string') {
+        if (blind && value !== '') {
+            secrets.push(path.join('.'));
+            return SECRET_MARKER;
+        }
+        const hidden = hideCredentials(value);
+        if (hidden !== undefined) {
+            secrets.push(path.join('.'));
+            return hidden;
+        }
+    }
+    return value;
+}
+/**
+ * Whether a value at an option path is a secret (`config unset` warns `SECRET_REMOVED` for one;
+ * D-0165 dropped the `SECRET_ON_COMMAND_LINE` warning it gave `--set` and `config set`). The
+ * plugin's options schema decides
+ * (AI-M24: `tokens.driver=redis`, `tokens.connection=main` and `maxTokensPerUser=5` of
+ * @dokebi/auth warned because a path word matched /token/): a value at a `writeOnly` option
+ * (`o.string({ secret: true })`), a list of them, or anything inside an object value that
+ * reaches one. Where the schema says nothing (an option it does not declare, a schema that
+ * cannot be read: `schema` undefined), the name decides by core's rule (`secretOption`): text,
+ * or text inside a list or object, under a secret name; a number only under a password, PIN or
+ * code name. Credentials by core's `maskCredentials` (a `scheme://user:password@` URL,
+ * `Password=…`) are a secret anywhere. Booleans never are.
+ */
+export function commandLineSecret(path, value, schema) {
+    let nodes = schema === undefined || schema === null ? [] : expand([schema], 0, true);
+    // A list item on the way (`targets.0.token`) is that item's schema.
+    for (const key of path)
+        nodes = expand(/^\d+$/.test(key) &&
+            !nodes.some((node) => isObject(node.properties) && Object.hasOwn(node.properties, key))
+            ? itemSchemas(nodes, Number(key))
+            : childSchemas(nodes, key), 0, true);
+    return secretValue(value, nodes, path[path.length - 1] ?? '');
+}
+function secretValue(value, nodes, key) {
+    const marked = nodes.some((node) => node.writeOnly === true) ||
+        (Array.isArray(value) &&
+            expand(nodes.map((node) => node.items)).some((node) => node.writeOnly === true));
+    if (marked && hide(value, false).hidden)
+        return true;
+    // Undeclared here: only the name is left to go by.
+    if (nodes.length === 0 &&
+        !/^\d+$/.test(key) &&
+        secretOption(key, value) &&
+        hide(value, Array.isArray(value) || isObject(value)).hidden)
+        return true;
+    if (Array.isArray(value))
+        return value.some((item, index) => secretValue(item, expand(itemSchemas(nodes, index), 0, true), key));
+    if (isObject(value))
+        return Object.entries(value).some(([child, item]) => secretValue(item, expand(childSchemas(nodes, child), 0, true), child));
+    return typeof value === 'string' && value !== '' && hideCredentials(value) !== undefined;
+}
+async function readText(root, file) {
+    try {
+        return file === CONFIG_FILE
+            ? await readProjectConfigSource(root)
+            : await readFile(join(root, file), 'utf8');
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        if (isMissing(error))
+            throw file === CONFIG_FILE
+                ? missingConfig(root, `No ${file}: run this in a Dokebi project (the folder with dokebi.yaml)`)
+                : new CliError('NOT_A_PROJECT', `No ${file}: run this in a Dokebi project (the folder with dokebi.yaml)`, { phase: 'arguments', details: { root, file } });
+        throw new CliError('READ_FAILED', `Cannot read ${file}`, { cause: error });
+    }
+}
+/**
+ * The settings the app reads (M50): the file DOKEBI_CONFIG names, else dokebi.yaml. Reading one
+ * outside the project is allowed (as a linked dokebi.yaml is); a named file that is not there is
+ * READ_FAILED with the variable in the message.
+ */
+export async function readSettings(root) {
+    const target = await configTarget(root);
+    return {
+        target,
+        source: target.fromEnvironment
+            ? await readNamedSettings(root, target)
+            : await readText(root, CONFIG_FILE),
+    };
+}
+/** The options schema of one installed plugin; undefined when it cannot be read. */
+async function pluginSchema(root, plugin) {
+    if (!plugin.optionsSchema)
+        return { schema: {} };
+    try {
+        return {
+            schema: await loadSchema(await packageFile(root, plugin.packageName, plugin.optionsSchema)),
+        };
+    }
+    catch (error) {
+        debug('config show: options schema unreadable; its strings are hidden', {
+            plugin: plugin.id,
+            error: describeError(error),
+        });
+        return undefined;
+    }
+}
+/** `dokebi config show [<plugin-id>[.<path>]]`: options with secrets hidden. */
+export async function configShow(root, target, 
+/**
+ * Another document than the settings file (config diff reads the sample's secrets with it, and
+ * the settings its transaction read).
+ */
+from) {
+    const state = readState(parseObject(await readText(root, '.dokebi/state.json'), 'state'));
+    const read = from ? undefined : await readSettings(root);
+    const file = from?.file ?? read?.target.file ?? CONFIG_FILE;
+    const options = parseProjectConfig(from?.source ?? read?.source ?? '').options;
+    const sections = { ...options };
+    // D-0151: the logger host's options are options.logging (optionsKey).
+    for (const plugin of state.plugins)
+        if (!Object.hasOwn(sections, optionsKey(plugin)))
+            sections[optionsKey(plugin)] = {};
+    // D-0155: the settings sections of the application, with their schema defaults.
+    for (const section of state.settings ?? [])
+        if (!Object.hasOwn(sections, section))
+            sections[section] = {};
+    const defaults = [];
+    const secrets = [];
+    const reloadable = [];
+    // R4CA-3: a DOKEBI_CONFIG in .env is not what the app or this command reads: said here.
+    const warnings = from
+        ? []
+        : envFileWarnings(root).map(({ code, path, hint }) => ({ code, path, hint }));
+    const shown = {};
+    let packageOf;
+    const undeclared = async (section) => {
+        packageOf ??= await catalogPackageOf();
+        return undeclaredSection(section, packageOf, state.plugins.map((item) => item.id), state.settings ?? []);
+    };
+    // The first admin a recipe wrote, under any section name (D-0115), is the framework's too.
+    const conventions = new Set([...CONVENTION_SECTIONS, ...adminSections(options)]);
+    for (const [section, value] of Object.entries(sections)) {
+        if (target && target.section !== section)
+            continue;
+        const plugin = state.plugins.find((item) => optionsKey(item) === section);
+        // Core's own sections (D-0154): options.reload, and options.logging without a logger plugin.
+        const core = section === 'reload'
+            ? reloadOptions.schema
+            : section === 'logging'
+                ? CORE_LOGGING_SCHEMA
+                : {};
+        const settings = !plugin && (state.settings ?? []).includes(section);
+        const settingsSchema = settings ? await readSettingsSchema(root, section) : undefined;
+        const declared = plugin || settings || section === 'reload' || section === 'logging';
+        // D-0155: a section nobody declares has no defaults and no secret marks: its text values are
+        // hidden (it may hold secrets) and it is named with the code config set would refuse. The
+        // framework's own sections (first-admin) keep the masking by name they always had.
+        if (!declared && !conventions.has(section)) {
+            const found = await undeclared(section);
+            warnings.push({
+                code: found.code,
+                plugin: section,
+                hint: `${found.message}; ${found.details.fix}`,
+            });
+        }
+        const schema = plugin
+            ? await pluginSchema(root, plugin)
+            : settingsSchema
+                ? { schema: settingsSchema }
+                : declared || conventions.has(section)
+                    ? { schema: core }
+                    : undefined;
+        if (!schema && plugin)
+            warnings.push({
+                code: 'OPTIONS_SCHEMA_UNREADABLE',
+                plugin: plugin.id,
+                hint: `the options schema of ${plugin.packageName} could not be read (npm install?); its text values are hidden`,
+            });
+        const filled = schema ? withDefaults(value, [schema.schema], [section], defaults) : value;
+        shown[section] = mask(filled, schema ? [schema.schema] : [], [section], !schema, secrets);
+        if (schema)
+            reloadablePaths(filled, schema.schema, [], section, reloadable);
+    }
+    // An installed plugin's id that is not its section (the logger's dokebi-logger reads
+    // options.logging, D-0151): never "not installed"; the same refusal as config set and unset.
+    const named = state.plugins.find((item) => item.id === target?.section);
+    if (target && named && !Object.hasOwn(shown, target.section)) {
+        const asked = [target.section, ...target.path].join('.');
+        const live = [optionsKey(named), ...target.path].join('.');
+        throw new CliError('PATH_MISMATCH', `${named.packageName} reads options.${optionsKey(named)}, not options.${target.section}`, {
+            phase: 'arguments',
+            details: {
+                requested: [asked],
+                outside: [live],
+                fix: `name the options as the files spell them: npx dokebi config show ${live}`,
+            },
+        });
+    }
+    // A section neither declared nor in dokebi.yaml: the same code as config set and unset.
+    if (target && !Object.hasOwn(shown, target.section))
+        throw undeclaredSectionError(await undeclared(target.section));
+    let value = target ? shown[target.section] : shown;
+    /** The asked path with list items as indexes (the paths of defaults and secrets use them). */
+    const resolved = [];
+    if (target)
+        for (const [index, key] of target.path.entries()) {
+            let next;
+            let segment = key;
+            if (Array.isArray(value)) {
+                // R4CA-7: a list item by its index, else its `name`, else the `type` of an item without
+                // a name — as config set, unset and secret name it (resolveItems).
+                let at = ITEM_INDEX.test(key)
+                    ? Number(key)
+                    : value.findIndex((item) => isObject(item) && item.name === key);
+                if (at < 0)
+                    at = value.findIndex((item) => isObject(item) && !Object.hasOwn(item, 'name') && item.type === key);
+                next = at >= 0 ? value[at] : undefined;
+                segment = String(at);
+            }
+            else
+                next = isObject(value) && Object.hasOwn(value, key) ? value[key] : undefined;
+            if (next === undefined) {
+                const where = [target.section, ...target.path.slice(0, index)].join('.');
+                throw new CliError('UNKNOWN_OPTION', `${[target.section, ...target.path].join('.')} is not set in ${file} and has no default`, {
+                    phase: 'arguments',
+                    details: {
+                        path: [target.section, ...target.path].join('.'),
+                        parent: where,
+                        keys: isObject(value) ? Object.keys(value) : Array.isArray(value) ? value.length : [],
+                        // A list: how each item is named (its name, else type, else index).
+                        ...(Array.isArray(value)
+                            ? {
+                                items: value.map((item, at) => isObject(item) && typeof (item.name ?? item.type) === 'string'
+                                    ? String(item.name ?? item.type)
+                                    : String(at)),
+                            }
+                            : {}),
+                        fix: `npx dokebi config show ${where} shows what is there; the plugin AI.md lists its options`,
+                    },
+                });
+            }
+            value = next;
+            resolved.push(segment);
+        }
+    const prefix = target ? [target.section, ...target.path].join('.') : '';
+    const at = target ? [target.section, ...resolved].join('.') : '';
+    const inside = (path) => !at || path === at || path.startsWith(`${at}.`);
+    debug('Configuration shown', {
+        path: prefix || null,
+        sections: Object.keys(shown).length,
+        secrets: secrets.length,
+        defaults: defaults.length,
+    });
+    return {
+        file,
+        path: prefix || null,
+        value,
+        defaults: defaults.filter(inside),
+        secrets: secrets.filter(inside),
+        reloadable: reloadable.filter((path) => inside(path) || at.startsWith(`${path}.`)),
+        ...(warnings.length ? { warnings } : {}),
+    };
+}
+/** The result for people: YAML, defaults marked with a comment, secrets already hidden. */
+export function configShowText(result) {
+    const base = result.path ? result.path.split('.') : [];
+    const document = new Document(result.value);
+    for (const path of result.defaults) {
+        const relative = path.split('.').slice(base.length);
+        const node = relative.length ? document.getIn(relative, true) : document.contents;
+        if (isNode(node))
+            node.comment = ` default (not in ${result.file})`;
+    }
+    // D-0154: what a running app reads again, as in the YAML the CLI writes.
+    for (const path of result.reloadable ?? []) {
+        const relative = path.split('.').slice(base.length);
+        if (!relative.length)
+            continue;
+        const parent = relative.length > 1 ? document.getIn(relative.slice(0, -1), true) : document.contents;
+        const pair = isMap(parent)
+            ? parent.items.find((item) => isScalar(item.key) && String(item.key.value) === relative.at(-1))
+            : undefined;
+        const value = pair?.value ?? document.getIn(relative, true);
+        // A block collection gets the mark on its key line; a value after itself.
+        const target = isCollection(value) && pair && isNode(pair.key) ? pair.key : value;
+        if (isNode(target))
+            target.comment = target.comment
+                ? `${target.comment} · ${RELOADABLE_MARK}`
+                : ` ${RELOADABLE_MARK}`;
+    }
+    const lines = [
+        `# ${result.file}${result.path ? ` ${result.path}` : ' options'}: secrets shown as ${SECRET_MARKER}${result.secrets.length ? ` (${result.secrets.join(', ')})` : ' (none here)'}`,
+        document.toString({ lineWidth: 0 }).trimEnd(),
+        ...(result.warnings ?? []).map((warning) => `# warning ${warning.code}: ${warning.hint}`),
+    ];
+    return `${lines.join('\n')}\n`;
+}

package/dist/config-values.d.ts

@@ -0,0 +1,8 @@
+/** A plain object (`{}` or JSON), not an array, a class instance or a null-prototype object. */
+export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Accepts a plain object of JSON values (strings, finite numbers, booleans, null, arrays and plain
+ * objects) within MAX_VALUES values, MAX_DEPTH levels and MAX_BYTES; anything else is
+ * INVALID_INSTALL_DEFAULTS with `details.reason`.
+ */
+export declare function validateDefaults(value: unknown): asserts value is Record<string, unknown>;

package/dist/config-values.js

@@ -0,0 +1,68 @@
+// The bound on a value the CLI writes into dokebi.yaml for a plugin: install plan defaults
+// (install-plan, merge-install-defaults) and `--set` / `config set` values (config-edit). A leaf
+// module (only errors and diagnostics): install-plan used to import it from merge-install-defaults,
+// which imports configuration, which imports project-state, which imports install-plan — a cycle
+// (D-0110 §1).
+import { debug } from './diagnostics.js';
+import { CliError } from './errors.js';
+/** The most values (nodes) one defaults object may hold. */
+const MAX_VALUES = 2000;
+/** The deepest nesting of one defaults object. */
+const MAX_DEPTH = 16;
+/** The largest JSON form of one defaults object. */
+const MAX_BYTES = 1024 * 1024;
+/** Keys that would change a prototype or a YAML merge instead of naming an option. */
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype', '<<']);
+function invalid(reason) {
+    debug('Plugin defaults refused', { reason });
+    throw new CliError('INVALID_INSTALL_DEFAULTS', 'Plugin defaults must be bounded JSON values within their own configuration namespace.', { details: { reason } });
+}
+/** A plain object (`{}` or JSON), not an array, a class instance or a null-prototype object. */
+export function isPlainRecord(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+/**
+ * Accepts a plain object of JSON values (strings, finite numbers, booleans, null, arrays and plain
+ * objects) within MAX_VALUES values, MAX_DEPTH levels and MAX_BYTES; anything else is
+ * INVALID_INSTALL_DEFAULTS with `details.reason`.
+ */
+export function validateDefaults(value) {
+    if (!isPlainRecord(value))
+        invalid('not a plain object');
+    let count = 0;
+    const seen = new WeakSet();
+    const visit = (item, depth) => {
+        count += 1;
+        if (count > MAX_VALUES)
+            invalid(`more than ${MAX_VALUES} values`);
+        if (depth > MAX_DEPTH)
+            invalid(`nested deeper than ${MAX_DEPTH} levels`);
+        if (item === null || typeof item === 'string' || typeof item === 'boolean')
+            return;
+        if (typeof item === 'number' && Number.isFinite(item))
+            return;
+        if (typeof item !== 'object' || item === null)
+            invalid(`a ${typeof item} is not a JSON value`);
+        if (seen.has(item))
+            invalid('a value appears twice (a cycle or a shared object)');
+        seen.add(item);
+        if (Array.isArray(item)) {
+            for (const child of item)
+                visit(child, depth + 1);
+            return;
+        }
+        if (!isPlainRecord(item))
+            invalid('an object that is not a plain object');
+        for (const [key, child] of Object.entries(item)) {
+            if (FORBIDDEN_KEYS.has(key))
+                invalid(`the key ${key} is not allowed`);
+            visit(child, depth + 1);
+        }
+    };
+    visit(value, 0);
+    if (Buffer.byteLength(JSON.stringify(value)) > MAX_BYTES)
+        invalid(`larger than ${MAX_BYTES} bytes as JSON`);
+}