@dokebi/cli 0.4.2 → 0.4.26

package/dist/install-plan.js

@@ -1,7 +1,7 @@
 import { path as paths } from '@dokebi/core/libraries';
+import { validateDefaults } from './config-values.js';
 import { CliError } from './errors.js';
 import { object, relativePath, templateTarget } from './filesystem.js';
-import { validateDefaults } from './merge-install-defaults.js';
 /**
  * Who edits a written file (D-0065 §11): `user` — a scaffold written once for the developer to
  * change (layouts, views, examples); doctor never reports an edit, upgrade keeps an edited copy.
@@ -71,8 +71,10 @@ export function readInstallPlan(value, legacy, extended = true) {
             try {
                 validateDefaults(plan.configDefaults);
             }
-            catch {
-                throw new CliError('INVALID_MANIFEST', 'Invalid install configuration defaults');
+            catch (cause) {
+                throw new CliError('INVALID_MANIFEST', 'Invalid install configuration defaults', {
+                    cause,
+                });
             }
             configDefaults = plan.configDefaults;
         }

package/dist/layout.d.ts

@@ -1,7 +1,9 @@
 import type { InstallPlan } from './install-plan.js';
 /**
  * Project layout (D-0031, D-0032). Plugins write only into
- * - `src/shared/<area>/…` — shared business code: models, modules (D-0032), views
+ * - `src/shared/<area>/…` — shared business code: models, services, modules (D-0032), views,
+ *   mail templates and locales (the consumer-facing rule is "Files and folders" in
+ *   capability-guide.ts, D-0092 §3)
  * - `src/infra/<name>/…` — code that wires a plugin up (connections, types, shared props …)
  * Files sit inside such a folder; plugins may also create the folder itself.
  * The plugin that hosts apps (manifest `dokebi.hosts: ["apps"]`, D-0070) also prepares `src/apps/`
@@ -16,3 +18,12 @@ export declare function assertLayout(plan: Pick<InstallPlan, 'files' | 'director
 }, pluginId: string, hosts?: readonly string[]): void;
 /** Installed entry paths from before D-0031 keep working; doctor reports them once. */
 export declare function legacyLayout(path: string, hosts?: readonly string[]): boolean;
+/**
+ * Source files older recipes wrote outside the "Files and folders" rule (the src root holds only
+ * main.ts and dokebi.generated.ts), mapped to where the current recipe writes them. Such a file
+ * keeps working where it is: doctor reports it as a LEGACY_LAYOUT warning that names the new
+ * place, and a re-run of the recipe keeps using the old file instead of writing a second copy.
+ * Moving it stays the developer's step because the file is user code (its relative imports and
+ * the import in src/main.ts change with it).
+ */
+export declare const MOVED_RECIPE_FILES: Readonly<Record<string, string>>;

package/dist/layout.js

@@ -2,7 +2,9 @@ import { path as paths } from '@dokebi/core/libraries';
 import { CliError } from './errors.js';
 /**
  * Project layout (D-0031, D-0032). Plugins write only into
- * - `src/shared/<area>/…` — shared business code: models, modules (D-0032), views
+ * - `src/shared/<area>/…` — shared business code: models, services, modules (D-0032), views,
+ *   mail templates and locales (the consumer-facing rule is "Files and folders" in
+ *   capability-guide.ts, D-0092 §3)
  * - `src/infra/<name>/…` — code that wires a plugin up (connections, types, shared props …)
  * Files sit inside such a folder; plugins may also create the folder itself.
  * The plugin that hosts apps (manifest `dokebi.hosts: ["apps"]`, D-0070) also prepares `src/apps/`
@@ -10,11 +12,11 @@ import { CliError } from './errors.js';
  */
 export function layoutAllowed(path, hosts = [], kind = 'file') {
     const key = paths.portablePathKey(path);
-    // Files live inside a named folder: src/shared/<area>/… (models, modules, views — D-0032) or
-    // src/infra/<name>/…
+    // Files live inside a named folder: src/shared/<area>/… (models, services, modules, views, mail,
+    // locales — D-0032, D-0092) or src/infra/<name>/…
     const area = kind === 'file'
-        ? /^src\/(shared\/(models|modules|views)|infra\/[^/]+)\/.+$/
-        : /^src\/(shared\/(models|modules|views)|infra\/[^/]+)(\/.+)?$/;
+        ? /^src\/(shared\/(models|services|modules|views|mail|locales)|infra\/[^/]+)\/.+$/
+        : /^src\/(shared\/(models|services|modules|views|mail|locales)|infra\/[^/]+)(\/.+)?$/;
     if (area.test(key))
         return true;
     return hosts.includes('apps') && (key === 'src/apps' || key.startsWith('src/apps/'));
@@ -28,9 +30,20 @@ export function assertLayout(plan, pluginId, hosts = []) {
     ];
     for (const [target, kind] of targets)
         if (!layoutAllowed(target, hosts, kind))
-            throw new CliError('INVALID_MANIFEST', `Plugin ${pluginId} writes outside src/shared/{models,modules,views}/ and src/infra/<name>/: ${target}`);
+            throw new CliError('INVALID_MANIFEST', `Plugin ${pluginId} writes outside src/shared/{models,services,modules,views,mail,locales}/ and src/infra/<name>/: ${target}`);
 }
 /** Installed entry paths from before D-0031 keep working; doctor reports them once. */
 export function legacyLayout(path, hosts = []) {
     return !layoutAllowed(path, hosts);
 }
+/**
+ * Source files older recipes wrote outside the "Files and folders" rule (the src root holds only
+ * main.ts and dokebi.generated.ts), mapped to where the current recipe writes them. Such a file
+ * keeps working where it is: doctor reports it as a LEGACY_LAYOUT warning that names the new
+ * place, and a re-run of the recipe keeps using the old file instead of writing a second copy.
+ * Moving it stays the developer's step because the file is user code (its relative imports and
+ * the import in src/main.ts change with it).
+ */
+export const MOVED_RECIPE_FILES = Object.freeze({
+    'src/site-worker.ts': 'src/infra/runtime/site-worker.ts',
+});

package/dist/log-writer-control.d.ts

@@ -28,6 +28,8 @@ export type ControlRequest = {
     op: 'stop';
     timeoutMs: number;
     force: boolean;
+} | {
+    op: 'reload';
 };
 /** The writer answered: its proven identity and its reply to the request. */
 export interface ControlReached {

package/dist/log-writer-control.js

@@ -13,10 +13,12 @@
 //   client → { challenge: C, answer: HMAC(token, 'dokebi-log-writer:client:' + W) }
 //   writer → { ok: false, code: 'UNAUTHORIZED' } and closes, or
 //            { ok: true, answer: HMAC(token, 'dokebi-log-writer:writer:' + C), writer, app }
-//   client → { op: 'status' } | { op: 'stop', timeoutMs, force }   (only after checking answer)
+//   client → { op: 'status' } | { op: 'stop', timeoutMs, force } | { op: 'reload' }
+//            (only after checking answer)
 //   writer → status: { ok: true, app: { pid, running } }
 //            stop:   { ok: true, stopped, forced, ms } | { ok: false, code: 'STOP_TIMEOUT', message }
-// Only `status` and `stop` exist. The writer closes the connection when it exits, so a client
+//            reload: { ok: true, signalled } (D-0154: SIGHUP to the app; it reads dokebi.yaml again)
+// Only `status`, `stop` and `reload` exist. The writer closes the connection when it exits, so a client
 // that asked for a stop knows the writer finished (its log closed) when the connection ends.
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { createConnection, createServer } from 'node:net';
@@ -278,6 +280,19 @@ export class ControlServer {
             lines.socket.end();
             return;
         }
+        if (request.op === 'reload') {
+            // D-0154: the CLI checked that the app reads dokebi.yaml again on SIGHUP before asking.
+            const running = app.running();
+            if (running)
+                app.signal('SIGHUP');
+            debug('Signalled the app to reload its configuration on a control request', {
+                pid: app.pid,
+                running,
+            });
+            lines.send({ ok: true, signalled: running });
+            lines.socket.end();
+            return;
+        }
         const timeoutMs = request.timeoutMs;
         if (request.op !== 'stop' ||
             !Number.isSafeInteger(timeoutMs) ||

package/dist/log-writer.js

@@ -17,6 +17,7 @@ import { spawn } from 'node:child_process';
 import { setTimeout as delay } from 'node:timers/promises';
 import { debug, describeError, reportError } from './diagnostics.js';
 import { ControlServer } from './log-writer-control.js';
+import { endLeftovers, PROCESS_GROUPS } from './process-group.js';
 import { forwardOutput, LineBuffer, RotatingLog } from './rotating-log.js';
 /** Written by the generated `src/main.ts` once `app.start()` resolved. */
 const STARTED = 'Dokebi application started';
@@ -24,6 +25,11 @@ const STARTED = 'Dokebi application started';
 const DRAIN_MS = 3000;
 /** An unfinished line is written after this much quiet. */
 const PARTIAL_MS = 200;
+/**
+ * How long processes the app left in its group get after SIGTERM before SIGKILL (less than
+ * DRAIN_MS, so one that holds the pipes is gone before the writer stops reading them).
+ */
+const LEFTOVER_MS = 2000;
 function send(message, then) {
     if (!process.connected) {
         then?.();
@@ -79,13 +85,33 @@ function run(file, maxBytes, keep, entry, control) {
         return;
     }
     log.write(Buffer.from(`\n--- dokebi start ${new Date().toISOString()} ---\n`));
-    const app = spawn(process.execPath, [entry], { stdio: ['ignore', 'pipe', 'pipe'] });
-    // `ready` goes to the CLI only after the start line is in app.log (forwardOutput).
-    const write = forwardOutput(log, STARTED, () => {
-        debug('Start line written to the app log', { pid: app.pid });
+    // DOKEBI_LOG_WRITER (D-0151): this writer rotates app.log, so @dokebi/logger skips its file
+    // targets here (no second set of rotated files) unless a target sets withDokebiStart.
+    // The IPC channel carries the generated main's `{ dokebi: 'started' }` (AI-M43): a
+    // logging.level above info hides the start line, and the app is still up.
+    // The app leads a process group of its own (POSIX): what it starts and leaves behind when it
+    // exits (stopped, crashed or killed) is found there and ended, never left holding a port.
+    const app = spawn(process.execPath, [entry], {
+        stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+        env: { ...process.env, DOKEBI_LOG_WRITER: '1' },
+        detached: PROCESS_GROUPS,
+    });
+    let announced = false;
+    const ready = (how) => {
+        if (announced)
+            return;
+        announced = true;
+        debug('App ready', { pid: app.pid, how });
         send({ ready: true });
+    };
+    app.on('message', (message) => {
+        if (message?.dokebi === 'started')
+            ready('ipc message');
     });
+    // `ready` goes to the CLI after the start line is in app.log (forwardOutput), or on the message.
+    const write = forwardOutput(log, STARTED, () => ready('start line'));
     let exit;
+    let leftovers = Promise.resolve('none');
     let open = 2;
     let finished = false;
     let drainExpired = false;
@@ -93,13 +119,18 @@ function run(file, maxBytes, keep, entry, control) {
         if (finished || !exit || (open > 0 && !drainExpired))
             return;
         finished = true;
-        const how = exit.signal ? `signal ${exit.signal}` : `code ${exit.code}`;
-        log.write(Buffer.from(`--- dokebi: app exited (${how}) ---\n`));
-        log.close();
-        debug('Log writer finished', { pid: app.pid, code: exit.code, signal: exit.signal });
         const { code, signal } = exit;
-        // A client waiting on the control port learns that the writer is done when it closes.
-        void (control?.close() ?? Promise.resolve()).then(() => send({ exited: code, signal }, () => process.exit(0)));
+        const how = signal ? `signal ${signal}` : `code ${code}`;
+        log.write(Buffer.from(`--- dokebi: app exited (${how}) ---\n`));
+        void leftovers.then((ended) => {
+            // Said in app.log, next to the app's own last lines.
+            if (ended !== 'none')
+                log.write(Buffer.from(`--- dokebi: processes the app started were still running; ended them (${ended === 'killed' ? 'SIGKILL' : 'SIGTERM'}) ---\n`));
+            log.close();
+            debug('Log writer finished', { pid: app.pid, code, signal, leftovers: ended });
+            // A client waiting on the control port learns that the writer is done when it closes.
+            return (control?.close() ?? Promise.resolve()).then(() => send({ exited: code, signal }, () => process.exit(0)));
+        });
     };
     app.once('error', (error) => {
         // spawn failed (the app never ran): there is no exit event to wait for.
@@ -117,6 +148,8 @@ function run(file, maxBytes, keep, entry, control) {
     app.once('exit', (code, signal) => {
         exit = { code, signal };
         debug('App process exited; draining its output', { pid: app.pid, code, signal });
+        if (app.pid !== undefined)
+            leftovers = endLeftovers(app.pid, LEFTOVER_MS);
         setTimeout(() => {
             if (finished)
                 return;

package/dist/logging-config.d.ts

@@ -1,7 +1,7 @@
 /** Levels accepted by core for `options.logging` (D-0047). */
 export declare const LOG_LEVELS: readonly ['debug', 'info', 'warn', 'error', 'silent'];
 export interface LoggingDiagnostic {
-    code: 'INVALID_LOGGING_CONFIG' | 'LOGGING_PLUGIN_UNKNOWN';
+    code: 'INVALID_LOGGING_CONFIG' | 'LOGGING_PLUGIN_UNKNOWN' | 'LOGGING_OPTIONS_UNUSED';
     path: string;
     plugin: string | null;
     severity: 'error' | 'warning';
@@ -9,6 +9,11 @@ export interface LoggingDiagnostic {
 }
 /**
  * Checks `options.logging` the way core does at startup (an invalid value is an error there),
- * and warns about per-plugin levels for plugins this project does not have.
+ * and warns about per-plugin levels for plugins this project does not have. D-0151: keys other
+ * than level and plugins belong to the logger host (@dokebi/logger), whose options schema the
+ * plugin checks validate; without one installed they are a warning (core's console logger does
+ * not read them and warns LOGGING_OPTIONS_UNUSED at startup).
  */
-export declare function loggingDiagnostics(options: Record<string, unknown>, plugins: ReadonlySet<string>): LoggingDiagnostic[];
+export declare function loggingDiagnostics(options: Record<string, unknown>, plugins: ReadonlySet<string>, loggerHost?: string, 
+/** The settings file the options come from (R4CA-10: the one DOKEBI_CONFIG names, M50). */
+file?: string): LoggingDiagnostic[];

package/dist/logging-config.js

@@ -5,13 +5,18 @@ const isLevel = (value) => typeof value === 'string' && LOG_LEVELS.includes(valu
 const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 /**
  * Checks `options.logging` the way core does at startup (an invalid value is an error there),
- * and warns about per-plugin levels for plugins this project does not have.
+ * and warns about per-plugin levels for plugins this project does not have. D-0151: keys other
+ * than level and plugins belong to the logger host (@dokebi/logger), whose options schema the
+ * plugin checks validate; without one installed they are a warning (core's console logger does
+ * not read them and warns LOGGING_OPTIONS_UNUSED at startup).
  */
-export function loggingDiagnostics(options, plugins) {
+export function loggingDiagnostics(options, plugins, loggerHost, 
+/** The settings file the options come from (R4CA-10: the one DOKEBI_CONFIG names, M50). */
+file = CONFIG_FILE) {
     const value = options.logging;
     if (value === undefined || value === null)
         return [];
-    const base = `${CONFIG_FILE}#options.logging`;
+    const base = `${file}#options.logging`;
     const invalid = (path) => ({
         code: 'INVALID_LOGGING_CONFIG',
         path,
@@ -19,9 +24,18 @@ export function loggingDiagnostics(options, plugins) {
         severity: 'error',
         hint: `use one of: ${LOG_LEVELS.join(', ')}`,
     });
-    if (!isObject(value) || Object.keys(value).some((key) => key !== 'level' && key !== 'plugins'))
-        return [{ ...invalid(base), hint: 'logging takes only level and plugins' }];
+    if (!isObject(value))
+        return [{ ...invalid(base), hint: 'logging is an object' }];
     const result = [];
+    const others = Object.keys(value).filter((key) => key !== 'level' && key !== 'plugins');
+    if (others.length && loggerHost === undefined)
+        result.push({
+            code: 'LOGGING_OPTIONS_UNUSED',
+            path: base,
+            plugin: null,
+            severity: 'warning',
+            hint: `core reads only level and plugins; ${others.sort().join(', ')} need @dokebi/logger (npx dokebi add @dokebi/logger) or can be removed`,
+        });
     if (value.level !== undefined && !isLevel(value.level))
         result.push(invalid(`${base}.level`));
     if (value.plugins === undefined || value.plugins === null)

package/dist/manifest.d.ts

@@ -1,3 +1,4 @@
+import { CliError } from './errors.js';
 import { type FileOwner } from './install-plan.js';
 export interface Dependency {
     name: string;
@@ -43,9 +44,19 @@ export declare const POINT: RegExp;
  *   (`domains`, `apps`) and ships the app skeletons (`templates/app*`, `templates/inertia-build`).
  * - `modules`: receives the modules of `dokebi module add|remove` (src/shared/modules/<name>/
  *   module.ts appended to `entry.modules`) and ships their skeletons (`templates/module*`).
+ * - `logger` (D-0151): provides the application logger. Its package exports
+ *   `createLogger({ options })`; the generated registration exports a `createLogger` that calls
+ *   it (src/main.ts passes the result to `new Application({ logger })`) and hands the logger to
+ *   the plugin as `entry.logger`. Its options are `options.logging` (the block core reads for
+ *   levels), not `options.<id>`. It ships no templates.
  */
-export declare const HOST_ROLES: readonly ['apps', 'modules'];
+export declare const HOST_ROLES: readonly ['apps', 'modules', 'logger'];
 export type HostRole = (typeof HOST_ROLES)[number];
+/**
+ * Where a plugin's options live in dokebi.yaml: `options.<id>`, except the logger host's, which
+ * are `options.logging` (D-0151).
+ */
+export declare function optionsKey(plugin: Pick<PluginManifest, 'id' | 'hosts'>): string;
 /**
  * The installed plugin that hosts `role` (D-0070). More than one is HOST_CONFLICT; none is
  * HOST_MISSING, whose fix names the command that installs one.
@@ -66,6 +77,23 @@ export declare function readManifest(value: unknown, options?: {
 }): PluginManifest;
 /** Reads a manifest previously normalized into .dokebi/state.json. */
 export declare function readStoredManifest(value: unknown): PluginManifest;
+/** Why a missing dependency was not installed with the change (D-0116). */
+export type MissingReason = 'not-installed' | 'no-package' | 'needs-choice' | 'needs-settings';
+/**
+ * MISSING_DEPENDENCY (D-0116): `plugin` (at its version) requires `dependency`, which the project
+ * does not have. The message names both and the version; `details.fix` is the command that adds
+ * it (`npx dokebi add <package>`, then `afterwards` when given). Raised before anything is written.
+ */
+export declare function missingDependency(plugin: Pick<PluginManifest, 'id' | 'version'>, dependency: Dependency, options?: {
+    reason?: MissingReason;
+    /** The npm package, when the manifest does not name it (the catalog's). */
+    package?: string;
+    /** Sentence after the first one of the message: why it was not installed. */
+    why?: string;
+    /** The command to run after the add (for example the same upgrade again). */
+    afterwards?: string;
+    extra?: Record<string, unknown>;
+}): CliError;
 export declare function orderPlugins(plugins: PluginManifest[], coreVersion: string, requiredPlugins?: ReadonlyArray<{
     id: string;
 }>): PluginManifest[];

package/dist/manifest.js

@@ -1,5 +1,7 @@
+import lt from 'semver/functions/lt.js';
 import satisfies from 'semver/functions/satisfies.js';
 import valid from 'semver/functions/valid.js';
+import minVersion from 'semver/ranges/min-version.js';
 import validRange from 'semver/ranges/valid.js';
 import { CliError } from './errors.js';
 import { object, relativePath } from './filesystem.js';
@@ -16,8 +18,20 @@ export const POINT = /^[a-z0-9][a-z0-9._/-]{0,95}:[a-z0-9][a-z0-9._-]{0,63}$/;
  *   (`domains`, `apps`) and ships the app skeletons (`templates/app*`, `templates/inertia-build`).
  * - `modules`: receives the modules of `dokebi module add|remove` (src/shared/modules/<name>/
  *   module.ts appended to `entry.modules`) and ships their skeletons (`templates/module*`).
+ * - `logger` (D-0151): provides the application logger. Its package exports
+ *   `createLogger({ options })`; the generated registration exports a `createLogger` that calls
+ *   it (src/main.ts passes the result to `new Application({ logger })`) and hands the logger to
+ *   the plugin as `entry.logger`. Its options are `options.logging` (the block core reads for
+ *   levels), not `options.<id>`. It ships no templates.
  */
-export const HOST_ROLES = ['apps', 'modules'];
+export const HOST_ROLES = ['apps', 'modules', 'logger'];
+/**
+ * Where a plugin's options live in dokebi.yaml: `options.<id>`, except the logger host's, which
+ * are `options.logging` (D-0151).
+ */
+export function optionsKey(plugin) {
+    return plugin.hosts?.includes('logger') ? 'logging' : plugin.id;
+}
 /** At most this many points per list (core's definePlugin limit). */
 const MAX_POINTS = 64;
 /**
@@ -71,7 +85,13 @@ function readRoles(metadata) {
 }
 function field(value, label) {
     if (typeof value !== 'string' || !value)
-        throw new CliError('INVALID_MANIFEST', label);
+        throw new CliError('INVALID_MANIFEST', `The plugin manifest field ${label} must be a non-empty string`, {
+            details: {
+                field: label,
+                fix: 'the package was published with a broken dokebi manifest: use another version, or report it to its authors',
+            },
+            phase: 'plan',
+        });
     return value;
 }
 function readDependencies(value, extended) {
@@ -197,6 +217,35 @@ export function readStoredManifest(value) {
         },
     }, { checkLayout: false });
 }
+/** Whether `installed` is below every version of `range` (an upgrade of it can satisfy it). */
+function providerTooOld(installed, range) {
+    const lowest = minVersion(range);
+    return lowest !== null && lt(installed, lowest);
+}
+/**
+ * MISSING_DEPENDENCY (D-0116): `plugin` (at its version) requires `dependency`, which the project
+ * does not have. The message names both and the version; `details.fix` is the command that adds
+ * it (`npx dokebi add <package>`, then `afterwards` when given). Raised before anything is written.
+ */
+export function missingDependency(plugin, dependency, options = {}) {
+    const pkg = dependency.package ?? options.package;
+    const add = pkg ? `npx dokebi add ${pkg}` : `npx dokebi plugins search ${dependency.name} --json`;
+    return new CliError('MISSING_DEPENDENCY', `${plugin.id} ${plugin.version} requires ${dependency.name} ${dependency.version}, which is not installed${options.why ? `; ${options.why}` : ''}`, {
+        details: {
+            plugin: plugin.id,
+            version: plugin.version,
+            dependency: dependency.name,
+            range: dependency.version,
+            package: pkg ?? null,
+            reason: options.reason ?? 'not-installed',
+            ...options.extra,
+            fix: pkg
+                ? `${add}${options.afterwards ? `, then ${options.afterwards}` : ''}`
+                : `${add} (find the package of ${dependency.name}), add it with npx dokebi add <package>${options.afterwards ? `, then ${options.afterwards}` : ''}`,
+        },
+        phase: 'plan',
+    });
+}
 export function orderPlugins(plugins, coreVersion, requiredPlugins = []) {
     const byId = new Map(plugins.map((plugin) => [plugin.id, plugin]));
     if (byId.size !== plugins.length)
@@ -208,9 +257,26 @@ export function orderPlugins(plugins, coreVersion, requiredPlugins = []) {
         if (visited.has(plugin.id))
             return;
         if (visiting.has(plugin.id))
-            throw new CliError('DEPENDENCY_CYCLE', plugin.id);
+            throw new CliError('DEPENDENCY_CYCLE', `The plugin dependencies form a cycle through ${plugin.id}: ${[...visiting, plugin.id].join(' -> ')}`, {
+                details: {
+                    plugin: plugin.id,
+                    cycle: [...visiting, plugin.id],
+                    fix: `the manifests of these packages depend on each other; install versions that do not (npx dokebi plugins info ${plugin.id} --json), or report it to the package authors`,
+                },
+                phase: 'plan',
+            });
         if (!satisfies(coreVersion, plugin.core))
-            throw new CliError('INCOMPATIBLE_VERSION', plugin.id);
+            throw new CliError('INCOMPATIBLE_VERSION', `${plugin.id} ${plugin.version} needs @dokebi/core ${plugin.core}, but the project has core ${coreVersion}`, {
+                details: {
+                    plugin: plugin.id,
+                    version: plugin.version,
+                    requires: '@dokebi/core',
+                    range: plugin.core,
+                    installed: coreVersion,
+                    fix: `use a version of ${plugin.packageName} made for core ${coreVersion} (npx dokebi plugins info ${plugin.id} --json lists the compatible one)`,
+                },
+                phase: 'plan',
+            });
         visiting.add(plugin.id);
         for (const dep of plugin.dependencies) {
             if (requiredPlugins.some((required) => required.id === dep.name))
@@ -219,10 +285,22 @@ export function orderPlugins(plugins, coreVersion, requiredPlugins = []) {
             if (!provider) {
                 if (dep.optional)
                     continue;
-                throw new CliError('MISSING_DEPENDENCY', dep.name);
+                throw missingDependency(plugin, dep);
             }
             if (!satisfies(provider.version, dep.version))
-                throw new CliError('INCOMPATIBLE_VERSION', dep.name);
+                throw new CliError('INCOMPATIBLE_VERSION', `${plugin.id} ${plugin.version} requires ${dep.name} ${dep.version}, but ${provider.version} is installed`, {
+                    details: {
+                        plugin: plugin.id,
+                        version: plugin.version,
+                        requires: dep.name,
+                        range: dep.version,
+                        installed: provider.version,
+                        fix: providerTooOld(provider.version, dep.version)
+                            ? `npx dokebi upgrade ${dep.name} first (a version in ${dep.version}), then repeat this command`
+                            : `use a version of ${plugin.packageName} made for ${dep.name} ${provider.version} (npx dokebi plugins info ${plugin.id} --json)`,
+                    },
+                    phase: 'plan',
+                });
             visit(provider);
         }
         visiting.delete(plugin.id);

package/dist/merge-install-defaults.d.ts

@@ -1,2 +1 @@
-export declare function validateDefaults(value: unknown): asserts value is Record<string, unknown>;
 export declare function mergeInstallDefaults(source: string, id: string, defaults: unknown): string;

package/dist/merge-install-defaults.js

@@ -1,49 +1,9 @@
 import { isDeepStrictEqual } from 'node:util';
-import { isMap, parseDocument } from 'yaml';
+import { isMap, isScalar, parseDocument } from 'yaml';
+import { isPlainRecord, validateDefaults } from './config-values.js';
 import { parseProjectConfig, renderConfig } from './configuration.js';
+import { debug } from './diagnostics.js';
 import { CliError } from './errors.js';
-function invalid() {
-    throw new CliError('INVALID_INSTALL_DEFAULTS', 'Plugin defaults must be bounded JSON values within their own configuration namespace.');
-}
-function isRecord(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        !Array.isArray(value) &&
-        Object.getPrototypeOf(value) === Object.prototype);
-}
-export function validateDefaults(value) {
-    if (!isRecord(value))
-        invalid();
-    let count = 0;
-    const seen = new WeakSet();
-    const visit = (item, depth) => {
-        count += 1;
-        if (count > 2000 || depth > 16)
-            invalid();
-        if (item === null || typeof item === 'string' || typeof item === 'boolean')
-            return;
-        if (typeof item === 'number' && Number.isFinite(item))
-            return;
-        if (typeof item !== 'object' || item === null || seen.has(item))
-            invalid();
-        seen.add(item);
-        if (Array.isArray(item)) {
-            for (const child of item)
-                visit(child, depth + 1);
-            return;
-        }
-        if (!isRecord(item))
-            invalid();
-        for (const [key, child] of Object.entries(item)) {
-            if (['__proto__', 'constructor', 'prototype', '<<'].includes(key))
-                invalid();
-            visit(child, depth + 1);
-        }
-    };
-    visit(value, 0);
-    if (Buffer.byteLength(JSON.stringify(value)) > 1024 * 1024)
-        invalid();
-}
 export function mergeInstallDefaults(source, id, defaults) {
     validateDefaults(defaults);
     const before = parseProjectConfig(source);
@@ -56,14 +16,17 @@ export function mergeInstallDefaults(source, id, defaults) {
                 target.set(key, document.createNode(value));
             else {
                 const current = target.get(key, true);
-                if (isMap(current) && isRecord(value))
+                if (isMap(current) && isPlainRecord(value))
                     merge(current, value);
             }
         }
     };
     if (!document.hasIn(['options']))
         document.setIn(['options'], document.createNode({}));
-    if (!document.hasIn(['options', id]))
+    const section = document.getIn(['options', id], true);
+    // An empty section (`dokebi-web:` alone is null) takes the defaults like a missing one; before,
+    // they were dropped without a word.
+    if (!document.hasIn(['options', id]) || (isScalar(section) && section.value === null))
         document.setIn(['options', id], document.createNode(defaults));
     else {
         const target = document.getIn(['options', id], true);
@@ -73,7 +36,10 @@ export function mergeInstallDefaults(source, id, defaults) {
     const result = renderConfig(document);
     const after = parseProjectConfig(result);
     for (const [key, value] of Object.entries(before.options))
-        if (key !== id && !isDeepStrictEqual(value, after.options[key]))
-            invalid();
+        if (key !== id && !isDeepStrictEqual(value, after.options[key])) {
+            debug('Plugin defaults changed another namespace', { plugin: id, namespace: key });
+            throw new CliError('INVALID_INSTALL_DEFAULTS', 'Plugin defaults must be bounded JSON values within their own configuration namespace.', { details: { reason: `changes options.${key}`, plugin: id } });
+        }
+    debug('Plugin defaults merged', { plugin: id, keys: Object.keys(defaults).length });
     return result;
 }

package/dist/npm-client.d.ts

@@ -1,10 +1,44 @@
+/** How long one npm install, pack or workspace install may take by default (2 minutes). */
+export declare const NPM_TIMEOUT_MS = 120000;
+/** The environment variable that sets that limit in milliseconds (D-0110 §4). */
+export declare const NPM_TIMEOUT_ENV = "DOKEBI_NPM_TIMEOUT_MS";
+/** The shortest and the longest limit the variable may set: 1 second and 24 hours. */
+export declare const NPM_TIMEOUT_RANGE: {
+    readonly min: 1000;
+    readonly max: 86400000;
+};
+/**
+ * The time limit of the npm commands NpmClient runs: `DOKEBI_NPM_TIMEOUT_MS` (a whole number of
+ * milliseconds within NPM_TIMEOUT_RANGE) or NPM_TIMEOUT_MS. A slow registry or a large first
+ * install may need more; anything else in the variable is INVALID_ENV, never a silent default.
+ */
+export declare function npmTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/**
+ * D-0138: what NPM_FAILED says when npm's code is ERESOLVE. The newest catalog packages fit each
+ * other (scripts/catalog/peers.ts), but a newer one may need a newer version of a package the
+ * project has (session 0.4.4 needs web ^0.4.3); add and upgrade without a version pick one that
+ * fits, and a named version gets details.fix (project.ts #peerConflict). Otherwise the conflict
+ * comes from another package or from a registry that is not the one the project was installed
+ * from; neither is fixed by forcing npm.
+ */
+export declare const ERESOLVE_HINT = "npm could not fit the packages' peer ranges (stderr names them: 'Found: <installed>' and 'peer <package>@<range> from <new package>'). Do not retry with --legacy-peer-deps or --force: they install a combination the packages do not support. When the new package needs a newer version of one the project has, upgrade that one first (npx dokebi upgrade <its plugin id>) and repeat the command. Otherwise check that npm config get @dokebi:registry names the registry in package-lock.json's resolved URLs, and that the package named in stderr is a version this project's core supports.";
 export declare function packageSpec(spec: string, cwd: string): string;
 export declare function dependencyMap(pkg: Record<string, unknown>): Record<string, string>;
+/**
+ * The project-relative path of a `file:<path>.tgz` dependency that stays inside the project
+ * (`file:vendor/web-0.4.3.tgz`, as npm writes a tarball installed from the project), else undefined.
+ * The staging install gets a copy at the same path, so package.json and package-lock.json keep it
+ * relative and the project can move (2026-10-28).
+ */
+export declare function projectTarball(value: string): string | undefined;
 export declare function validateProjectPackage(pkg: Record<string, unknown>): void;
 export declare class NpmClient {
     #private;
-    /** Installs into a standalone directory (the project or the CLI's staging). */
-    install(directory: string, spec?: string): Promise<void>;
+    /**
+     * Installs into a standalone directory (the project or the CLI's staging): the package.json as
+     * it is, plus `spec` (one spec, or several in one npm run).
+     */
+    install(directory: string, spec?: string | readonly string[]): Promise<void>;
     /** `npm pack` of a workspace package into `destination`; returns the archive path (D-0035). */
     pack(directory: string, destination: string): Promise<string>;
     /** `npm install` at a workspace root: brings its lock and node_modules in line (D-0035). */
@@ -74,7 +108,9 @@ export declare class NpmFailureNotes {
     };
 }
 /**
- * Removes credentials npm may print: `user:password@` in URLs, `_authToken=`/`_auth=`/
- * `_password=` values (npmrc lines), bearer tokens and npm access tokens (`npm_…`).
+ * Removes credentials npm may print: `user:password@` in URLs (core's rule, which also takes a
+ * raw `/` inside a password: `//app:Zm9v/YmFy@db` kept the part after the slash before),
+ * `_authToken=`/`_auth=`/`_password=` values (npmrc lines), bearer tokens and npm access tokens
+ * (`npm_…`).
  */
 export declare function redactNpmOutput(text: string): string;