@dokebi/cli 0.4.1 → 0.4.26

package/dist/config-paths.js

@@ -0,0 +1,82 @@
+// What a config command changed, by option path and file (Studio v2 report, 2026-10-24): before
+// d48f77b1 `config unset dokebi-logger.redact …` removed seven options of the live
+// options.logging and answered only `changed: [dokebi.yaml, dokebi.example.yaml]`. The result now
+// names every option path a file gained, lost or changed (never a value), and a change outside
+// what the command was asked for is refused before anything is written (PATH_MISMATCH).
+import { parseDocument } from 'yaml';
+import { resolveItems } from './config-edit.js';
+import { parseProjectConfig } from './configuration.js';
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** The leaf paths (a scalar or a list each) that differ between the options of two sources. */
+export function optionChanges(before, after) {
+    const removed = [];
+    const set = [];
+    const added = [];
+    const leaves = (value, path, into) => {
+        if (isObject(value) && Object.keys(value).length)
+            for (const [key, item] of Object.entries(value))
+                leaves(item, [...path, key], into);
+        else
+            into.push(path.join('.'));
+    };
+    const walk = (left, right, path, hasLeft, hasRight) => {
+        if (hasLeft && !hasRight)
+            return leaves(left, path, removed);
+        if (hasRight && !hasLeft)
+            return leaves(right, path, added);
+        if (isObject(left) &&
+            isObject(right) &&
+            (Object.keys(left).length || Object.keys(right).length)) {
+            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 (JSON.stringify(left) !== JSON.stringify(right))
+            set.push(path.join('.'));
+    };
+    const a = parseProjectConfig(before).options;
+    const b = parseProjectConfig(after).options;
+    for (const key of new Set([...Object.keys(a), ...Object.keys(b)]))
+        walk(a[key], b[key], [key], Object.hasOwn(a, key), Object.hasOwn(b, key));
+    return { removed, set, added };
+}
+/** Each file's changes, the files nothing changed in left out. */
+export function filePaths(files) {
+    const result = {};
+    for (const [file, before, after] of files) {
+        if (before === undefined || after === undefined || before === after)
+            continue;
+        const changes = optionChanges(before, after);
+        if (changes.removed.length || changes.set.length || changes.added.length)
+            result[file] = changes;
+    }
+    return result;
+}
+/**
+ * A requested path as the files spell it: `<section>.<path>` with named list items turned into
+ * indexes in `source` (`logging.targets.studio.token` → `logging.targets.3.token`); as typed when
+ * the item is not there.
+ */
+export function requestedPath(source, section, path) {
+    const resolved = resolveItems(parseDocument(source, { version: '1.2' }), [
+        'options',
+        section,
+        ...path,
+    ]);
+    return resolved ? resolved.slice(1) : [section, ...path];
+}
+/**
+ * The changed paths outside the requested ones. A changed path is asked for when it is a
+ * requested path or below one, or when it is a list a requested path goes through (a list is
+ * compared whole).
+ */
+export function outsideRequested(changes, requested) {
+    const asked = requested.map((path) => path.join('.'));
+    const inside = (changed) => asked.some((path) => changed === path || changed.startsWith(`${path}.`) || path.startsWith(`${changed}.`));
+    const outside = new Set();
+    for (const paths of Object.values(changes))
+        for (const changed of [...paths.removed, ...paths.set, ...paths.added])
+            if (!inside(changed))
+                outside.add(changed);
+    return [...outside];
+}

package/dist/config-show.d.ts

@@ -0,0 +1,82 @@
+import { type ConfigTarget } from './configuration.js';
+/** What a hidden value is replaced with. */
+export declare const SECRET_MARKER = "<secret: set>";
+/** What the password of a URL is replaced with: `scheme://user:<secret>@host`. */
+export declare const URL_SECRET_MARKER = "<secret>";
+/**
+ * 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 declare function hideCredentials(text: string): string | undefined;
+export interface ConfigShowWarning {
+    readonly code: 'OPTIONS_SCHEMA_UNREADABLE' | 'UNKNOWN_PLUGIN' | 'UNDECLARED_SECTION' | 'ENV_DOKEBI_CONFIG_IGNORED';
+    /** The section it is about (absent for ENV_DOKEBI_CONFIG_IGNORED). */
+    readonly plugin?: string;
+    /** ENV_DOKEBI_CONFIG_IGNORED: `.env:<line>`. */
+    readonly path?: string;
+    readonly hint: string;
+}
+export interface ConfigShowResult {
+    /** The settings file shown: dokebi.yaml, or the file DOKEBI_CONFIG names (M50). */
+    readonly file: string;
+    /** The asked `<plugin-id>[.<path>]`, or null for every section. */
+    readonly path: string | null;
+    /** The options (or the asked part), secrets replaced by SECRET_MARKER. */
+    readonly value: unknown;
+    /** Option paths shown with their schema default because dokebi.yaml does not set them. */
+    readonly defaults: string[];
+    /** Option paths whose value was hidden (a whole list of secrets is one path). */
+    readonly secrets: string[];
+    /**
+     * D-0154: option paths a running app reads again (the topmost marked key; everything under it
+     * is reloadable too). Any other change needs a restart.
+     */
+    readonly reloadable: string[];
+    readonly warnings?: ConfigShowWarning[];
+}
+/**
+ * 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 declare function secretOption(key: string, value: unknown): boolean;
+/**
+ * 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 declare function commandLineSecret(path: readonly string[], value: unknown, schema: unknown): boolean;
+/**
+ * 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 declare function readSettings(root: string): Promise<{
+    target: ConfigTarget;
+    source: string;
+}>;
+/** `dokebi config show [<plugin-id>[.<path>]]`: options with secrets hidden. */
+export declare function configShow(root: string, target?: {
+    readonly section: string;
+    readonly path: readonly string[];
+}, 
+/**
+ * Another document than the settings file (config diff reads the sample's secrets with it, and
+ * the settings its transaction read).
+ */
+from?: {
+    readonly source: string;
+    readonly file?: string;
+}): Promise<ConfigShowResult>;
+/** The result for people: YAML, defaults marked with a comment, secrets already hidden. */
+export declare function configShowText(result: ConfigShowResult): string;