@dokebi/cli 0.4.2 → 0.4.26

package/dist/configuration-scaffold.d.ts

@@ -1 +1,43 @@
+/**
+ * The old names of an object schema (D-0071 `option.alias`, and `option.renamed`, which core
+ * refuses anyway) and the field each one names: `bodyLimit` → [maxBodyBytes],
+ * `maxReconnectAttempts` → [reconnect, maxAttempts]. Core refuses an old name and its field set
+ * together (INVALID_OPTIONS `conflict`), so the CLI writes, fills or shows no default of a field
+ * whose old name is set. Read from the keyword core puts on the old name (`x-dokebi-alias-of`);
+ * a schema from before the keyword by core's default description (OLD_NAME_DESCRIPTION).
+ */
+export declare function aliasTargets(schema: unknown): Map<string, [string] | [string, string]>;
+/**
+ * The places in `value` (an options section) where an old name and the field it sets are both
+ * set, which core refuses at start (INVALID_OPTIONS `conflict`): `{ alias, field }` as dotted
+ * paths below the section (`bodyLimit`, `maxBodyBytes`; `connections.main.reconnectAttempts`,
+ * `connections.main.reconnect.maxAttempts`).
+ */
+export declare function aliasConflicts(value: unknown, schema: unknown): {
+    readonly alias: string;
+    readonly field: string;
+}[];
 export declare function scaffoldConfig(source: string, id: string, schema: Record<string, unknown> | null): string;
+/**
+ * AI-M49 D2: the options of `options.<id>` whose value is still the default the old schema gave
+ * them (the CLI wrote it: `settings add`'s placeholders, a scaffolded default) and whose default
+ * the new schema changed take the new default, at any depth of declared objects. A value set by
+ * hand (anything but the old default) is kept; so is one whose option has no default any more.
+ * `updated`: dotted paths below the section. Like pruneUndeclared for dropped options.
+ */
+export declare function followDefaults(source: string, id: string, previous: Record<string, unknown> | null, schema: Record<string, unknown>): {
+    source: string;
+    updated: string[];
+};
+/**
+ * S-b: the options of `options.<id>` the new schema no longer declares, at any depth (`b.y` of
+ * an object option too, R9). One whose value is still the default the old schema gave it (the CLI
+ * wrote it) is removed; any other is kept and named (`kept`, dotted paths below the section), for
+ * the user to remove (`config unset`) or to declare again. An object that takes any key
+ * (`additionalProperties`, `patternProperties`) is not judged (R10).
+ */
+export declare function pruneUndeclared(source: string, id: string, previous: Record<string, unknown> | null, schema: Record<string, unknown>): {
+    source: string;
+    kept: string[];
+    removed: string[];
+};

package/dist/configuration-scaffold.js

@@ -1,5 +1,8 @@
-import { isMap, isNode, parseDocument } from 'yaml';
+// ALIAS_KEYWORD (`x-dokebi-alias-of`): what core writes on an old option name, its current name.
+import { ALIAS_KEYWORD } from '@dokebi/core';
+import { isMap, isNode, isScalar, parseDocument } from 'yaml';
 import { parseProjectConfig, renderConfig } from './configuration.js';
+import { applyReloadableMarks } from './reloadable.js';
 const SENSITIVE = /(?:password|passwd|secret|token|credential|api.?key|private.?key|connection.?string|url|uri|host|address|endpoint|servers?)/i;
 const ADDRESS = /^(?:[a-z][a-z0-9+.-]*:\/\/|localhost(?::|$)|(?:\d{1,3}\.){3}\d{1,3}(?::|$))/i;
 const FORBIDDEN = new Set(['__proto__', '<<']);
@@ -19,6 +22,98 @@ const composite = (schema) => COMPOSITE.some((key) => Object.hasOwn(schema, key)
 function record(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+/** `name` or `parent.name`, as core's alias targets are. */
+const ALIAS_TARGET = /^([A-Za-z_$][\w$-]*)(?:\.([A-Za-z_$][\w$-]*))?$/;
+/**
+ * The fallback for schemas written before core had ALIAS_KEYWORD (plugin versions already on npm,
+ * such as @dokebi/web 0.4.2): core's two default descriptions of an old name, read only on a
+ * `deprecated: true` property without the keyword. Without it CLIA-3 (a default written beside a
+ * set old name, an app that does not start) comes back on every project with such a plugin.
+ * Remove it once no supported plugin version lacks the keyword.
+ */
+const OLD_NAME_DESCRIPTION = /^(?:Deprecated name of|Renamed to) ([A-Za-z_$][\w$-]*(?:\.[A-Za-z_$][\w$-]*)?); use that key\.$/;
+/**
+ * The old names of an object schema (D-0071 `option.alias`, and `option.renamed`, which core
+ * refuses anyway) and the field each one names: `bodyLimit` → [maxBodyBytes],
+ * `maxReconnectAttempts` → [reconnect, maxAttempts]. Core refuses an old name and its field set
+ * together (INVALID_OPTIONS `conflict`), so the CLI writes, fills or shows no default of a field
+ * whose old name is set. Read from the keyword core puts on the old name (`x-dokebi-alias-of`);
+ * a schema from before the keyword by core's default description (OLD_NAME_DESCRIPTION).
+ */
+export function aliasTargets(schema) {
+    const result = new Map();
+    if (!record(schema) || !record(schema.properties))
+        return result;
+    for (const [key, property] of Object.entries(schema.properties)) {
+        if (!record(property))
+            continue;
+        const target = typeof property[ALIAS_KEYWORD] === 'string'
+            ? property[ALIAS_KEYWORD]
+            : property.deprecated === true && typeof property.description === 'string'
+                ? OLD_NAME_DESCRIPTION.exec(property.description)?.[1]
+                : undefined;
+        if (target === undefined)
+            continue;
+        const match = ALIAS_TARGET.exec(target);
+        if (!match?.[1] || match[1] === key)
+            continue;
+        result.set(key, match[2] ? [match[1], match[2]] : [match[1]]);
+    }
+    return result;
+}
+/**
+ * The places in `value` (an options section) where an old name and the field it sets are both
+ * set, which core refuses at start (INVALID_OPTIONS `conflict`): `{ alias, field }` as dotted
+ * paths below the section (`bodyLimit`, `maxBodyBytes`; `connections.main.reconnectAttempts`,
+ * `connections.main.reconnect.maxAttempts`).
+ */
+export function aliasConflicts(value, schema) {
+    const found = [];
+    const forms = (node, depth = 0) => {
+        if (!record(node) || depth > 8)
+            return [];
+        return [
+            node,
+            ...['anyOf', 'oneOf', 'allOf'].flatMap((key) => Array.isArray(node[key])
+                ? node[key].flatMap((item) => forms(item, depth + 1))
+                : []),
+        ];
+    };
+    const visit = (item, nodes, path, depth) => {
+        if (depth > 16)
+            return;
+        if (Array.isArray(item)) {
+            const items = nodes.flatMap((node) => forms(node.items));
+            for (const [index, child] of item.entries())
+                visit(child, items, [...path, String(index)], depth + 1);
+            return;
+        }
+        if (!record(item))
+            return;
+        for (const node of nodes)
+            for (const [alias, [first, second]] of aliasTargets(node)) {
+                if (!Object.hasOwn(item, alias))
+                    continue;
+                const parent = item[first];
+                const set = second === undefined
+                    ? Object.hasOwn(item, first)
+                    : record(parent) && Object.hasOwn(parent, second);
+                const field = [...path, first, ...(second === undefined ? [] : [second])].join('.');
+                if (set && !found.some((conflict) => conflict.field === field))
+                    found.push({ alias: [...path, alias].join('.'), field });
+            }
+        for (const [key, child] of Object.entries(item)) {
+            const next = nodes.flatMap((node) => {
+                const properties = record(node.properties) ? node.properties : {};
+                return forms(Object.hasOwn(properties, key) ? properties[key] : node.additionalProperties);
+            });
+            if (next.length)
+                visit(child, next, [...path, key], depth + 1);
+        }
+    };
+    visit(value, forms(schema), [], 0);
+    return found;
+}
 function description(value) {
     if (typeof value !== 'string')
         return '';
@@ -69,16 +164,33 @@ export function scaffoldConfig(source, id, schema) {
     parseProjectConfig(source);
     const document = parseDocument(source, { version: '1.2' });
     const base = ['options', id];
+    const empty = document.getIn(base, true);
     if (!document.hasIn(base))
         document.setIn(base, document.createNode({}));
+    else if (isScalar(empty) && empty.value === null) {
+        // An empty section (`vault:` alone) gets its defaults like a missing one; its comment stays.
+        const map = document.createNode({});
+        if (empty.commentBefore)
+            map.commentBefore = empty.commentBefore;
+        if (empty.comment)
+            map.comment = empty.comment;
+        document.setIn(base, map);
+    }
     const lines = [
         'Configuration for ' + id + '. Values marked required must be set before starting.',
     ];
     let visited = 0;
+    /** Document paths (joined by NUL) of fields an old name that is set already gives a value. */
+    const aliased = new Set();
     const visit = (current, path, names, depth, allowDefaults) => {
         if (depth > 12 || visited >= 200)
             return;
         const properties = record(current.properties) ? current.properties : {};
+        // An old name that is set holds the value of its field: no default beside it (core refuses
+        // both together, so an add or upgrade would leave an app that does not start).
+        for (const [alias, target] of aliasTargets(current))
+            if (document.hasIn([...path, alias]))
+                aliased.add([...path, ...target].join('\0'));
         const required = new Set(Array.isArray(current.required)
             ? current.required.filter((value) => typeof value === 'string')
             : []);
@@ -118,6 +230,7 @@ export function scaffoldConfig(source, id, schema) {
             if (canDefault &&
                 writable &&
                 !document.hasIn(keys) &&
+                !aliased.has(keys.join('\0')) &&
                 Object.hasOwn(candidate, 'default') &&
                 safeDefault(candidate.default, candidate, labels) &&
                 !FORBIDDEN.has(name)) {
@@ -127,6 +240,12 @@ export function scaffoldConfig(source, id, schema) {
                         document.setIn(parentPath, document.createNode({}));
                 }
                 document.setIn(keys, document.createNode(candidate.default));
+                // A default object leaves out the field an old name beside it already sets.
+                for (const blocked of aliased) {
+                    const inside = blocked.split('\0');
+                    if (inside.length > keys.length && keys.every((key, index) => inside[index] === key))
+                        document.deleteIn(inside);
+                }
             }
             if (candidate.type === 'object' && record(candidate.properties)) {
                 const present = document.hasIn(keys);
@@ -143,11 +262,146 @@ export function scaffoldConfig(source, id, schema) {
     const node = document.getIn(base, true);
     if (isNode(node)) {
         const marker = '[dokebi:' + id + ']';
-        if (!node.commentBefore?.includes(marker))
-            node.commentBefore =
-                (node.commentBefore ? node.commentBefore + '\n' : '') + marker + '\n' + lines.join('\n');
+        const before = node.commentBefore ?? '';
+        const at = before.indexOf(marker);
+        // The block after the marker is the CLI's: written again from the current schema (S-b: a
+        // changed declaration left the descriptions of options that no longer exist). Only its own
+        // lines are replaced; a note the user wrote after them stays (R8).
+        let after = '';
+        if (at !== -1) {
+            const rest = before.slice(at + marker.length).split('\n');
+            let index = rest[0]?.trim() === '' ? 1 : 0;
+            while (index < rest.length && generatedLine(rest[index]))
+                index++;
+            after = rest.slice(index).join('\n');
+        }
+        node.commentBefore =
+            (at === -1 ? (before ? before + '\n' : '') : before.slice(0, at)) +
+                marker +
+                '\n' +
+                lines.join('\n') +
+                (after ? '\n' + after : '');
     }
+    // D-0154: the options of this plugin a running app reloads get `# reloadable`.
+    if (schema)
+        applyReloadableMarks(document, new Map([[id, schema]]));
     const result = renderConfig(document);
     parseProjectConfig(result);
     return result;
 }
+/** A comment line the CLI's description block is made of. */
+function generatedLine(line) {
+    const text = line.trim();
+    return (text.startsWith('Configuration for ') ||
+        text.startsWith('"') ||
+        text.startsWith('Additional fields:') ||
+        text.startsWith('No options schema is installed'));
+}
+/**
+ * AI-M49 D2: the options of `options.<id>` whose value is still the default the old schema gave
+ * them (the CLI wrote it: `settings add`'s placeholders, a scaffolded default) and whose default
+ * the new schema changed take the new default, at any depth of declared objects. A value set by
+ * hand (anything but the old default) is kept; so is one whose option has no default any more.
+ * `updated`: dotted paths below the section. Like pruneUndeclared for dropped options.
+ */
+export function followDefaults(source, id, previous, schema) {
+    if (!previous)
+        return { source, updated: [] };
+    parseProjectConfig(source);
+    const document = parseDocument(source, { version: '1.2' });
+    const updated = [];
+    const json = (item) => JSON.stringify(isNode(item) ? item.toJSON() : item);
+    const visit = (path, current, before, depth) => {
+        if (depth > 12)
+            return;
+        const map = document.getIn(['options', id, ...path], true);
+        if (!isMap(map))
+            return;
+        const declared = record(current.properties) ? current.properties : {};
+        const old = record(before.properties) ? before.properties : {};
+        for (const pair of [...map.items]) {
+            const key = isScalar(pair.key) ? String(pair.key.value) : undefined;
+            if (key === undefined)
+                continue;
+            const now = declared[key];
+            const was = old[key];
+            if (!record(now) || !record(was) || now.writeOnly === true)
+                continue;
+            const at = [...path, key];
+            if (now.type === 'object' && record(now.properties) && isMap(pair.value)) {
+                visit(at, now, was, depth + 1);
+                continue;
+            }
+            if (!Object.hasOwn(was, 'default') || !Object.hasOwn(now, 'default'))
+                continue;
+            const value = document.getIn(['options', id, ...at]);
+            if (json(value) !== JSON.stringify(was.default))
+                continue;
+            if (JSON.stringify(now.default) === JSON.stringify(was.default))
+                continue;
+            document.setIn(['options', id, ...at], document.createNode(now.default));
+            updated.push(at.join('.'));
+        }
+    };
+    visit([], schema, previous, 0);
+    if (!updated.length)
+        return { source, updated };
+    const result = renderConfig(document);
+    parseProjectConfig(result);
+    return { source: result, updated };
+}
+/**
+ * S-b: the options of `options.<id>` the new schema no longer declares, at any depth (`b.y` of
+ * an object option too, R9). One whose value is still the default the old schema gave it (the CLI
+ * wrote it) is removed; any other is kept and named (`kept`, dotted paths below the section), for
+ * the user to remove (`config unset`) or to declare again. An object that takes any key
+ * (`additionalProperties`, `patternProperties`) is not judged (R10).
+ */
+export function pruneUndeclared(source, id, previous, schema) {
+    parseProjectConfig(source);
+    const document = parseDocument(source, { version: '1.2' });
+    const kept = [];
+    const removed = [];
+    const json = (item) => JSON.stringify(isNode(item) ? item.toJSON() : item);
+    const visit = (path, current, before, depth) => {
+        if (depth > 12)
+            return;
+        const map = document.getIn(['options', id, ...path], true);
+        if (!isMap(map))
+            return;
+        const open = (current.additionalProperties !== undefined && current.additionalProperties !== false) ||
+            current.patternProperties !== undefined;
+        const declared = record(current.properties) ? current.properties : {};
+        const old = before && record(before.properties) ? before.properties : {};
+        for (const pair of [...map.items]) {
+            const key = isScalar(pair.key) ? String(pair.key.value) : undefined;
+            if (key === undefined)
+                continue;
+            const at = [...path, key];
+            const now = declared[key];
+            if (record(now)) {
+                if (now.type === 'object' && record(now.properties))
+                    visit(at, now, record(old[key]) ? old[key] : undefined, depth + 1);
+                continue;
+            }
+            if (open)
+                continue;
+            const was = old[key];
+            const value = document.getIn(['options', id, ...at]);
+            if (record(was) &&
+                Object.hasOwn(was, 'default') &&
+                json(value) === JSON.stringify(was.default)) {
+                document.deleteIn(['options', id, ...at]);
+                removed.push(at.join('.'));
+            }
+            else
+                kept.push(at.join('.'));
+        }
+    };
+    visit([], schema, previous ?? undefined, 0);
+    if (!removed.length)
+        return { source, kept, removed };
+    const result = renderConfig(document);
+    parseProjectConfig(result);
+    return { source: result, kept, removed };
+}

package/dist/configuration.d.ts

@@ -1,19 +1,79 @@
 import { type Document } from 'yaml';
+import { CliError } from './errors.js';
 import { type ProjectConfig } from './project-state.js';
 export declare const CONFIG_FILE = "dokebi.yaml";
 export declare const LEGACY_CONFIG_FILE = "dokebi.json";
 export declare const CONFIG_BACKUP = ".dokebi/dokebi.json.backup";
-export declare const CONFIG_EXAMPLE = "# Copy to dokebi.yaml and keep actual credentials out of Git.\nschemaVersion: 1\noptions:\n  # Log level: debug, info, warn, error or silent. DOKEBI_LOG_LEVEL overrides it.\n  logging:\n    level: info\n    # Per-plugin levels by plugin name, louder or quieter than level:\n    # plugins:\n    #   dokebi-nats: debug\n";
+export declare const CONFIG_EXAMPLE = "# Copy to dokebi.yaml and keep actual credentials out of Git.\nschemaVersion: 1\noptions:\n  # Log level: debug, info, warn, error or silent. DOKEBI_LOG_LEVEL overrides it. Options marked\n  # reloadable apply while the app runs when this file is saved (or npx dokebi reload); the\n  # others need a restart (D-0154).\n  logging:\n    level: info # reloadable\n    # Per-plugin levels by plugin name, louder or quieter than level:\n    # plugins:\n    #   dokebi-nats: debug\n";
 /** The real dokebi.yaml written by init: same shape, its own header. */
-export declare const CONFIG_TEMPLATE = "# Settings for this machine. Not committed to Git; dokebi.example.yaml is the shared sample.\nschemaVersion: 1\noptions:\n  # Log level: debug, info, warn, error or silent. DOKEBI_LOG_LEVEL overrides it.\n  logging:\n    level: info\n    # Per-plugin levels by plugin name, louder or quieter than level:\n    # plugins:\n    #   dokebi-nats: debug\n";
+export declare const CONFIG_TEMPLATE = "# Settings for this machine. Not committed to Git; dokebi.example.yaml is the shared sample.\nschemaVersion: 1\noptions:\n  # Log level: debug, info, warn, error or silent. DOKEBI_LOG_LEVEL overrides it. Options marked\n  # reloadable apply while the app runs when this file is saved (or npx dokebi reload); the\n  # others need a restart (D-0154).\n  logging:\n    level: info # reloadable\n    # Per-plugin levels by plugin name, louder or quieter than level:\n    # plugins:\n    #   dokebi-nats: debug\n";
+/**
+ * D-0151: where records go with @dokebi/logger, written into options.logging when the logger
+ * plugin is added to a project whose logging block has no targets (init adds it by default).
+ */
+export declare const LOGGING_TARGETS = "targets:\n  # JSON lines on stdout: what dokebi start, dokebi verify, containers and systemd collect.\n  - type: stdout\n    when: [production, test, other]\n  # Readable lines for dokebi dev (pino-pretty, loaded only for this target).\n  - type: pretty\n    when: [development]\n  # Rotated files for a server that keeps its own log files (systemd, pm2, a VM): set enabled\n  # to true there. Containers keep stdout. Skipped under dokebi start, which already rotates\n  # .dokebi/run/app.log (withDokebiStart: true writes both).\n  - type: file\n    enabled: false\n    folder: logs\n    file: app.log\n    rotate: { maxBytes: 52428800, frequency: daily }\n    keep: { count: 10, maxAgeMs: 1209600000 }\n";
+/** Adds LOGGING_TARGETS to options.logging when it has no `targets`; else returns the source. */
+export declare function addLoggingTargets(source: string): string;
 /**
  * Serializes a configuration document edited by the CLI. Non-empty mappings and sequences under
  * `options` are written in block style, so schema comments and values stay readable even when the
  * file started from `options: {}`. Values are unchanged; only the layout is normalized.
  */
 export declare function renderConfig(document: Document): string;
-/** Never committed: real settings, the legacy backup and the generated secrets in .env (D-0073). */
+/**
+ * Never committed: the real settings with their secrets (D-0073 addendum 2), the legacy backup,
+ * and .env (still passed to the app by dev, start and verify; dev-infra's database password).
+ */
 export declare const CONFIG_IGNORES: string[];
+/** The settings file of a project the config commands read and change (M50). */
+export interface ConfigTarget {
+    /** As the results name it: project-relative with `/` (`dokebi.yaml`), absolute outside it. */
+    readonly file: string;
+    /** Absolute path. */
+    readonly path: string;
+    /** Inside the project folder (no link out of it): a changing command may write it. */
+    readonly inside: boolean;
+    /** Named by DOKEBI_CONFIG (not the default dokebi.yaml). */
+    readonly fromEnvironment: boolean;
+}
+/**
+ * The file the app reads: DOKEBI_CONFIG when it is set and not empty (an empty value is no value,
+ * D-0154 D4), else dokebi.yaml; a relative path is from the project folder, the folder the app,
+ * `dokebi dev` and dokebi-migrate resolve it from. Links are followed to tell inside from outside.
+ */
+export declare function configTarget(root: string, environment?: NodeJS.ProcessEnv): Promise<ConfigTarget>;
+/**
+ * The settings the app reads, for every CLI reader (doctor, describe, verify, dev, start, the
+ * app URLs, recipes, check): the file configTarget names, bounded like dokebi.yaml and followed
+ * when it is a link. File system errors (ENOENT) are thrown as they are; callers keep their own
+ * handling of a missing file.
+ */
+export declare function readProjectSettings(root: string): Promise<{
+    target: ConfigTarget;
+    source: string;
+}>;
+/**
+ * The source of a settings file DOKEBI_CONFIG names; one that cannot be read (also not there)
+ * is READ_FAILED naming the variable, never dokebi.yaml instead.
+ */
+export declare function readNamedSettings(root: string, target: ConfigTarget): Promise<string>;
+/**
+ * The fix of a missing dokebi.yaml (D-0163, R3 Claude T4 review): it stays out of version control,
+ * so a fresh copy of the project has none, and `config init` writes one from the sample.
+ */
+export declare const FRESH_COPY_FIX = "dokebi.yaml stays out of version control, so a fresh copy of the project (a clone, a CI checkout) has none: run npx dokebi config init in the project folder (it writes dokebi.yaml from dokebi.example.yaml with new generated secrets) and follow its nextSteps";
+/** NOT_A_PROJECT for a missing dokebi.yaml, with FRESH_COPY_FIX. */
+export declare function missingConfig(root: string, message: string): CliError;
+/**
+ * CONFIG_OUTSIDE (UNSAFE_PATH): a changing config command never writes a settings file outside
+ * the project (as with a linked dokebi.yaml), and never changes another file instead.
+ */
+export declare function configOutsideProject(target: ConfigTarget): CliError;
+/** Read-only configuration boundary: runtime also follows this explicit root YAML link.
+ * Never use this for mutation; Transaction and securePath must still reject linked files.
+ * `path`: the file DOKEBI_CONFIG names (configTarget), else dokebi.yaml of `root`.
+ */
+export declare function readProjectConfigSource(root: string, path?: string): Promise<string>;
 export declare function parseProjectConfig(source: string): ProjectConfig;
 export declare function addConfigSection(source: string, id: string): string;
 export declare function migrateConfig(source: string): string;

package/dist/configuration.js

@@ -1,5 +1,9 @@
+import { constants } from 'node:fs';
+import { open, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { ConfigError, parseConfig } from '@dokebi/config';
-import { isMap, parseDocument, stringify, visit } from 'yaml';
+import { isMap, isNode, parseDocument, stringify, visit } from 'yaml';
+import { debug, isMissing } from './diagnostics.js';
 import { CliError } from './errors.js';
 import { readConfig } from './project-state.js';
 export const CONFIG_FILE = 'dokebi.yaml';
@@ -7,9 +11,11 @@ export const LEGACY_CONFIG_FILE = 'dokebi.json';
 export const CONFIG_BACKUP = '.dokebi/dokebi.json.backup';
 /** The logging block of a new project (D-0047): core reads options.logging, not a plugin. */
 const LOGGING_BLOCK = `options:
-  # Log level: debug, info, warn, error or silent. DOKEBI_LOG_LEVEL overrides it.
+  # Log level: debug, info, warn, error or silent. DOKEBI_LOG_LEVEL overrides it. Options marked
+  # reloadable apply while the app runs when this file is saved (or npx dokebi reload); the
+  # others need a restart (D-0154).
   logging:
-    level: info
+    level: info # reloadable
     # Per-plugin levels by plugin name, louder or quieter than level:
     # plugins:
     #   dokebi-nats: debug
@@ -17,6 +23,45 @@ const LOGGING_BLOCK = `options:
 export const CONFIG_EXAMPLE = `# Copy to dokebi.yaml and keep actual credentials out of Git.\nschemaVersion: 1\n${LOGGING_BLOCK}`;
 /** The real dokebi.yaml written by init: same shape, its own header. */
 export const CONFIG_TEMPLATE = `# Settings for this machine. Not committed to Git; dokebi.example.yaml is the shared sample.\nschemaVersion: 1\n${LOGGING_BLOCK}`;
+/**
+ * D-0151: where records go with @dokebi/logger, written into options.logging when the logger
+ * plugin is added to a project whose logging block has no targets (init adds it by default).
+ */
+export const LOGGING_TARGETS = `targets:
+  # JSON lines on stdout: what dokebi start, dokebi verify, containers and systemd collect.
+  - type: stdout
+    when: [production, test, other]
+  # Readable lines for dokebi dev (pino-pretty, loaded only for this target).
+  - type: pretty
+    when: [development]
+  # Rotated files for a server that keeps its own log files (systemd, pm2, a VM): set enabled
+  # to true there. Containers keep stdout. Skipped under dokebi start, which already rotates
+  # .dokebi/run/app.log (withDokebiStart: true writes both).
+  - type: file
+    enabled: false
+    folder: logs
+    file: app.log
+    rotate: { maxBytes: 52428800, frequency: daily }
+    keep: { count: 10, maxAgeMs: 1209600000 }
+`;
+/** Adds LOGGING_TARGETS to options.logging when it has no `targets`; else returns the source. */
+export function addLoggingTargets(source) {
+    const document = parseDocument(source);
+    if (document.hasIn(['options', 'logging', 'targets']))
+        return source;
+    if (!document.hasIn(['options']))
+        document.setIn(['options'], document.createNode({}));
+    const logging = document.getIn(['options', 'logging'], true);
+    if (logging === undefined || logging === null || (isNode(logging) && !isMap(logging)))
+        document.setIn(['options', 'logging'], document.createNode({}));
+    const target = document.getIn(['options', 'logging'], true);
+    if (!isMap(target))
+        return source;
+    const block = parseDocument(LOGGING_TARGETS);
+    target.set('targets', block.get('targets', true));
+    debug('Added the logger targets to options.logging', { targets: 3 });
+    return renderConfig(document);
+}
 /**
  * Serializes a configuration document edited by the CLI. Non-empty mappings and sequences under
  * `options` are written in block style, so schema comments and values stay readable even when the
@@ -39,8 +84,137 @@ export function renderConfig(document) {
     }
     return document.toString();
 }
-/** Never committed: real settings, the legacy backup and the generated secrets in .env (D-0073). */
+/**
+ * Never committed: the real settings with their secrets (D-0073 addendum 2), the legacy backup,
+ * and .env (still passed to the app by dev, start and verify; dev-infra's database password).
+ */
 export const CONFIG_IGNORES = ['dokebi.yaml', 'dokebi.json', '.dokebi/dokebi.json.backup', '.env'];
+/**
+ * The file the app reads: DOKEBI_CONFIG when it is set and not empty (an empty value is no value,
+ * D-0154 D4), else dokebi.yaml; a relative path is from the project folder, the folder the app,
+ * `dokebi dev` and dokebi-migrate resolve it from. Links are followed to tell inside from outside.
+ */
+export async function configTarget(root, environment = process.env) {
+    const base = await realpath(root);
+    const named = environment.DOKEBI_CONFIG;
+    if (!named)
+        return {
+            file: CONFIG_FILE,
+            path: join(base, CONFIG_FILE),
+            inside: true,
+            fromEnvironment: false,
+        };
+    const given = resolve(base, named);
+    let path = given;
+    try {
+        path = await realpath(given);
+    }
+    catch (error) {
+        // A file that is not there yet: its folder decides where it is.
+        if (!isMissing(error))
+            throw error;
+    }
+    const relation = relative(base, path);
+    // R4CA-4: `..staging.yaml` is a file of the project; only a `..` segment leaves it.
+    const inside = relation !== '' &&
+        relation !== '..' &&
+        !relation.startsWith(`..${sep}`) &&
+        !isAbsolute(relation);
+    const file = inside ? relation.split(sep).join('/') : path;
+    debug('Settings file named by DOKEBI_CONFIG', { file, inside });
+    return { file, path, inside, fromEnvironment: true };
+}
+/**
+ * The settings the app reads, for every CLI reader (doctor, describe, verify, dev, start, the
+ * app URLs, recipes, check): the file configTarget names, bounded like dokebi.yaml and followed
+ * when it is a link. File system errors (ENOENT) are thrown as they are; callers keep their own
+ * handling of a missing file.
+ */
+export async function readProjectSettings(root) {
+    const target = await configTarget(root);
+    return { target, source: await readProjectConfigSource(root, target.path) };
+}
+/**
+ * The source of a settings file DOKEBI_CONFIG names; one that cannot be read (also not there)
+ * is READ_FAILED naming the variable, never dokebi.yaml instead.
+ */
+export async function readNamedSettings(root, target) {
+    try {
+        return await readProjectConfigSource(root, target.path);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError('READ_FAILED', `Cannot read ${target.file}, the settings file DOKEBI_CONFIG names`, {
+            cause: error,
+            phase: 'arguments',
+            details: {
+                file: target.file,
+                fix: 'point DOKEBI_CONFIG at the settings file the app reads, or unset it to use dokebi.yaml',
+            },
+        });
+    }
+}
+/**
+ * The fix of a missing dokebi.yaml (D-0163, R3 Claude T4 review): it stays out of version control,
+ * so a fresh copy of the project has none, and `config init` writes one from the sample.
+ */
+export const FRESH_COPY_FIX = 'dokebi.yaml stays out of version control, so a fresh copy of the project (a clone, a CI checkout) has none: run npx dokebi config init in the project folder (it writes dokebi.yaml from dokebi.example.yaml with new generated secrets) and follow its nextSteps';
+/** NOT_A_PROJECT for a missing dokebi.yaml, with FRESH_COPY_FIX. */
+export function missingConfig(root, message) {
+    return new CliError('NOT_A_PROJECT', message, {
+        phase: 'arguments',
+        details: { root, file: CONFIG_FILE, fix: FRESH_COPY_FIX },
+    });
+}
+/**
+ * CONFIG_OUTSIDE (UNSAFE_PATH): a changing config command never writes a settings file outside
+ * the project (as with a linked dokebi.yaml), and never changes another file instead.
+ */
+export function configOutsideProject(target) {
+    return new CliError('UNSAFE_PATH', `DOKEBI_CONFIG names ${target.file}, outside the project: config commands change files of the project only`, {
+        phase: 'arguments',
+        details: {
+            file: target.file,
+            fix: 'edit that file yourself (npx dokebi config show reads it with secrets hidden), or run the command without DOKEBI_CONFIG to change the dokebi.yaml of the project',
+        },
+    });
+}
+/** Read-only configuration boundary: runtime also follows this explicit root YAML link.
+ * Never use this for mutation; Transaction and securePath must still reject linked files.
+ * `path`: the file DOKEBI_CONFIG names (configTarget), else dokebi.yaml of `root`.
+ */
+export async function readProjectConfigSource(root, path) {
+    debug('Reading project configuration', { file: path ?? CONFIG_FILE });
+    const limit = 1_048_576; // Same 1 MiB source bound as @dokebi/config.
+    const handle = await open(path ?? join(root, CONFIG_FILE), constants.O_RDONLY | constants.O_NONBLOCK);
+    try {
+        const stats = await handle.stat();
+        if (!stats.isFile())
+            throw new CliError('READ_FAILED', 'Configuration source must be a regular file');
+        if (stats.size > limit)
+            throw new CliError('INVALID_CONFIG', 'Configuration source exceeds 1 MiB');
+        const bytes = Buffer.alloc(limit + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const { bytesRead } = await handle.read(bytes, length, bytes.length - length, null);
+            if (bytesRead === 0)
+                break;
+            length += bytesRead;
+        }
+        if (length > limit)
+            throw new CliError('INVALID_CONFIG', 'Configuration source exceeds 1 MiB');
+        try {
+            return new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, length));
+        }
+        catch (cause) {
+            throw new CliError('INVALID_CONFIG', 'Configuration source must be valid UTF-8', { cause });
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
 export function parseProjectConfig(source) {
     try {
         return readConfig(parseConfig(source));

package/dist/deployment.d.ts

@@ -0,0 +1,2 @@
+/** Optional, editable deployment files written atomically with a new project. */
+export declare const DEPLOYMENT_FILES: Readonly<Record<string, string>>;