@dokebi/cli 0.4.2 → 0.4.27

package/dist/config-diff.d.ts

@@ -0,0 +1,42 @@
+import { type ConfigShowWarning } from './config-show.js';
+export declare const EXAMPLE_FILE = "dokebi.example.yaml";
+export interface ConfigDiffResult {
+    /** The settings file compared: dokebi.yaml, or the one DOKEBI_CONFIG names (M50). */
+    readonly file: string;
+    readonly example: typeof EXAMPLE_FILE;
+    /** The asked section, or null for every section. */
+    readonly section: string | null;
+    readonly inSync: boolean;
+    readonly onlyInConfig: string[];
+    readonly onlyInExample: string[];
+    readonly different: string[];
+    readonly secrets: string[];
+    readonly exampleSecrets: string[];
+    /**
+     * R4CA-2: what config show warns of either file, once per section (a schema that cannot be read:
+     * its text counts as secret in both files, so its sample values are listed in exampleSecrets;
+     * a section nothing declares). Absent when there is none.
+     */
+    readonly warnings?: ConfigShowWarning[];
+}
+/** A path only in dokebi.yaml and its value without secrets (`sampleAdditions`). */
+export interface SampleAddition {
+    /** Section first: `['dokebi-web', 'port']`. */
+    readonly path: readonly string[];
+    readonly value: unknown;
+}
+export declare function configDiff(root: string, section?: string): Promise<ConfigDiffResult>;
+/**
+ * What `config diff --write` copies into the sample: every path only in dokebi.yaml with the
+ * secrets inside it dropped (a secret leaf; a list with a secret item is left out whole).
+ */
+export declare function sampleAdditions(root: string, configSource: string, exampleSource: string, section?: string, 
+/** The settings file `configSource` is (dokebi.yaml, or the one DOKEBI_CONFIG names). */
+file?: string): Promise<{
+    result: ConfigDiffResult;
+    additions: SampleAddition[];
+    changes: SampleAddition[];
+    prunable: string[][];
+}>;
+/** The result for people: paths only. */
+export declare function configDiffText(result: ConfigDiffResult): string;

package/dist/config-diff.js

@@ -0,0 +1,289 @@
+// `dokebi config diff [<plugin-id>]` (AI-M45): which options dokebi.yaml and dokebi.example.yaml do
+// not share, by path only. An agent keeping the sample in step dumped both files through
+// loadConfig to compare them and printed a database password and two signing secrets into its
+// log. This compares inside the CLI and never puts a value into the result, errors or debug logs.
+//
+// - onlyInConfig / onlyInExample: option paths one file sets and the other does not (a subtree
+//   the other lacks is one path, a list is one value);
+// - different: paths both set to different non-secret values (a sample value is allowed to
+//   differ; the list says where);
+// - secrets: secret paths of dokebi.yaml (as config show hides them, and a subtree only in
+//   dokebi.yaml that holds nothing else). They are never compared and never count as missing
+//   from the sample, which must not hold them;
+// - exampleSecrets: secret paths that hold a value in dokebi.example.yaml (a leak to remove).
+//
+// `--write` (AI-M46: a builder kept the sample in step with a script of its own, since config set
+// writes dokebi.yaml only) copies the paths only in dokebi.yaml into the sample, without their
+// secrets: the same rule that keeps them out of the comparison drops them from the copy.
+// `--write --values` (Studio v2, 10-31) also writes dokebi.yaml's value of every `different` path
+// into the sample, the same way (a secret is never compared, so never copied).
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { configShow, hideCredentials, readSettings, secretOption, } from './config-show.js';
+import { CONFIG_FILE, missingConfig, parseProjectConfig } from './configuration.js';
+import { debug, isMissing } from './diagnostics.js';
+import { envFileWarnings } from './env-file.js';
+import { CliError } from './errors.js';
+export const EXAMPLE_FILE = 'dokebi.example.yaml';
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** A value worth calling set: not null, not '', not an empty list or mapping. */
+function holdsValue(value) {
+    if (value === null || value === undefined || value === '')
+        return false;
+    if (Array.isArray(value))
+        return value.some(holdsValue);
+    if (isObject(value))
+        return Object.values(value).some(holdsValue);
+    return true;
+}
+function same(a, b) {
+    if (Array.isArray(a) || Array.isArray(b) || isObject(a) || isObject(b))
+        return JSON.stringify(a) === JSON.stringify(b);
+    return a === b;
+}
+// Text with credentials (core's maskCredentials: `scheme://user:password@`, `Password=…`) is a
+// secret wherever it is; a `<password>` placeholder is the documented shape (hideCredentials).
+const URL_SCHEME = /^[a-z][a-z0-9+.-]*:\/\//i;
+/** `scheme://user@`: a URL whose user has no password (group 1 is the scheme and slashes). */
+const URL_USER_ONLY = /^([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+@/i;
+/** A placeholder the scaffold writes for a value to fill in: `<set … here …>`. */
+const PLACEHOLDER = /^<[^<>]*>$/;
+/** Text anywhere in the value (what a secret name hides; numbers and booleans show). */
+function holdsText(value) {
+    if (typeof value === 'string')
+        return value !== '';
+    if (Array.isArray(value))
+        return value.some(holdsText);
+    if (isObject(value))
+        return Object.values(value).some(holdsText);
+    return false;
+}
+export async function configDiff(root, section) {
+    // M50: the settings the app reads (DOKEBI_CONFIG, else dokebi.yaml), against the one sample.
+    const settings = await readSettings(root);
+    return (await compare(root, settings.source, await readProjectFile(root, EXAMPLE_FILE), section, settings.target.file)).result;
+}
+/**
+ * What `config diff --write` copies into the sample: every path only in dokebi.yaml with the
+ * secrets inside it dropped (a secret leaf; a list with a secret item is left out whole).
+ */
+export async function sampleAdditions(root, configSource, exampleSource, section, 
+/** The settings file `configSource` is (dokebi.yaml, or the one DOKEBI_CONFIG names). */
+file = CONFIG_FILE) {
+    return compare(root, configSource, exampleSource, section, file);
+}
+async function compare(root, configSource, exampleSource, section, file) {
+    const config = parseProjectConfig(configSource).options;
+    const example = parseProjectConfig(exampleSource).options;
+    // Schema-marked and name-marked secrets of dokebi.yaml, exactly as config show hides them.
+    const shown = await configShow(root, undefined, { source: configSource, file });
+    // The sample's own secrets too (schema-marked ones in a subtree or list item only it has).
+    const sampleShown = await configShow(root, undefined, { source: exampleSource });
+    // A section nobody declares hides every text value (fail closed in config show); in the
+    // sample that would call each old value a secret, so only declared sections count here.
+    // Sections without a schema in either file: there the name of a key is all there is to go on.
+    const unknownSections = new Set([...(shown.warnings ?? []), ...(sampleShown.warnings ?? [])]
+        .filter((warning) => warning.code !== 'OPTIONS_SCHEMA_UNREADABLE')
+        .map((warning) => warning.plugin));
+    const blind = new Set((sampleShown.warnings ?? [])
+        .filter((warning) => warning.code !== 'OPTIONS_SCHEMA_UNREADABLE')
+        .map((warning) => warning.plugin));
+    const sampleSecretPaths = new Set(sampleShown.secrets.filter((path) => !blind.has(path.split('.')[0] ?? '')));
+    // dokebi.yaml is judged fail closed (what config show hides is never compared or copied).
+    const secretPaths = new Set([...shown.secrets, ...sampleSecretPaths]);
+    // R4CA-1: a value of the sample is a leaked secret by the sample's own rule: in a section
+    // nobody declares (one a removed plugin left, D-0153) by name and credentials only. Before,
+    // the fail-closed paths of dokebi.yaml's same section called every plain sample value there a
+    // secret with a value (`remove them`).
+    for (const path of shown.secrets)
+        if (!unknownSections.has(path.split('.')[0] ?? ''))
+            sampleSecretPaths.add(path);
+    const isSecret = (path, value, paths = secretPaths) => {
+        for (let length = path.length; length > 0; length--)
+            if (paths.has(path.slice(0, length).join('.')))
+                return true;
+        const key = path[path.length - 1];
+        // Core's name rule, as config show applies it: `transientLogMaxKeys: 256` is a count, and a
+        // list or object under a secret name is a secret by its text. A section with a schema
+        // already went through config show, which honours `plain`.
+        if (key !== undefined &&
+            !/^\d+$/.test(key) &&
+            unknownSections.has(path[0] ?? '') &&
+            secretOption(key, value) &&
+            (Array.isArray(value) || isObject(value) ? holdsText(value) : holdsValue(value)))
+            return true;
+        return typeof value === 'string' && hideCredentials(value) !== undefined;
+    };
+    const sampleSecret = (path, value) => isSecret(path, value, sampleSecretPaths);
+    // A sample URL without credentials is the documented placeholder of a secret URL, not a leak;
+    // nor is the scaffold's `<set the postgres URL here or run npx dokebi dev-infra>`, also as the
+    // items of a list (a list or object leaks when one of its values does).
+    const leaks = (value) => {
+        if (Array.isArray(value))
+            return value.some(leaks);
+        if (isObject(value))
+            return Object.values(value).some(leaks);
+        if (!holdsValue(value))
+            return false;
+        if (typeof value !== 'string')
+            return true;
+        const text = value.trim();
+        // A user without a password (`postgres://blog@host`) is the documented shape too; core
+        // masks that user in logs and config show hides it, but it is no password in the sample.
+        const withoutUser = text.replace(URL_USER_ONLY, '$1');
+        return !((URL_SCHEME.test(text) && hideCredentials(withoutUser) === undefined) ||
+            PLACEHOLDER.test(text));
+    };
+    const DROP = Symbol('secret');
+    /** The value without its secrets; DROP when nothing but secrets (or nothing) is left. */
+    const scrub = (value, path) => {
+        if (isSecret(path, value))
+            return DROP;
+        if (Array.isArray(value)) {
+            const items = value.map((item, index) => scrub(item, [...path, String(index)]));
+            // Dropping an item would change what the list means: a list with a secret item is left out.
+            return items.includes(DROP) ? DROP : items;
+        }
+        if (isObject(value)) {
+            const kept = {};
+            for (const [key, item] of Object.entries(value)) {
+                const clean = scrub(item, [...path, key]);
+                if (clean !== DROP)
+                    kept[key] = clean;
+            }
+            return Object.keys(kept).length || !Object.keys(value).length ? kept : DROP;
+        }
+        return value;
+    };
+    const additions = [];
+    /** `different` paths with dokebi.yaml's value without secrets (`--write --values`). */
+    const changes = [];
+    /** Secrets with a value in the sample, as paths (what `--prune` always removes). */
+    const prunable = [];
+    /**
+     * Secrets inside a sample value that is compared whole (a list, an object only the sample has):
+     * logging.targets.<n>.token of a network log target. The value itself was not a secret.
+     */
+    const leakedInside = (value, path) => {
+        if (Array.isArray(value)) {
+            for (const [index, item] of value.entries())
+                leakedInside(item, [...path, String(index)]);
+            return;
+        }
+        if (isObject(value)) {
+            for (const [key, item] of Object.entries(value))
+                leakedInside(item, [...path, key]);
+            return;
+        }
+        if (sampleSecret(path, value) && leaks(value)) {
+            exampleSecrets.push(path.join('.'));
+            prunable.push(path);
+        }
+    };
+    const onlyInConfig = [];
+    const onlyInExample = [];
+    const different = [];
+    const secrets = [];
+    const exampleSecrets = [];
+    const walk = (left, right, path, hasLeft, hasRight) => {
+        const at = path.join('.');
+        const secretLeft = hasLeft && isSecret(path, left);
+        const secretRight = hasRight && isSecret(path, right);
+        if (secretLeft || secretRight) {
+            if (hasLeft)
+                secrets.push(at);
+            if (hasRight && sampleSecret(path, right) && leaks(right)) {
+                exampleSecrets.push(at);
+                prunable.push(path);
+            }
+            return;
+        }
+        if (isObject(left) && isObject(right)) {
+            for (const key of new Set([...Object.keys(left), ...Object.keys(right)]))
+                walk(left[key], right[key], [...path, key], Object.hasOwn(left, key), Object.hasOwn(right, key));
+            return;
+        }
+        if (hasLeft && !hasRight) {
+            // A subtree that holds nothing but secrets is a secret too: never missing from the sample.
+            const value = scrub(left, path);
+            if (value === DROP)
+                secrets.push(at);
+            else {
+                onlyInConfig.push(at);
+                additions.push({ path, value });
+            }
+        }
+        else if (hasRight && !hasLeft)
+            onlyInExample.push(at);
+        else if (!same(left, right)) {
+            different.push(at);
+            // A list or mapping is copied without its secrets, or not at all when one item is secret.
+            const value = scrub(left, path);
+            if (value !== DROP)
+                changes.push({ path, value });
+        }
+        if (hasRight && (Array.isArray(right) || isObject(right)))
+            leakedInside(right, path);
+    };
+    for (const name of new Set([...Object.keys(config), ...Object.keys(example)])) {
+        if (section !== undefined && name !== section)
+            continue;
+        walk(config[name], example[name], [name], Object.hasOwn(config, name), Object.hasOwn(example, name));
+    }
+    const warnings = new Map();
+    for (const warning of [
+        // R4CA-3: what the project's .env sets that neither the app nor this command reads.
+        ...envFileWarnings(root).map(({ code, path, hint }) => ({ code, path, hint })),
+        ...(shown.warnings ?? []),
+        ...(sampleShown.warnings ?? []),
+    ])
+        if (section === undefined || warning.plugin === undefined || warning.plugin === section)
+            warnings.set(`${warning.code} ${warning.plugin ?? warning.path}`, warning);
+    const result = {
+        file,
+        example: EXAMPLE_FILE,
+        section: section ?? null,
+        inSync: !onlyInConfig.length && !onlyInExample.length && !exampleSecrets.length,
+        onlyInConfig,
+        onlyInExample,
+        different,
+        secrets,
+        exampleSecrets,
+        ...(warnings.size ? { warnings: [...warnings.values()] } : {}),
+    };
+    debug('Configuration compared with the sample', {
+        section: section ?? null,
+        onlyInConfig: onlyInConfig.length,
+        onlyInExample: onlyInExample.length,
+        different: different.length,
+        secrets: secrets.length,
+        exampleSecrets: exampleSecrets.length,
+    });
+    return { result, additions, changes, prunable };
+}
+async function readProjectFile(root, file) {
+    try {
+        return await readFile(join(root, file), 'utf8');
+    }
+    catch (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('EXAMPLE_MISSING', `No ${file} to compare with (it is the sample of dokebi.yaml without secrets)`, { phase: 'arguments', details: { root, file } });
+        throw new CliError('READ_FAILED', `Cannot read ${file}`, { cause: error });
+    }
+}
+/** The result for people: paths only. */
+export function configDiffText(result) {
+    const list = (label, paths) => paths.length ? [`${label} [${paths.length}]:`, ...paths.map((path) => `  ${path}`)] : [];
+    const lines = [
+        `# ${result.file} against ${result.example}${result.section ? ` (${result.section})` : ''}: ${result.inSync ? 'in step' : 'not in step'}; values are never shown`,
+        ...list(`only in ${result.file}`, result.onlyInConfig),
+        ...list(`only in ${result.example}`, result.onlyInExample),
+        ...list('set in both to different values', result.different),
+        ...list(`secrets of ${result.file} (never compared; the sample must not hold them)`, result.secrets),
+        ...list(`secrets with a value in ${result.example} (remove them)`, result.exampleSecrets),
+        ...(result.warnings ?? []).map((warning) => `# warning ${warning.code}: ${warning.hint}`),
+    ];
+    return `${lines.join('\n')}\n`;
+}

package/dist/config-edit.d.ts

@@ -1,3 +1,4 @@
+import { type Document } from 'yaml';
 import type { ConfigChange } from './plugin-lifecycle.js';
 export interface SetOption {
     readonly path: string[];
@@ -9,9 +10,41 @@ export interface Warning {
 }
 /** Parses one `--set <path>=<value>` argument. Values are JSON when parseable, otherwise text. */
 export declare function parseSetOption(argument: string): SetOption;
-export declare function setWarnings(sets: readonly SetOption[]): Warning[];
+/**
+ * A path whose list items are named turned into item indexes: `targets.studio.token` is
+ * `targets.<index>.token` of the item of `targets` whose `name` is studio (else, for an item
+ * without a name, whose `type` is). An index stays an index. `undefined` when a named item or an
+ * index is not there (callers decide: an error for set, not set for unset). D-0151 follow-up:
+ * the targets of options.logging are a list.
+ */
+export declare function resolveItems(document: Document, path: readonly string[]): string[] | undefined;
+/**
+ * A path with each list index named the way resolveItems finds the item (`name`, else `type` of
+ * an item without a name), so the same item is found in another file whose list has another
+ * order. `undefined` when an indexed item has neither (it cannot be found elsewhere for sure);
+ * the path as given when the item is not in this file.
+ */
+export declare function namedItems(source: string, id: string, path: readonly string[]): string[] | undefined;
 export declare function applySetOptions(source: string, id: string, sets: readonly SetOption[]): string;
-export declare function applyConfigChanges(source: string, id: string, changes: readonly ConfigChange[]): string;
+/** The value at `<id>.<path>` of a dokebi.yaml source (list items by name or index), or undefined. */
+export declare function optionAtPath(source: string, id: string, path: readonly string[]): unknown;
+/**
+ * `dokebi config unset` (D-0153): removes `options.<id>.<path>` for each path that is set, and
+ * the mappings this leaves empty below the plugin section (the section itself stays). Returns
+ * the new source and the paths that were set; a source without any of them comes back as it is.
+ * Values are never read out.
+ */
+export declare function applyUnsetOptions(source: string, id: string, paths: readonly (readonly string[])[]): {
+    source: string;
+    removed: string[][];
+};
+/** A manifest's change, or `set` (the CLI's own: replaces a value, `config diff --values`). */
+export type ConfigEdit = ConfigChange | {
+    readonly op: 'set';
+    readonly path: readonly string[];
+    readonly value: unknown;
+};
+export declare function applyConfigChanges(source: string, id: string, changes: readonly ConfigEdit[]): string;
 /**
  * Removes `options.<host>.apps.<app>` (D-0061 per-app settings of the apps host, D-0070) and the
  * `apps` map when it is left empty; a source without that entry is returned unchanged. The host

package/dist/config-edit.js

@@ -1,11 +1,10 @@
 import { isDeepStrictEqual } from 'node:util';
-import { isMap, isNode, isScalar, parseDocument } from 'yaml';
+import { isMap, isNode, isScalar, isSeq, parseDocument } from 'yaml';
+import { validateDefaults } from './config-values.js';
 import { parseProjectConfig, renderConfig } from './configuration.js';
 import { CliError } from './errors.js';
-import { validateDefaults } from './merge-install-defaults.js';
 const SEGMENT = /^[A-Za-z0-9_-]{1,64}$/;
 const FORBIDDEN = new Set(['__proto__', 'constructor', 'prototype', '<<']);
-const SECRET = /(password|passwd|secret|token|credential|api.?key|private.?key)/i;
 /** Parses one `--set <path>=<value>` argument. Values are JSON when parseable, otherwise text. */
 export function parseSetOption(argument) {
     const index = argument.indexOf('=');
@@ -20,25 +19,93 @@ export function parseSetOption(argument) {
         value = JSON.parse(text);
     }
     catch {
-        /* plain text value */
+        // dokebi-check: allow empty-catch a value that is not JSON is the plain text the user typed
     }
     try {
         validateDefaults({ value });
     }
-    catch {
-        throw new CliError('INVALID_SET', 'Invalid --set value');
+    catch (cause) {
+        throw new CliError('INVALID_SET', 'Invalid --set value', { cause });
     }
     return { path, value };
 }
-export function setWarnings(sets) {
-    return sets
-        .filter((set) => set.path.some((key) => SECRET.test(key)))
-        .map((set) => ({ code: 'SECRET_ON_COMMAND_LINE', path: set.path.join('.') }));
+const INDEX = /^(?:0|[1-9][0-9]{0,5})$/;
+/**
+ * A path whose list items are named turned into item indexes: `targets.studio.token` is
+ * `targets.<index>.token` of the item of `targets` whose `name` is studio (else, for an item
+ * without a name, whose `type` is). An index stays an index. `undefined` when a named item or an
+ * index is not there (callers decide: an error for set, not set for unset). D-0151 follow-up:
+ * the targets of options.logging are a list.
+ */
+export function resolveItems(document, path) {
+    const result = [];
+    for (const segment of path) {
+        const node = document.getIn(result, true);
+        if (!isSeq(node)) {
+            result.push(segment);
+            continue;
+        }
+        let index = INDEX.test(segment)
+            ? Number(segment)
+            : node.items.findIndex((item) => isMap(item) && item.get('name') === segment);
+        if (index < 0)
+            index = node.items.findIndex((item) => isMap(item) && !item.has('name') && item.get('type') === segment);
+        if (index < 0 || index >= node.items.length)
+            return undefined;
+        result.push(String(index));
+    }
+    return result;
+}
+/**
+ * A path with each list index named the way resolveItems finds the item (`name`, else `type` of
+ * an item without a name), so the same item is found in another file whose list has another
+ * order. `undefined` when an indexed item has neither (it cannot be found elsewhere for sure);
+ * the path as given when the item is not in this file.
+ */
+export function namedItems(source, id, path) {
+    const document = parseDocument(source, { version: '1.2' });
+    const named = [];
+    const walked = ['options', id];
+    for (const segment of path) {
+        const node = document.getIn(walked, true);
+        if (isSeq(node) && INDEX.test(segment)) {
+            const item = node.items[Number(segment)];
+            if (item === undefined)
+                return [...path];
+            const name = isMap(item) ? item.get('name') : undefined;
+            const type = isMap(item) && !item.has('name') ? item.get('type') : undefined;
+            if (typeof name === 'string')
+                named.push(name);
+            else if (typeof type === 'string')
+                named.push(type);
+            else
+                return undefined;
+        }
+        else
+            named.push(segment);
+        walked.push(segment);
+    }
+    return named;
+}
+/** The names of the items of the list a path goes through (for the error of a missing one). */
+function itemNames(document, path) {
+    for (let length = path.length - 1; length > 0; length--) {
+        const prefix = resolveItems(document, path.slice(0, length));
+        const node = prefix ? document.getIn(prefix, true) : undefined;
+        if (!isSeq(node))
+            continue;
+        return node.items.map((item, index) => isMap(item) ? String(item.get('name') ?? item.get('type') ?? index) : String(index));
+    }
+    return [];
 }
 function ensureMap(document, path, code) {
     for (let length = 1; length <= path.length; length++) {
         const current = path.slice(0, length);
         const node = document.getIn(current, true);
+        // An item of a list (an index resolveItems found) is crossed, never created.
+        const next = path[length];
+        if (isSeq(node) && next !== undefined && INDEX.test(next) && Number(next) < node.items.length)
+            continue;
         if (!document.hasIn(current) || (isScalar(node) && node.value === null))
             document.setIn(current, document.createNode({}));
         else if (!isMap(node))
@@ -68,12 +135,77 @@ export function applySetOptions(source, id, sets) {
     }
     return edit(source, id, (document) => {
         for (const set of sets) {
-            const path = ['options', id, ...set.path];
+            const wanted = ['options', id, ...set.path];
+            const path = resolveItems(document, wanted);
+            if (!path)
+                throw new CliError('INVALID_SET', `No list item at ${[id, ...set.path].join('.')}`, {
+                    details: {
+                        path: [id, ...set.path].join('.'),
+                        items: itemNames(document, wanted),
+                        fix: 'name an item of the list by its name (else its type) or by its index, as npx dokebi config show lists them',
+                    },
+                });
             ensureMap(document, path.slice(0, -1), 'INVALID_SET');
             document.setIn(path, document.createNode(set.value));
         }
     });
 }
+/** The value at `<id>.<path>` of a dokebi.yaml source (list items by name or index), or undefined. */
+export function optionAtPath(source, id, path) {
+    const document = parseDocument(source, { version: '1.2' });
+    const resolved = resolveItems(document, ['options', id, ...path]);
+    if (!resolved || !document.hasIn(resolved))
+        return undefined;
+    const value = document.getIn(resolved, false);
+    return isNode(value) ? value.toJSON() : value;
+}
+/**
+ * `dokebi config unset` (D-0153): removes `options.<id>.<path>` for each path that is set, and
+ * the mappings this leaves empty below the plugin section (the section itself stays). Returns
+ * the new source and the paths that were set; a source without any of them comes back as it is.
+ * Values are never read out.
+ */
+export function applyUnsetOptions(source, id, paths) {
+    const seen = new Set();
+    for (const path of paths) {
+        const key = path.join('.');
+        if (seen.has(key))
+            throw new CliError('INVALID_SET', 'Repeated config unset path');
+        seen.add(key);
+    }
+    const document = parseDocument(source, { version: '1.2' });
+    // List items may be named (resolveItems); one that is not there is a path that is not set.
+    const present = [];
+    for (const path of paths) {
+        const full = resolveItems(document, ['options', id, ...path]);
+        if (full && document.hasIn(full))
+            present.push({ path: [...path], full });
+    }
+    const removed = present.map((item) => item.path);
+    if (!removed.length)
+        return { source, removed };
+    // Later list items first, so removing one never shifts the index of another. One item named
+    // twice (`targets.studio` and `targets.3`) is removed once: removing it again would take the
+    // item that moved into its place.
+    const order = [
+        ...new Map(present.map((item) => [item.full.join('\0'), item.full])).values(),
+    ].sort((a, b) => b.join('\0').localeCompare(a.join('\0'), 'en', { numeric: true }));
+    const result = edit(source, id, (target) => {
+        for (const full of order) {
+            // A path below one removed earlier in this call is gone already.
+            if (!target.hasIn(full))
+                continue;
+            target.deleteIn(full);
+            for (let length = full.length - 1; length > 2; length--) {
+                const parent = target.getIn(full.slice(0, length), true);
+                if (!isMap(parent) || parent.items.length)
+                    break;
+                target.deleteIn(full.slice(0, length));
+            }
+        }
+    });
+    return { source: result, removed };
+}
 export function applyConfigChanges(source, id, changes) {
     if (!changes.length)
         return source;
@@ -98,9 +230,9 @@ export function applyConfigChanges(source, id, changes) {
                 if (document.hasIn(path))
                     document.deleteIn(path);
             }
-            else if (change.op === 'default' && change.path) {
+            else if ((change.op === 'default' || change.op === 'set') && change.path) {
                 const path = [...base, ...change.path];
-                if (document.hasIn(path))
+                if (change.op === 'default' && document.hasIn(path))
                     continue;
                 validateDefaults({ value: change.value });
                 ensureMap(document, path.slice(0, -1), 'UPGRADE_CONFIG_CONFLICT');

package/dist/config-init.d.ts

@@ -0,0 +1,15 @@
+/** The option keys of a validator issue's instancePath (`/connections/main` → connections, main). */
+export declare function issuePathOf(instancePath: string): string[];
+/**
+ * Whether the option at `path` of a section is a secret: marked so in its schema (`writeOnly`,
+ * `x-dokebi-secret: true`), or named like one by core's rule unless the schema marks it plain
+ * (`x-dokebi-secret: false`), as `config show` hides it.
+ */
+export declare function secretInSchema(schema: unknown, path: readonly string[]): boolean;
+/** A sample value still to fill in (`<set the postgres URL here or run npx dokebi dev-infra>`). */
+export declare function isPlaceholder(value: unknown): boolean;
+/**
+ * The option paths whose value is a placeholder of the sample (`<set the postgres URL here or
+ * run npx dokebi dev-infra>`, `<password>`), as `section.key.key`; list items by index.
+ */
+export declare function placeholderPaths(options: Record<string, unknown>): string[];

package/dist/config-init.js

@@ -0,0 +1,61 @@
+// Pure parts of `dokebi config init` (D-0163): which missing options are secrets the CLI may
+// generate, and which sample values are placeholders still to fill.
+import { secretOption } from './config-show.js';
+/** The option keys of a validator issue's instancePath (`/connections/main` → connections, main). */
+export function issuePathOf(instancePath) {
+    return instancePath
+        .split('/')
+        .slice(1)
+        .map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'));
+}
+function propertySchema(node, key) {
+    if (!node || typeof node !== 'object')
+        return undefined;
+    const properties = node.properties;
+    if (!properties || typeof properties !== 'object')
+        return undefined;
+    const found = properties[key];
+    return found && typeof found === 'object' ? found : undefined;
+}
+/**
+ * Whether the option at `path` of a section is a secret: marked so in its schema (`writeOnly`,
+ * `x-dokebi-secret: true`), or named like one by core's rule unless the schema marks it plain
+ * (`x-dokebi-secret: false`), as `config show` hides it.
+ */
+export function secretInSchema(schema, path) {
+    let node = schema;
+    for (const key of path)
+        node = propertySchema(node, key);
+    const marked = node;
+    if (marked?.['x-dokebi-secret'] === false)
+        return false;
+    if (marked?.writeOnly === true || marked?.['x-dokebi-secret'] === true)
+        return true;
+    return secretOption(path.at(-1) ?? '', 'text');
+}
+/** A sample value still to fill in (`<set the postgres URL here or run npx dokebi dev-infra>`). */
+export function isPlaceholder(value) {
+    return typeof value === 'string' && /^<[^<>]+>$/.test(value.trim());
+}
+/**
+ * The option paths whose value is a placeholder of the sample (`<set the postgres URL here or
+ * run npx dokebi dev-infra>`, `<password>`), as `section.key.key`; list items by index.
+ */
+export function placeholderPaths(options) {
+    const found = [];
+    const walk = (value, path) => {
+        if (typeof value === 'string') {
+            if (isPlaceholder(value))
+                found.push(path.join('.'));
+        }
+        else if (Array.isArray(value)) {
+            for (const [index, item] of value.entries())
+                walk(item, [...path, `${index}`]);
+        }
+        else if (value && typeof value === 'object')
+            for (const [key, item] of Object.entries(value))
+                walk(item, [...path, key]);
+    };
+    walk(options, []);
+    return found;
+}