@dokebi/cli 0.4.1 → 0.4.26

package/dist/env-file.js

@@ -51,6 +51,21 @@ export function checkEnvText(text) {
         } while (!(lines[index] ?? '').includes(quote));
     }
 }
+/**
+ * The variables of a .env text, checked line by line first (ENV_FILE_INVALID). R4CA-11: a byte
+ * order mark (editors on Windows write one) is no part of the first name; util.parseEnv kept it
+ * there (`\uFEFFDATABASE_URL`), so the app missed that variable and an install that looked for
+ * it appended a second line that won over the user's value.
+ */
+export function parseEnvText(text) {
+    let body = text;
+    if (body.startsWith('\uFEFF')) {
+        debug('The project .env starts with a byte order mark; it is not part of the first name');
+        body = body.slice(1);
+    }
+    checkEnvText(body);
+    return parseEnv(body);
+}
 /**
  * The variables of `<root>/.env` (empty when there is none). Throws ENV_FILE_INVALID when the
  * file cannot be read or a line is not `KEY=value`.
@@ -72,24 +87,67 @@ export function readEnvFile(root) {
             },
         });
     }
-    checkEnvText(text);
-    const values = parseEnv(text);
+    const values = parseEnvText(text);
     debug('Read the project .env for the app', { file, variables: Object.keys(values) });
     return values;
 }
+/**
+ * Variables .env never passes to the app (R4CA-3, user decision 2026-10-26): DOKEBI_CONFIG chooses
+ * the settings file, and every CLI command and `npm start` read it from the environment only;
+ * from .env it would make only the app the CLI runs read another file than all of them.
+ */
+export const ENVIRONMENT_ONLY = ['DOKEBI_CONFIG'];
+/** What `.env` sets that the app does not get (ENVIRONMENT_ONLY), by line; [] without .env. */
+export function envFileWarnings(root) {
+    let text;
+    try {
+        text = readFileSync(join(root, ENV_FILE), 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return [];
+        throw new CliError('ENV_FILE_INVALID', `Unable to read ${ENV_FILE}`, {
+            cause: error,
+            details: { file: ENV_FILE, fix: `make ${ENV_FILE} a readable file (or remove it)` },
+        });
+    }
+    const warnings = [];
+    for (const [index, line] of text
+        .replace(/^\uFEFF/, '')
+        .split(/\r?\n/)
+        .entries()) {
+        const name = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.-]*)\s*=/.exec(line)?.[1];
+        if (name === undefined || !ENVIRONMENT_ONLY.includes(name))
+            continue;
+        warnings.push({
+            code: 'ENV_DOKEBI_CONFIG_IGNORED',
+            path: `${ENV_FILE}:${index + 1}`,
+            variable: name,
+            hint: `${ENV_FILE} line ${index + 1} sets ${name}, which the app does not get from ${ENV_FILE}: every dokebi command and npm start read the settings file from the environment only. To use another file, set it in the environment (${name}=<file> npx dokebi …), and remove the line`,
+        });
+    }
+    return warnings;
+}
 /**
  * The environment of an app the CLI runs: the project's .env, then the CLI's own environment on
  * top (it wins), then NODE_ENV (`mode` unless one of them set it) and `extra` (the CLI's own
- * variables such as DOKEBI_DEV or the verify and instance tokens).
+ * variables such as DOKEBI_DEV or the verify and instance tokens). ENVIRONMENT_ONLY variables are
+ * never taken from .env (envFileWarnings names their lines).
  */
 export function appEnvironment(root, mode, extra = {}, fileValues = readEnvFile(root)) {
-    const overridden = Object.keys(fileValues).filter((key) => process.env[key] !== undefined);
+    const passed = Object.fromEntries(Object.entries(fileValues).filter(([key]) => !ENVIRONMENT_ONLY.includes(key)));
+    const ignored = Object.keys(fileValues).filter((key) => ENVIRONMENT_ONLY.includes(key));
+    if (ignored.length)
+        debug('Variables of .env the app does not get (environment only)', { variables: ignored });
+    const overridden = Object.keys(passed).filter((key) => process.env[key] !== undefined);
     if (overridden.length)
         debug('Variables of .env already set in the environment; the environment wins', {
             variables: overridden,
         });
-    const merged = { ...fileValues, ...process.env };
-    return { ...merged, NODE_ENV: merged.NODE_ENV ?? mode, ...extra };
+    const merged = { ...passed, ...process.env };
+    // D-0161: an app the CLI runs on this machine (start, verify, dev) is no deployment, even under
+    // NODE_ENV=production: the plugins keep memory stores for one process there.
+    return { ...merged, NODE_ENV: merged.NODE_ENV ?? mode, DOKEBI_LOCAL_RUN: '1', ...extra };
 }
 /** Whether a variable is set in the environment or in the project's .env (values not returned). */
 export function envHas(root, name) {

package/dist/errors.d.ts

@@ -1,6 +1,12 @@
 export interface CliErrorOptions extends ErrorOptions {
     details?: unknown;
-    phase?: 'arguments' | 'install' | 'commit' | 'unknown';
+    /**
+     * The confirmed stage (docs/cli/automation.md): `arguments` (the input was refused), `plan` (the
+     * change was being prepared and checked, after the project and any staged install were read
+     * and before the commit: nothing in the project was written, D-0116), `install`, `commit`, or
+     * `unknown`. A failure in `arguments` or `plan` always has `mutation: none`.
+     */
+    phase?: 'arguments' | 'plan' | 'install' | 'commit' | 'unknown';
 }
 export declare class CliError extends Error {
     readonly code: string;

package/dist/example-config.d.ts

@@ -7,5 +7,7 @@ export declare function syncExample(source: string, id: string, update: {
     readonly defaults?: readonly Record<string, unknown>[];
     readonly changes?: readonly ConfigChange[];
     readonly schema?: Record<string, unknown> | null;
+    /** The logger host was added: the sample gets the targets dokebi.yaml got (AI-M46). */
+    readonly loggingTargets?: boolean;
 }): string;
 export declare function markExampleRemoved(source: string, id: string): string;

package/dist/example-config.js

@@ -1,4 +1,5 @@
 import { applyConfigChanges, markRemoved } from './config-edit.js';
+import { addLoggingTargets } from './configuration.js';
 import { scaffoldConfig } from './configuration-scaffold.js';
 import { mergeInstallDefaults } from './merge-install-defaults.js';
 /**
@@ -9,6 +10,8 @@ export function syncExample(source, id, update) {
     let result = applyConfigChanges(source, id, update.changes ?? []);
     for (const defaults of update.defaults ?? [])
         result = mergeInstallDefaults(result, id, defaults);
+    if (update.loggingTargets)
+        result = addLoggingTargets(result);
     return scaffoldConfig(result, id, update.schema ?? null);
 }
 export function markExampleRemoved(source, id) {

package/dist/first-admin.d.ts

@@ -0,0 +1,43 @@
+/** The login of the first admin as dokebi.yaml configures it (never the password). */
+export interface FirstAdminIdentity {
+    /** The key in the section (`login`, `email`, …). */
+    readonly key: string;
+    readonly value: string;
+    readonly kind: 'login' | 'email';
+}
+/** What the project says about its first admin. */
+export interface FirstAdmin {
+    /** The section of `options` that holds `initialPassword`; absent when none could be told. */
+    readonly section?: string;
+    readonly identity?: FirstAdminIdentity;
+    /** The seed that creates the first admin, when there is one. */
+    readonly seedFile?: string;
+    /** The section the seed reads (`config.options['…']`), when it names one. */
+    readonly seedSection?: string;
+    /** Every section of `options` that holds `initialPassword`. */
+    readonly candidates: readonly string[];
+    /**
+     * The settings file these options come from (M50: the one DOKEBI_CONFIG names); absent for
+     * dokebi.yaml.
+     */
+    readonly settingsFile?: string;
+}
+/** The sections of `options` that hold a non-empty `initialPassword`, in file order. */
+export declare function adminSections(options: Record<string, unknown>): string[];
+/** Every `options['…']` / `options.…` section a source file reads, in order (comments skipped). */
+export declare function sectionsRead(source: string): string[];
+/** What `options` and the seed source say about the first admin (no file access). */
+export declare function describeFirstAdmin(options: Record<string, unknown>, seed: {
+    file: string;
+    text: string;
+} | undefined): FirstAdmin;
+/**
+ * Reads the settings file the app reads (DOKEBI_CONFIG, else dokebi.yaml; M50) and the seed;
+ * undefined facts when the settings file cannot be read.
+ */
+export declare function readFirstAdmin(root: string): Promise<FirstAdmin>;
+/**
+ * The words after `sign in at <url>/login` in the login notice: the configured login and where
+ * the initial password is, or that the first-admin settings were not found and where to look.
+ */
+export declare function firstAdminPhrase(found: FirstAdmin): string;

package/dist/first-admin.js

@@ -0,0 +1,175 @@
+// Where the first admin of `dokebi recipe blog --admin login` comes from (D-0115), read from the
+// project itself instead of stated from the recipe's constants: AI-M25's builder renamed the
+// section and signed the first admin in by email, and verify still told the user "the login name
+// admin … at options.blog-admin.initialPassword". The section is the one that holds
+// `initialPassword` (the one the seed reads when it names one), the login is the login or email
+// key configured there. Nothing found is said as such, with where to look: a value that is not
+// in the project is never stated, and the password itself is never read into a text or a log.
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseProjectConfig, readProjectSettings } from './configuration.js';
+import { debug, describeError, isMissing } from './diagnostics.js';
+import { ADMIN_PASSWORD_KEY, ADMIN_SECTION, LEGACY_ADMIN_SECTION, SEED_FILE, } from './recipe-login.js';
+const SEEDS = 'src/infra/db/seeds';
+/** Keys that name the first admin's login (the recipe writes `login`). */
+const LOGIN_KEYS = /^(?:login|login_?name|user_?name|user|account|identity)$/i;
+/** Keys that name an email address (AI-M25: the builder signed the admin in by email). */
+const EMAIL_KEYS = /e-?mail/i;
+/** A value that can be shown on one line (anything else is not repeated). */
+const SHOWN = /^[^\s\p{Cc}]{1,254}$/u;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** The sections of `options` that hold a non-empty `initialPassword`, in file order. */
+export function adminSections(options) {
+    return Object.entries(options).flatMap(([name, value]) => {
+        const password = record(value)?.[ADMIN_PASSWORD_KEY];
+        return typeof password === 'string' && password.length > 0 ? [name] : [];
+    });
+}
+/** Every `options['…']` / `options.…` section a source file reads, in order (comments skipped). */
+export function sectionsRead(source) {
+    const found = [];
+    const code = source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:'"`\\])\/\/.*$/gm, '$1');
+    const pattern = /\boptions\s*(?:\?\.)?\s*(?:\[\s*(['"`])([^'"`\n]+)\1\s*\]|\.\s*([A-Za-z_$][\w$]*(?:-[\w$]+)*))/g;
+    for (const match of code.matchAll(pattern)) {
+        const name = match[2] ?? match[3];
+        if (name && !found.includes(name))
+            found.push(name);
+    }
+    return found;
+}
+/** The login or email key of `section`, preferring one the seed reads. */
+function identityOf(section, seed) {
+    const keys = Object.entries(section).flatMap(([key, value]) => key !== ADMIN_PASSWORD_KEY &&
+        (LOGIN_KEYS.test(key) || EMAIL_KEYS.test(key)) &&
+        typeof value === 'string' &&
+        SHOWN.test(value.trim())
+        ? [{ key, value: value.trim() }]
+        : []);
+    const read = (key) => {
+        const name = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return new RegExp(`(?:\\.\\s*${name}\\b|\\[\\s*['"\`]${name}['"\`]\\s*\\])`).test(seed);
+    };
+    const chosen = keys.find((item) => read(item.key)) ?? keys[0];
+    if (!chosen)
+        return undefined;
+    return { ...chosen, kind: EMAIL_KEYS.test(chosen.key) ? 'email' : 'login' };
+}
+/** The seed file of the first admin: the recipe's, else a seed that names `initialPassword`. */
+async function seedSource(root) {
+    try {
+        return { file: SEED_FILE, text: await readFile(join(root, SEED_FILE), 'utf8') };
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    let connections = [];
+    try {
+        connections = (await readdir(join(root, SEEDS), { withFileTypes: true }))
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        return undefined;
+    }
+    for (const connection of connections) {
+        const names = (await readdir(join(root, SEEDS, connection))).filter((name) => /\.[cm]?ts$/.test(name));
+        for (const name of names.sort()) {
+            const file = `${SEEDS}/${connection}/${name}`;
+            const text = await readFile(join(root, file), 'utf8');
+            if (text.includes(ADMIN_PASSWORD_KEY))
+                return { file, text };
+        }
+    }
+    return undefined;
+}
+/** What `options` and the seed source say about the first admin (no file access). */
+export function describeFirstAdmin(options, seed) {
+    const candidates = adminSections(options);
+    const read = seed ? sectionsRead(seed.text) : [];
+    // The section the seed reads that holds the password, else the first one it reads (in code
+    // order: the read itself comes before any message that names it).
+    const seedSection = read.find((name) => candidates.includes(name)) ?? read[0];
+    const base = {
+        candidates,
+        ...(seed ? { seedFile: seed.file } : {}),
+        ...(seedSection ? { seedSection } : {}),
+    };
+    // The seed decides when it names a section; otherwise the one section holding the password.
+    const section = seedSection
+        ? candidates.includes(seedSection)
+            ? seedSection
+            : undefined
+        : candidates.length === 1
+            ? candidates[0]
+            : (candidates.find((name) => name === ADMIN_SECTION) ??
+                candidates.find((name) => name === LEGACY_ADMIN_SECTION));
+    if (!section)
+        return base;
+    const identity = identityOf(record(options[section]) ?? {}, seed?.text ?? '');
+    return { ...base, section, ...(identity ? { identity } : {}) };
+}
+/**
+ * Reads the settings file the app reads (DOKEBI_CONFIG, else dokebi.yaml; M50) and the seed;
+ * undefined facts when the settings file cannot be read.
+ */
+export async function readFirstAdmin(root) {
+    let options = {};
+    let settingsFile;
+    try {
+        const settings = await readProjectSettings(root);
+        if (settings.target.fromEnvironment)
+            settingsFile = settings.target.file;
+        options = parseProjectConfig(settings.source).options;
+    }
+    catch (error) {
+        debug('First admin: the settings file not read', { error: describeError(error) });
+    }
+    let seed;
+    try {
+        seed = await seedSource(root);
+    }
+    catch (error) {
+        debug('First admin: seed not read', { error: describeError(error) });
+    }
+    const found = {
+        ...describeFirstAdmin(options, seed),
+        ...(settingsFile ? { settingsFile } : {}),
+    };
+    debug('First admin settings', {
+        section: found.section ?? null,
+        identityKey: found.identity?.key ?? null,
+        seedFile: found.seedFile ?? null,
+        seedSection: found.seedSection ?? null,
+        candidates: found.candidates,
+    });
+    return found;
+}
+/**
+ * The words after `sign in at <url>/login` in the login notice: the configured login and where
+ * the initial password is, or that the first-admin settings were not found and where to look.
+ */
+export function firstAdminPhrase(found) {
+    const file = found.settingsFile ?? 'dokebi.yaml';
+    const seed = found.seedFile ?? `the seed that creates the first admin (${SEEDS}/<connection>/)`;
+    if (!found.section) {
+        const why = found.seedSection
+            ? `${seed} reads options.${found.seedSection}, and ${file} has no ${ADMIN_PASSWORD_KEY} there`
+            : found.candidates.length > 1
+                ? `more than one section under options of ${file} holds ${ADMIN_PASSWORD_KEY} (${found.candidates.join(', ')})`
+                : `no section under options of ${file} holds ${ADMIN_PASSWORD_KEY}`;
+        return `as the first admin, but the CLI could not find the first-admin settings (${why}: renamed, or removed once the admin existed). Look in ${seed} and the options of ${file} for the login and the initial password, and never print the password`;
+    }
+    const at = `options.${found.section}`;
+    const who = found.identity
+        ? `the ${found.identity.kind === 'email' ? 'email address' : 'login name'} ${found.identity.value}`
+        : `the login ${seed} gives the first admin (${at} of ${file} has no login or email key)`;
+    return `with ${who} and the initial password stored in ${file} at ${at}.${ADMIN_PASSWORD_KEY} (it is never printed; change it before going live and then remove the key)`;
+}

package/dist/formatter-ignore.d.ts

@@ -0,0 +1,37 @@
+export declare const PRETTIER_IGNORE = ".prettierignore";
+/** The comment line above the CLI-owned .prettierignore entry. */
+export declare const PRETTIER_MARKER = "# dokebi: applied migrations are never reformatted (D-0145; @dokebi/migrate checks them)";
+/** The CLI-written registration; the CLI refuses a project whose copy differs (MODIFIED_REGISTRATION). */
+export declare const GENERATED_FILE = "src/dokebi.generated.ts";
+/** The comment line above the CLI-owned .prettierignore entry of the generated registration. */
+export declare const PRETTIER_GENERATED_MARKER = "# dokebi: the CLI writes src/dokebi.generated.ts and refuses a reformatted copy (MODIFIED_REGISTRATION)";
+export type FormatterTool = 'prettier' | 'biome' | 'eslint';
+/** One formatter the project configures, and whether it leaves the migrations folder alone. */
+export interface FormatterUse {
+    readonly tool: FormatterTool;
+    /** The config file (`package.json` for a `prettier` key or dependency). */
+    readonly config: string;
+    /** True when its ignore settings already keep the folder out. */
+    readonly covered: boolean;
+}
+/** The migrations folder of the project: `options.dokebi-migrate.directory` + `/migrations`. */
+export declare function migrationsFolder(root: string): Promise<string>;
+/** Whether a .prettierignore (gitignore syntax) keeps `folder` out. */
+export declare function prettierCovers(ignore: string, folder: string): boolean;
+/** .prettierignore with the CLI-owned entry for `folder` (unchanged when it is covered). */
+export declare function prettierIgnoreText(ignore: string, folder: string): string;
+/** Whether a parsed biome config keeps `folder` out (v2 `files.includes`, v1 `files.ignore`). */
+export declare function biomeCovers(config: unknown, folder: string): boolean;
+/**
+ * biome.json with `folder` kept out, edited in place so the file stays as biome formats it:
+ * `!<folder>` appended to `files.includes` (v2), or `<folder>` to `files.ignore` (v1, `v1`), or
+ * a new `"files": { "includes": ["**", "!<folder>"] }` first in the object. Undefined when the
+ * text is not plain JSON (biome.jsonc, comments): the caller warns instead.
+ */
+export declare function biomeConfigText(text: string, folder: string, v1?: boolean): string | undefined;
+/** The major version of @biomejs/biome the project asks for, when package.json names one. */
+export declare function biomeMajor(pkg: Record<string, unknown>): number | undefined;
+/** The formatters the project configures and whether each leaves `folder` alone. */
+export declare function formatterUses(root: string, folder: string): Promise<FormatterUse[]>;
+/** The one-line fix for a formatter that would format the migrations folder. */
+export declare function formatterFix(use: FormatterUse, folder: string): string;