@dokebi/cli 0.4.2 → 0.4.27

package/dist/config-paths.d.ts

@@ -0,0 +1,22 @@
+/** The option paths of one file a command changed: dotted, below `options`; a list is one path. */
+export interface OptionPaths {
+    readonly removed: string[];
+    readonly set: string[];
+    readonly added: string[];
+}
+/** The leaf paths (a scalar or a list each) that differ between the options of two sources. */
+export declare function optionChanges(before: string, after: string): OptionPaths;
+/** Each file's changes, the files nothing changed in left out. */
+export declare function filePaths(files: readonly (readonly [string, string | undefined, string | undefined])[]): Record<string, OptionPaths>;
+/**
+ * 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 declare function requestedPath(source: string, section: string, path: readonly string[]): string[];
+/**
+ * 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 declare function outsideRequested(changes: Readonly<Record<string, OptionPaths>>, requested: readonly (readonly string[])[]): string[];

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-secrets.d.ts

@@ -0,0 +1,46 @@
+import { type ConfigObject } from '@dokebi/config';
+export interface SecretEntry {
+    /** The option path (`dokebi-db.connections.main.url`). */
+    readonly path: string;
+    /** Where it is set: dokebi.yaml (or the file DOKEBI_CONFIG names), the secrets file, or nowhere. */
+    readonly source: 'config' | 'secrets' | null;
+    /** In the document's `secrets` list: the app refuses to start without it. */
+    readonly listed: boolean;
+    /** A secret a plugin's install plan generates (dokebi-session.secrets): it needs one. */
+    readonly required: boolean;
+}
+export interface ConfigSecretsWarning {
+    readonly code: 'SECRET_IN_CONFIG_FILE' | 'SECRETS_PLAN_UNREADABLE';
+    readonly path: string;
+    readonly hint: string;
+}
+export interface ConfigSecretsResult {
+    /** The settings file read: dokebi.yaml, or the file DOKEBI_CONFIG names. */
+    readonly file: string;
+    /** The file DOKEBI_SECRETS names, or null. */
+    readonly secretsFile: string | null;
+    /** The document's `secrets` list. */
+    readonly listed: readonly string[];
+    readonly secrets: readonly SecretEntry[];
+    /** Listed or required paths without a value (a placeholder counts as none). */
+    readonly missing: readonly string[];
+    readonly warnings?: readonly ConfigSecretsWarning[];
+    readonly nextSteps?: ReadonlyArray<{
+        command: string;
+        why: string;
+    }>;
+}
+/**
+ * The secrets the installed plugins generate at install (their plans' `configSecrets`, such as
+ * `dokebi-session.secrets`): each plugin needs one to start.
+ */
+export declare function requiredSecretPaths(root: string, options: ConfigObject): Promise<{
+    paths: string[];
+    unreadable: string[];
+}>;
+/** The warning for plugins whose generated secrets could not be read (their install modules). */
+export declare function unreadableWarning(plugins: readonly string[]): ConfigSecretsWarning[];
+/** `dokebi config secrets`: secret paths by name, where each is set, and the missing ones. */
+export declare function configSecrets(root: string, env?: NodeJS.ProcessEnv): Promise<ConfigSecretsResult>;
+/** The result for people: one line per path. */
+export declare function configSecretsText(result: ConfigSecretsResult): string;

package/dist/config-secrets.js

@@ -0,0 +1,187 @@
+// `dokebi config secrets` (D-0184): the secret option paths the app needs, by name only — where
+// each one comes from (dokebi.yaml or the secrets file DOKEBI_SECRETS names) and which are
+// missing. Values are never read into the result.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { applySecrets, ConfigError, parseConfig, readConfigFile, SECRETS_VARIABLE, } from '@dokebi/config';
+import { isPlaceholder } from './config-init.js';
+import { configShow, readSettings } from './config-show.js';
+import { debug } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { parseObject } from './filesystem.js';
+import { optionsKey } from './manifest.js';
+import { dependencyMap } from './npm-client.js';
+import { planLifecycle } from './plugin-lifecycle.js';
+import { readState } from './project-state.js';
+function valueAt(options, path) {
+    let value = options;
+    for (const key of path) {
+        if (Array.isArray(value) && /^\d+$/.test(key))
+            value = value[Number(key)];
+        else if (value && typeof value === 'object' && Object.hasOwn(value, key))
+            value = value[key];
+        else
+            return undefined;
+    }
+    return value;
+}
+function empty(value) {
+    return (value === undefined ||
+        value === null ||
+        value === '' ||
+        isPlaceholder(value) ||
+        (Array.isArray(value) && (value.length === 0 || value.every(isPlaceholder))) ||
+        (typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0));
+}
+/** The same failure as the app's start, as a CLI error with the paths and no values. */
+function configFailure(error) {
+    return new CliError(error.code, error.message, {
+        phase: 'arguments',
+        details: {
+            issues: error.issues.map((issue) => ({
+                path: issue.instancePath
+                    .split('/')
+                    .slice(1)
+                    .map((key) => key.replaceAll('~1', '/').replaceAll('~0', '~'))
+                    .join('.'),
+                keyword: issue.keyword,
+            })),
+            fix: error.fix,
+        },
+    });
+}
+/**
+ * The secrets the installed plugins generate at install (their plans' `configSecrets`, such as
+ * `dokebi-session.secrets`): each plugin needs one to start.
+ */
+export async function requiredSecretPaths(root, options) {
+    const state = readState(parseObject(await readFile(join(root, '.dokebi/state.json'), 'utf8'), 'state'));
+    const projectPackages = Object.keys(dependencyMap(parseObject(await readFile(join(root, 'package.json'), 'utf8'), 'package.json')));
+    const paths = [];
+    // A plugin whose install module cannot run here (not installed: npm install) is named, so the
+    // list is never silently short.
+    const unreadable = [];
+    for (const plugin of state.plugins) {
+        let plan;
+        try {
+            plan = await planLifecycle({ base: root, plugin, options, plugins: state.plugins, projectPackages }, 'planInstall');
+        }
+        catch (error) {
+            if (!(error instanceof CliError) || error.code !== 'PLUGIN_INSTALL_FAILED')
+                throw error;
+            unreadable.push(plugin.id);
+            continue;
+        }
+        for (const path of plan.configSecrets)
+            paths.push([optionsKey(plugin), ...path].join('.'));
+    }
+    return { paths, unreadable };
+}
+/** The warning for plugins whose generated secrets could not be read (their install modules). */
+export function unreadableWarning(plugins) {
+    return plugins.length
+        ? [
+            {
+                code: 'SECRETS_PLAN_UNREADABLE',
+                path: plugins.join(', '),
+                hint: 'the install modules of these plugins could not run (are their packages installed? npm install), so the secrets they generate are not in this list',
+            },
+        ]
+        : [];
+}
+/** `dokebi config secrets`: secret paths by name, where each is set, and the missing ones. */
+export async function configSecrets(root, env = process.env) {
+    const { target, source } = await readSettings(root);
+    let document;
+    try {
+        document = parseConfig(source);
+    }
+    catch (error) {
+        if (error instanceof ConfigError)
+            throw configFailure(error);
+        throw error;
+    }
+    const secretsFile = env[SECRETS_VARIABLE] || undefined;
+    // The merged options (conflicts and an unsafe file refuse as at start); the list is checked
+    // below, so a missing listed secret is reported instead of thrown.
+    let merged = document.options;
+    let secretsText;
+    let secretOptions;
+    if (secretsFile !== undefined) {
+        try {
+            merged = (await applySecrets({ schemaVersion: 1, options: document.options }, secretsFile))
+                .options;
+            secretsText = await readConfigFile(secretsFile);
+            secretOptions = parseConfig(secretsText).options;
+        }
+        catch (error) {
+            if (error instanceof ConfigError)
+                throw configFailure(error);
+            throw error;
+        }
+    }
+    const fromConfig = new Set((await configShow(root, undefined, { source, file: target.file })).secrets);
+    const fromSecrets = new Set(secretsText === undefined
+        ? []
+        : (await configShow(root, undefined, { source: secretsText, file: secretsFile }))
+            .secrets);
+    const planned = await requiredSecretPaths(root, document.options);
+    const required = new Set(planned.paths);
+    const listed = document.secrets ?? [];
+    const paths = [...new Set([...fromConfig, ...fromSecrets, ...listed, ...required])].sort();
+    const secrets = paths.map((path) => {
+        const set = !empty(valueAt(merged, path.split('.')));
+        return {
+            path,
+            source: !set ? null : !empty(valueAt(secretOptions, path.split('.'))) ? 'secrets' : 'config',
+            listed: listed.includes(path),
+            required: required.has(path),
+        };
+    });
+    const missing = secrets.filter((entry) => entry.source === null).map((entry) => entry.path);
+    const warnings = [
+        ...unreadableWarning(planned.unreadable),
+        ...(secretsFile === undefined
+            ? []
+            : secrets
+                .filter((entry) => entry.source === 'config' && fromConfig.has(entry.path))
+                .map((entry) => ({
+                code: 'SECRET_IN_CONFIG_FILE',
+                path: entry.path,
+                hint: `${target.file} holds this secret although ${SECRETS_VARIABLE} names a secrets file: move it there (the configuration file is the one deploy/ keeps without secrets)`,
+            }))),
+    ];
+    debug('Configuration secrets listed', {
+        secrets: secrets.length,
+        missing: missing.length,
+        listed: listed.length,
+        secretsFile: secretsFile !== undefined,
+    });
+    return {
+        file: target.file,
+        secretsFile: secretsFile ?? null,
+        listed,
+        secrets,
+        missing,
+        ...(warnings.length ? { warnings } : {}),
+        ...(missing.length
+            ? {
+                nextSteps: [
+                    {
+                        command: secretsFile === undefined
+                            ? `${SECRETS_VARIABLE}=<the 0600 secrets file> npx dokebi config secrets --json`
+                            : `edit ${secretsFile}`,
+                        why: `set ${missing.join(', ')} (the app refuses to start without the listed ones: CONFIG_SECRETS_MISSING)`,
+                    },
+                ],
+            }
+            : {}),
+    };
+}
+/** The result for people: one line per path. */
+export function configSecretsText(result) {
+    const lines = result.secrets.map((entry) => `${entry.source === null ? 'MISSING' : entry.source.padEnd(7)} ${entry.path}${entry.listed ? ' (listed)' : ''}${entry.required ? ' (required)' : ''}`);
+    return `${lines.join('\n') || 'no secret options'}\n${result.missing.length ? `missing: ${result.missing.join(', ')}` : 'no secret missing'}${(result.warnings ?? [])
+        .map((warning) => `\nwarning: ${warning.code} (${warning.path}): ${warning.hint}`)
+        .join('')}\n`;
+}

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;