@dokebi/cli 0.4.2 → 0.4.27

package/dist/plugin-options.js

@@ -1,10 +1,134 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { ConfigValidator, loadSchema } from '@dokebi/config';
+import { debug, describeError } from './diagnostics.js';
 import { CliError } from './errors.js';
+import { optionsKey } from './manifest.js';
+import { optionsFix } from './option-fixes.js';
+import { readSettingsSchema } from './settings.js';
 import { packageFile } from './workspace.js';
+/** The smallest schema the validator compiles: whether it works at all. */
+const TRIVIAL_SCHEMA = Object.freeze({
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    type: 'object',
+});
+/** The version of the @dokebi/config this CLI validates with ('unknown' when it cannot be read). */
+function configVersion() {
+    try {
+        // ESM resolution: @dokebi/config exports only an `import` condition.
+        let directory = dirname(fileURLToPath(import.meta.resolve('@dokebi/config')));
+        for (let depth = 0; depth < 4; depth++) {
+            const file = join(directory, 'package.json');
+            if (existsSync(file)) {
+                const pkg = JSON.parse(readFileSync(file, 'utf8'));
+                if (pkg.name === '@dokebi/config')
+                    return String(pkg.version);
+            }
+            directory = dirname(directory);
+        }
+    }
+    catch (error) {
+        debug('The @dokebi/config version could not be read', { error: describeError(error) });
+    }
+    return 'unknown';
+}
+/**
+ * The first line of an error and of each cause under it, at most 500 characters: why a schema
+ * failed, never a value. @dokebi/config's ConfigError says only "Invalid or unsupported options
+ * schema"; ajv's words (`strict mode: unknown keyword: "x-dokebi-…"`) are its cause (R5C-1).
+ */
+function reasonOf(error) {
+    const lines = [];
+    let current = error ?? 'unknown';
+    for (let depth = 0; depth < 4 && current !== undefined && current !== null; depth++) {
+        const text = current instanceof Error ? `${current.name}: ${current.message}` : String(current);
+        lines.push(text.split('\n')[0] ?? '');
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return lines.join(' <- caused by ').slice(0, 500);
+}
 export class PluginOptionsValidator {
     #validator;
+    /** Whether the validator itself works (a trivial schema compiles); asked once, on a failure. */
+    #works;
     constructor(options = {}) {
-        this.#validator = new ConfigValidator(options);
+        this.#validator =
+            options.validator ??
+                new ConfigValidator({ ...(options.allErrors ? { allErrors: true } : {}) });
+    }
+    /**
+     * AI-M45: a schema that cannot be read or compiled, with the reason. When even a trivial schema
+     * does not compile, the validator itself is broken (a damaged node_modules: ajv's files gone)
+     * and every plugin would be reported: the fix then says to restore the installation.
+     */
+    async #failure(cause, subject, reinstall) {
+        // A schema the validator takes (it refuses one without the 2020-12 `$schema`): with
+        // `{ type: 'object' }` alone the probe always failed, so every schema that did not compile
+        // was reported as a damaged installation with the fix `npm ci`.
+        this.#works ??= this.#validator.check(TRIVIAL_SCHEMA, {}).then(() => true, () => false);
+        const validatorBroken = !(await this.#works);
+        // A schema of a newer release than this CLI's @dokebi/config (2026-10-28: an older CLI met
+        // x-dokebi-secret and x-dokebi-alias-of and was read as a broken installation).
+        const keyword = /unknown keyword:? "?(x-dokebi-[\w-]+)/.exec(reasonOf(cause))?.[1];
+        if (!validatorBroken && keyword !== undefined) {
+            const version = configVersion();
+            return new CliError('INVALID_OPTIONS_SCHEMA', `The options schema of ${String(subject.plugin ?? subject.section)} uses ${keyword}, which the @dokebi/config ${version} of this CLI does not know`, {
+                cause,
+                details: {
+                    ...subject,
+                    reason: reasonOf(cause),
+                    keyword,
+                    config: version,
+                    validator: false,
+                    fix: `the schema comes from a newer release than this CLI: run the @dokebi/cli of the same release as the installed plugins (npm install the matching @dokebi/cli in the project, then npx dokebi), and keep @dokebi/core, @dokebi/config and @dokebi/cli of one release; the installation is not damaged`,
+                },
+                phase: 'plan',
+            });
+        }
+        return new CliError('INVALID_OPTIONS_SCHEMA', validatorBroken
+            ? 'The options schema validator of @dokebi/config cannot load (the installation is damaged)'
+            : `The options schema of ${String(subject.plugin ?? subject.section)} cannot be read or compiled`, {
+            cause,
+            details: {
+                ...subject,
+                reason: reasonOf(cause),
+                validator: validatorBroken,
+                fix: validatorBroken
+                    ? 'restore node_modules with npm ci (or npm install): the JSON Schema validator (ajv, a dependency of @dokebi/config) is missing files, so no options can be checked; every section is reported until then'
+                    : reinstall,
+            },
+            phase: 'plan',
+        });
+    }
+    /**
+     * D-0155: the options of an application settings section against the schema file beside its
+     * declaration (src/shared/settings/<section>.schema.json); no schema yet checks nothing.
+     */
+    async checkSettings(root, section, options) {
+        const schema = await readSettingsSchema(root, section);
+        if (!schema)
+            return { schema: null, errors: [] };
+        try {
+            const checked = await this.#validator.check(schema, options);
+            return { schema, errors: checked.errors };
+        }
+        catch (cause) {
+            throw await this.#failure(cause, { section }, `run npx dokebi settings sync to write src/shared/settings/${section}.schema.json again`);
+        }
+    }
+    /**
+     * A settings section against a schema in hand (`settings sync` checks the options against the
+     * schema it is about to write, before the file is on disk).
+     */
+    async checkSettingsWith(section, schema, options) {
+        try {
+            const checked = await this.#validator.check(schema, options);
+            return { schema, errors: checked.errors };
+        }
+        catch (cause) {
+            throw await this.#failure(cause, { section }, `correct the declaration of ${section} so core renders a valid schema, then npx dokebi settings sync`);
+        }
     }
     async check(root, plugin, options) {
         if (!plugin.optionsSchema)
@@ -16,7 +140,7 @@ export class PluginOptionsValidator {
             return { schema, errors: checked.errors };
         }
         catch (cause) {
-            throw new CliError('INVALID_OPTIONS_SCHEMA', plugin.id, { cause });
+            throw await this.#failure(cause, { plugin: plugin.id, version: plugin.version, schema: plugin.optionsSchema }, `reinstall ${plugin.packageName} (npm install), or use another version of it; details.reason says why`);
         }
     }
 }
@@ -24,12 +148,20 @@ export async function checkPluginOptions(root, plugin, options) {
     return new PluginOptionsValidator().check(root, plugin, options);
 }
 export async function validatePluginOptions(root, plugins, options) {
-    const validator = new PluginOptionsValidator();
+    // Every issue (D-0153): the fix names all unknown keys in one config unset.
+    const validator = new PluginOptionsValidator({ allErrors: true });
     for (const plugin of plugins) {
-        const result = await validator.check(root, plugin, Object.hasOwn(options, plugin.id) ? (options[plugin.id] ?? {}) : {});
+        // D-0151: the logger host's options are options.logging.
+        const key = optionsKey(plugin);
+        const result = await validator.check(root, plugin, Object.hasOwn(options, key) ? (options[key] ?? {}) : {});
         if (result.errors.length)
-            throw new CliError('INVALID_PLUGIN_OPTIONS', plugin.id, {
-                details: { plugin: plugin.id, errors: result.errors },
+            throw new CliError('INVALID_PLUGIN_OPTIONS', `The options of ${plugin.id} do not match its schema: options.${key}${(result.errors[0]?.instancePath ?? '').replaceAll('/', '.')} (${result.errors[0]?.keyword ?? 'invalid'})`, {
+                details: {
+                    plugin: plugin.id,
+                    errors: result.errors,
+                    fix: optionsFix(plugin.id, result.errors, `correct options.${key} in dokebi.yaml (npx dokebi plugins info ${plugin.id} --json lists the option keys)`, key, result.schema),
+                },
+                phase: 'plan',
             });
     }
 }

package/dist/plugins-command.js

@@ -109,9 +109,14 @@ export async function pluginsList(root, options) {
 export async function pluginsSearch(query) {
     return searchCatalog(await loadCatalog(), query);
 }
-function unknownPackage(catalog, key) {
+function unknownPackage(catalog, key, 
+/** An installed package the key names by its short name (AI-M04 F7), with its guide's path. */
+installed) {
     const search = searchCatalog(catalog, key);
-    return new CliError('UNKNOWN_PLUGIN', `No Dokebi package "${key}"`, {
+    const fix = installed
+        ? `npx dokebi plugins doc ${installed.package} --json (or read ${installed.path})`
+        : undefined;
+    return new CliError('UNKNOWN_PLUGIN', `No Dokebi package "${key}"${installed ? `; did you mean ${installed.package}? ${fix}` : ''}`, {
         phase: 'arguments',
         details: {
             query: key,
@@ -121,10 +126,44 @@ function unknownPackage(catalog, key) {
                 summary: entry.summary,
                 instead: entry.instead,
             })),
-            hint: 'npx dokebi plugins search <words> --json',
+            ...(installed && fix ? { package: installed.package, path: installed.path, fix } : {}),
+            hint: fix ?? 'npx dokebi plugins search <words> --json',
         },
     });
 }
+/** The guide path of an installed package's package.json (`dokebi.documentation`, else AI.md). */
+function documentationPath(packageName, pkg) {
+    const manifest = pkg.dokebi;
+    const documentation = typeof manifest?.documentation === 'string' ? manifest.documentation : 'AI.md';
+    return `node_modules/${packageName}/${documentation}`;
+}
+/**
+ * An id that is not in the catalog but names an installed @dokebi package by its short name
+ * (`dokebi-core`, `dokebi-cli`: core, CLI and drivers have no plugin id), AI-M04 F7.
+ */
+async function installedByShortName(root, key) {
+    const short = key
+        .trim()
+        .toLowerCase()
+        .replace(/^@dokebi\//, '')
+        .replace(/^dokebi-/, '');
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(short))
+        return undefined;
+    const packageName = `@dokebi/${short}`;
+    try {
+        const pkg = parseObject(await readFile(await packageFile(root, packageName, 'package.json'), 'utf8'), packageName);
+        return { package: packageName, path: documentationPath(packageName, pkg) };
+    }
+    catch (error) {
+        if (!isMissing(error) && !(error instanceof CliError))
+            throw error;
+        debug('plugins doc: no installed package by that short name', {
+            package: packageName,
+            error: describeError(error),
+        });
+        return undefined;
+    }
+}
 export async function pluginsInfo(root, key) {
     const catalog = await loadCatalog();
     const item = findPackage(catalog, key);
@@ -146,7 +185,7 @@ export async function pluginsDoc(root, key) {
     const item = findPackage(catalog, key);
     const packageName = item?.package ?? (key.startsWith('@') ? key : undefined);
     if (!packageName)
-        throw unknownPackage(catalog, key);
+        throw unknownPackage(catalog, key, await installedByShortName(root, key));
     let pkg;
     try {
         pkg = parseObject(await readFile(await packageFile(root, packageName, 'package.json'), 'utf8'), packageName);
@@ -167,9 +206,7 @@ export async function pluginsDoc(root, key) {
             },
         });
     }
-    const manifest = pkg.dokebi;
-    const documentation = typeof manifest?.documentation === 'string' ? manifest.documentation : 'AI.md';
-    const path = `node_modules/${packageName}/${documentation}`;
+    const path = documentationPath(packageName, pkg);
     let content;
     try {
         content = await readFile(await installedPath(root, path), 'utf8');

package/dist/process-group.d.ts

@@ -0,0 +1,39 @@
+/** Spawn with `detached: PROCESS_GROUPS`: on POSIX the child then leads a new process group. */
+export declare const PROCESS_GROUPS: boolean;
+/**
+ * Signals the process group of `pid` (POSIX; the child leads it) or the child alone (Windows):
+ * true when the signal was sent, false when nothing of the group is left (ESRCH, the expected
+ * case after a clean run) or it could not be signalled (logged at debug: the caller decides).
+ */
+export declare function killGroup(pid: number | undefined, signal: NodeJS.Signals): boolean;
+/**
+ * Whether the process group `pid` led still has a member (POSIX). A group outlives its leader
+ * while a member runs, and its id is not reused as long as it exists, so a member found here
+ * right after the leader exited is one the leader started.
+ */
+export declare function groupAlive(pid: number): boolean;
+/**
+ * Ends what is left of the process group of `pid` after its leader exited: processes the leader
+ * started and did not stop (a helper, a server holding a port). SIGTERM first, SIGKILL after
+ * `graceMs`. `none` when nothing was left (the usual case), else how they were ended.
+ */
+export declare function endLeftovers(pid: number, graceMs: number): Promise<'none' | 'terminated' | 'killed'>;
+/** The signals that end a command (Ctrl+C, an agent's command time limit, a closed terminal). */
+export declare const TERMINATING: readonly ['SIGINT', 'SIGTERM', 'SIGHUP'];
+/**
+ * Holds off a terminating signal while a step must clean up first: the first SIGINT, SIGTERM or
+ * SIGHUP is recorded (`signal()`) instead of ending the process at once, so the step can see it,
+ * undo what it started and throw. `release()` removes the handlers and, when a signal came and
+ * nobody else listens for it, ends this process as that signal would have.
+ */
+export declare function holdTermination(): {
+    signal(): NodeJS.Signals | undefined;
+    release(): void;
+};
+/**
+ * A detached group no longer gets the terminal's Ctrl+C (nor a SIGTERM or SIGHUP sent to this
+ * process). While the child runs, this passes such a signal on to its group and then lets this
+ * process end as it would have without the listener. Returns the function that stops forwarding;
+ * call it once the child closed.
+ */
+export declare function forwardTermination(pid: number | undefined): () => void;

package/dist/process-group.js

@@ -0,0 +1,132 @@
+// Child commands that may start their own children (npm run, Vite, tsc, test runners) run in a
+// process group of their own, so a time limit can end all of them. Killing only the direct child
+// leaves the grandchildren running, and as they still hold the stdout/stderr pipes the child's
+// 'close' event (and the step waiting for it) would not come until they end by themselves.
+import { debug, describeError } from './diagnostics.js';
+/** Spawn with `detached: PROCESS_GROUPS`: on POSIX the child then leads a new process group. */
+export const PROCESS_GROUPS = process.platform !== 'win32';
+/**
+ * Signals the process group of `pid` (POSIX; the child leads it) or the child alone (Windows):
+ * true when the signal was sent, false when nothing of the group is left (ESRCH, the expected
+ * case after a clean run) or it could not be signalled (logged at debug: the caller decides).
+ */
+export function killGroup(pid, signal) {
+    if (pid === undefined)
+        return false;
+    try {
+        if (PROCESS_GROUPS)
+            process.kill(-pid, signal);
+        else
+            process.kill(pid, signal);
+        return true;
+    }
+    catch (error) {
+        if (error.code !== 'ESRCH')
+            debug('Could not signal the process group', {
+                pid,
+                signal,
+                error: describeError(error),
+            });
+        return false;
+    }
+}
+/**
+ * Whether the process group `pid` led still has a member (POSIX). A group outlives its leader
+ * while a member runs, and its id is not reused as long as it exists, so a member found here
+ * right after the leader exited is one the leader started.
+ */
+export function groupAlive(pid) {
+    if (!PROCESS_GROUPS)
+        return false;
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (error) {
+        // ESRCH: nobody is left. EPERM: a member this user may not signal (not one the app started).
+        if (error.code !== 'ESRCH')
+            debug('Could not probe the process group', { pid, error: describeError(error) });
+        return false;
+    }
+}
+/**
+ * Ends what is left of the process group of `pid` after its leader exited: processes the leader
+ * started and did not stop (a helper, a server holding a port). SIGTERM first, SIGKILL after
+ * `graceMs`. `none` when nothing was left (the usual case), else how they were ended.
+ */
+export async function endLeftovers(pid, graceMs) {
+    if (!groupAlive(pid))
+        return 'none';
+    debug('Processes are left in the group of an exited process; ending them', { pid, graceMs });
+    killGroup(pid, 'SIGTERM');
+    const until = performance.now() + graceMs;
+    while (performance.now() < until) {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        if (!groupAlive(pid))
+            return 'terminated';
+    }
+    killGroup(pid, 'SIGKILL');
+    debug('Processes left in the group did not end on SIGTERM; killed', { pid, graceMs });
+    return 'killed';
+}
+/** The signals that end a command (Ctrl+C, an agent's command time limit, a closed terminal). */
+export const TERMINATING = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+/**
+ * Holds off a terminating signal while a step must clean up first: the first SIGINT, SIGTERM or
+ * SIGHUP is recorded (`signal()`) instead of ending the process at once, so the step can see it,
+ * undo what it started and throw. `release()` removes the handlers and, when a signal came and
+ * nobody else listens for it, ends this process as that signal would have.
+ */
+export function holdTermination() {
+    let received;
+    const handlers = new Map();
+    for (const signal of TERMINATING) {
+        const handler = () => {
+            if (received)
+                return;
+            received = signal;
+            debug('A termination signal arrived; cleaning up before ending', { signal });
+        };
+        handlers.set(signal, handler);
+        process.on(signal, handler);
+    }
+    return {
+        signal: () => received,
+        release: () => {
+            for (const [signal, handler] of handlers)
+                process.off(signal, handler);
+            handlers.clear();
+            if (received && process.listenerCount(received) === 0)
+                process.kill(process.pid, received);
+        },
+    };
+}
+/**
+ * A detached group no longer gets the terminal's Ctrl+C (nor a SIGTERM or SIGHUP sent to this
+ * process). While the child runs, this passes such a signal on to its group and then lets this
+ * process end as it would have without the listener. Returns the function that stops forwarding;
+ * call it once the child closed.
+ */
+export function forwardTermination(pid) {
+    const handlers = new Map();
+    const stop = () => {
+        for (const [signal, handler] of handlers)
+            process.off(signal, handler);
+        handlers.clear();
+    };
+    if (!PROCESS_GROUPS || pid === undefined)
+        return stop;
+    for (const signal of TERMINATING) {
+        const handler = () => {
+            debug('Passing a termination signal on to the child process group', { pid, signal });
+            killGroup(pid, signal);
+            stop();
+            // Nobody else listens: the signal's default action (ending this process) applies again.
+            if (process.listenerCount(signal) === 0)
+                process.kill(process.pid, signal);
+        };
+        handlers.set(signal, handler);
+        process.on(signal, handler);
+    }
+    return stop;
+}

package/dist/production-doctor.d.ts

@@ -0,0 +1,3 @@
+import type { Diagnostic } from './project-inspector.js';
+/** The production diagnostics of the project at `root` (D-0184 §4). */
+export declare function productionDiagnostics(root: string, env?: NodeJS.ProcessEnv): Promise<Diagnostic[]>;

package/dist/production-doctor.js

@@ -0,0 +1,176 @@
+// `dokebi doctor --production` (D-0184 §4): the checks of a server, on the settings the app
+// reads there (DOKEBI_CONFIG, merged with the secrets file DOKEBI_SECRETS). The per-process
+// state rules mirror what the plugins refuse at start in production (D-0161), so a deploy learns
+// them before the restart instead of from a failed start.
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { applySecrets, ConfigError, parseConfig, SECRETS_VARIABLE } from '@dokebi/config';
+import { kept } from './check/shared-state-rules.js';
+import { placeholderPaths } from './config-init.js';
+import { configSecrets } from './config-secrets.js';
+import { readSettings } from './config-show.js';
+import { debug, describeError } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { parseObject } from './filesystem.js';
+import { optionsKey } from './manifest.js';
+import { readState } from './project-state.js';
+function valueAt(options, path) {
+    let value = options;
+    for (const key of path) {
+        if (value && typeof value === 'object' && !Array.isArray(value) && Object.hasOwn(value, key))
+            value = value[key];
+        else
+            return undefined;
+    }
+    return value;
+}
+/** `dokebi-migrate status --json` with the settings of the server; undefined when it cannot run. */
+function migrationStatus(root, env) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        const child = spawn(join(root, 'node_modules', '.bin', 'dokebi-migrate'), ['status', '--json'], {
+            cwd: root,
+            env,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 60_000,
+        });
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+        child.once('error', (error) => {
+            debug('dokebi-migrate status could not run', { error: describeError(error) });
+            resolve(undefined);
+        });
+        child.once('close', () => {
+            try {
+                resolve(JSON.parse(stdout));
+            }
+            catch (error) {
+                debug('dokebi-migrate status gave no JSON', { error: describeError(error) });
+                resolve(undefined);
+            }
+        });
+    });
+}
+/** The production diagnostics of the project at `root` (D-0184 §4). */
+export async function productionDiagnostics(root, env = process.env) {
+    const found = [];
+    const add = (code, severity, path, hint, plugin = null, details) => found.push({
+        code,
+        severity,
+        path,
+        plugin,
+        hint,
+        ...(details === undefined ? {} : { details }),
+    });
+    if (env.NODE_ENV !== 'production')
+        add('NODE_ENV_NOT_PRODUCTION', 'error', 'NODE_ENV', 'NODE_ENV is not production here, so this check (and an app started like this) runs with development behaviour: run it as the service runs, NODE_ENV=production npx dokebi doctor --production (the systemd unit and compose file set it)');
+    const { target, source } = await readSettings(root);
+    const secretsFile = env[SECRETS_VARIABLE] || undefined;
+    let options;
+    try {
+        options = (await applySecrets(parseConfig(source), secretsFile)).options;
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError))
+            throw error;
+        // The app would refuse to start with the same code; the rest is checked on the file alone.
+        add(error.code, 'error', target.file, `${error.message}. ${error.fix}`, 'dokebi-config', {
+            issues: error.issues,
+        });
+        // A settings file that does not parse has nothing more to check; a secrets problem leaves
+        // the settings file itself readable.
+        if (!error.code.startsWith('CONFIG_SECRETS') && !/secrets file/.test(error.message))
+            return found;
+        options = parseConfig(source).options;
+    }
+    const state = readState(parseObject(await readFile(join(root, '.dokebi/state.json'), 'utf8'), 'state'));
+    const installed = new Set(state.plugins.map((plugin) => optionsKey(plugin)));
+    // The same state `dokebi check` names for several workers (D-0161): in production one process
+    // is refused too (a restart loses it).
+    const redis = Object.keys(valueAt(options['dokebi-redis'], ['connections']) ??
+        {})[0];
+    for (const item of kept(installed, options))
+        add('STATE_NOT_SHARED', 'error', item.path.join('.'), `${item.what} would live in one process and be lost on every restart; the plugin refuses to start so in production (D-0161): ${item.fix(redis)}`, item.path[0] ?? null);
+    for (const plugin of ['dokebi-lock', 'dokebi-cache'])
+        if (installed.has(plugin)) {
+            const backends = valueAt(options[plugin], ['backends']);
+            for (const [name, backend] of Object.entries(backends && typeof backends === 'object' ? backends : {}))
+                if ((valueAt(backend, ['driver']) ?? 'local') === 'local')
+                    add('STATE_NOT_SHARED', 'warning', `${plugin}.backends.${name}`, `the ${name} backend is local to one process: right for one process, wrong for a cluster or two instances that must share it; use driver: redis for shared ${plugin === 'dokebi-lock' ? 'locks' : 'cache entries'}`, plugin);
+        }
+    if (installed.has('dokebi-mail')) {
+        const driver = valueAt(options['dokebi-mail'], ['transport', 'driver']) ?? 'log';
+        if (driver === 'log' || driver === 'capture')
+            add('TRANSPORT_NOT_FOR_PRODUCTION', 'error', 'dokebi-mail.transport.driver', `the ${String(driver)} transport keeps mail in memory and the plugin refuses it in production: set options.dokebi-mail.transport to smtp or ses`, 'dokebi-mail');
+    }
+    if (installed.has('dokebi-web')) {
+        const web = options['dokebi-web'];
+        const port = valueAt(web, ['port']);
+        if (typeof port !== 'number' || port === 0)
+            add('WEB_PORT_UNSET', 'error', 'dokebi-web.port', 'the port is 0 (any free port), so the reverse proxy cannot reach the app: set the instance port (deploy init writes it)', 'dokebi-web');
+        const trust = valueAt(web, ['trustProxy']);
+        if (!Array.isArray(trust) || trust.length === 0)
+            add('TRUST_PROXY_EMPTY', 'warning', 'dokebi-web.trustProxy', 'behind a reverse proxy the app must trust its address, or it ignores X-Forwarded-Proto and -Host (http URLs, cookies without Secure, wrong client addresses): list the proxy addresses, 127.0.0.1 and ::1 on the same server', 'dokebi-web');
+        const host = valueAt(web, ['host']) ?? '127.0.0.1';
+        if (host === '0.0.0.0' || host === '::')
+            add('WEB_LISTENS_EVERYWHERE', 'warning', 'dokebi-web.host', 'the app listens on every interface, so it can be reached without the reverse proxy (no TLS): listen on 127.0.0.1 unless a firewall closes the port', 'dokebi-web');
+    }
+    if (installed.has('dokebi-storage')) {
+        const storage = options['dokebi-storage'];
+        const directory = valueAt(storage, ['directory']) ?? '.dokebi/storage';
+        if ((valueAt(storage, ['driver']) ?? 'local') === 'local' && !isAbsolute(String(directory)))
+            add('STORAGE_RELATIVE', 'warning', 'dokebi-storage.directory', `the stored files go to ${String(directory)} inside the working folder, which a new release replaces: set an absolute folder outside the release (deploy init uses /var/lib/<app>/<instance>/storage)`, 'dokebi-storage');
+    }
+    const placeholders = placeholderPaths(options);
+    if (placeholders.length)
+        add('PLACEHOLDER_LEFT', 'error', target.file, `these options still hold a <placeholder> of the sample: ${placeholders.join(', ')}; fill them in the settings (or the secrets file)`, null, { paths: placeholders });
+    if (!found.some((item) => item.code.startsWith('CONFIG_SECRETS'))) {
+        try {
+            const secrets = await configSecrets(root, env);
+            for (const warning of secrets.warnings ?? [])
+                add(warning.code, 'warning', warning.path, warning.hint);
+            const unlisted = secrets.missing.filter((path) => !secrets.listed.includes(path));
+            if (unlisted.length)
+                add('SECRETS_MISSING', 'error', target.file, `secrets the installed plugins need are not set: ${unlisted.join(', ')}; put them in the secrets file (npx dokebi config secrets --json)`, null, { paths: unlisted });
+        }
+        catch (error) {
+            if (!(error instanceof CliError))
+                throw error;
+            add(error.code, 'error', target.file, error.message);
+        }
+    }
+    if (installed.has('dokebi-migrate')) {
+        const status = await migrationStatus(root, {
+            ...env,
+            ...(env.DOKEBI_CONFIG ? {} : { DOKEBI_CONFIG: target.path }),
+        });
+        if (!status?.results)
+            add('MIGRATIONS_UNCHECKED', 'error', 'dokebi-migrate', `dokebi-migrate status could not read the migrations${status?.error?.code ? ` (${status.error.code}: ${status.error.message ?? ''})` : ''}: check its options and that the database is reachable with these settings (npx dokebi-migrate status)`, 'dokebi-migrate');
+        else
+            for (const [connection, list] of Object.entries(status.results)) {
+                const pending = list.filter((item) => item.state === 'pending');
+                const before = pending
+                    .filter((item) => item.phase !== 'post-deploy')
+                    .map((item) => item.name);
+                const after = pending
+                    .filter((item) => item.phase === 'post-deploy')
+                    .map((item) => item.name);
+                const missing = list.filter((item) => item.state === 'missing').map((item) => item.name);
+                if (before.length)
+                    add('MIGRATIONS_PENDING', 'error', `dokebi-migrate.connections.${connection}`, `${before.length} migration(s) to apply before the new code starts: ${before.join(', ')}; run npx dokebi-migrate up --phase pre-deploy --json (DEPLOY.md, release step 2)`, 'dokebi-migrate');
+                if (after.length)
+                    add('MIGRATIONS_POST_DEPLOY_PENDING', 'warning', `dokebi-migrate.connections.${connection}`, `post-deploy migration(s) wait for the switch: ${after.join(', ')}; run npx dokebi-migrate up --json after the new code runs`, 'dokebi-migrate');
+                if (missing.length)
+                    add('MIGRATION_FILE_MISSING', 'warning', `dokebi-migrate.connections.${connection}`, `applied migrations whose files are gone (an older release folder?): ${missing.join(', ')}`, 'dokebi-migrate');
+            }
+    }
+    debug('Production checks done', {
+        errors: found.filter((item) => item.severity === 'error').length,
+        warnings: found.filter((item) => item.severity === 'warning').length,
+        secretsFile: secretsFile !== undefined,
+    });
+    return found;
+}

package/dist/project-guide.d.ts

@@ -1,3 +1,4 @@
+import type { Catalog } from './catalog.js';
 import type { PluginManifest } from './manifest.js';
 import type { RequiredPlugin } from './required-plugins.js';
 /** Markers of the CLI-maintained list of installed packages in AGENTS.md (D-0065). */
@@ -7,6 +8,12 @@ export declare const AGENTS_FILE = "AGENTS.md";
 export declare const CLAUDE_FILE = "CLAUDE.md";
 /** CLAUDE.md of a new project: Claude Code reads AGENTS.md through this import line. */
 export declare const CLAUDE_GUIDE = "@AGENTS.md\n";
+/**
+ * Markers of the project's own block in AGENTS.md (D-0077 G): the people of the project (or their
+ * tools) write rules there; the CLI never changes what is between them and doctor never judges it.
+ */
+export declare const PROJECT_START = "<!-- dokebi:project:start -->";
+export declare const PROJECT_END = "<!-- dokebi:project:end -->";
 /** One row of the installed list: a package, its version and its AI guide path. */
 export interface InstalledEntry {
     readonly id: string;
@@ -32,5 +39,16 @@ export declare function installedBlockEdited(text: string, entries: readonly Ins
  * of order (the developer removed them; doctor reports GUIDE_BLOCK_MISSING and the file stays).
  */
 export declare function replaceInstalledBlock(text: string, block: string): string | undefined;
+/** The project block as init writes it (and as it is added to an older AGENTS.md). */
+export declare function projectBlock(): string;
+/**
+ * The state of the project block in an AGENTS.md text: `ok` (one start, then one end, outside
+ * the installed list), `missing` (no marker at all: the next add, upgrade or remove adds an
+ * empty block) or `invalid` (a marker alone, repeated, out of order, or inside the installed
+ * list: doctor warns GUIDE_PROJECT_BLOCK_INVALID and the CLI leaves the file alone).
+ */
+export declare function projectBlockState(text: string): 'ok' | 'missing' | 'invalid';
+/** The text with an empty project block (and its heading) added at the end. */
+export declare function withProjectBlock(text: string): string;
 /** AGENTS.md of a new project (D-0065 skeleton): ask first, use the catalog, verify last. */
-export declare function projectGuide(entries: readonly InstalledEntry[]): string;
+export declare function projectGuide(entries: readonly InstalledEntry[], catalog?: Catalog): string;