@dokebi/cli 0.4.1 → 0.4.26

package/dist/describe.js

@@ -0,0 +1,417 @@
+// `dokebi describe [--json]` (D-0077 B): what the app has — routes, pages, jobs, schedules, error
+// codes, option keys and environment variable names — without serving traffic. The project is
+// loaded like `dokebi start` loads it (the settings file, M50; the generated registration, the project's
+// .env under the CLI's environment), in a child process, but in core's describe mode: every
+// plugin's setup runs, no start or ready hook (nothing listens, nothing connects), and the
+// describers plugins contributed are asked. No value of an option or a variable is ever printed.
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { redaction } from '@dokebi/core/libraries';
+import { configTarget, readNamedSettings } from './configuration.js';
+import { DB_NOT_READ, describeDatabases } from './describe-db.js';
+import { debug, describeError, maskTexts } from './diagnostics.js';
+import { appEnvironment } from './env-file.js';
+import { CliError } from './errors.js';
+import { checkProject, installedVersion } from './server.js';
+/** The JSON Schema of `result` (shipped next to dist/: packages/cli/describe.schema.json). */
+export const DESCRIBE_SCHEMA_FILE = 'describe.schema.json';
+export const DESCRIBE_SCHEMA_VERSION = 1;
+/** Default limit for loading and describing the app. */
+export const DESCRIBE_TIMEOUT_MS = 30_000;
+/** How long the child may take to exit once it answered. */
+const EXIT_GRACE_MS = 5_000;
+/** The section names that are lists in the result; every other section goes under `app`. */
+const LISTS = new Set(['routes', 'pages', 'jobs', 'schedules', 'env']);
+/**
+ * Runs in the project's folder (`node --input-type=module --eval`): bare specifiers resolve from
+ * the project's node_modules and relative ones from its root, like src/main.ts.
+ */
+export const DESCRIBE_RUNNER = `import { existsSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+const base = pathToFileURL(process.cwd() + '/');
+const reason = (error) => {
+  let text;
+  try { text = error instanceof Error ? error.message : String(error); } catch { text = typeof error; }
+  return (String(text).split('\\n', 1)[0] || 'Unknown error').replace(/\\/\\/[^\\s/]*@/g, '//***@').slice(0, 500);
+};
+const answer = (message) =>
+  new Promise((resolve) => process.send(message, () => resolve(undefined)));
+try {
+  const { Application, loadConfig, definePoint } = await import('@dokebi/core');
+  if (typeof Application.prototype.describe !== 'function') {
+    await answer({ type: 'failure', code: 'DESCRIBE_UNSUPPORTED', message: 'The installed @dokebi/core cannot describe an app' });
+  } else {
+    // M50: the settings file the app reads, resolved by the CLI (DOKEBI_CONFIG, else dokebi.yaml).
+    const settings = process.env.DOKEBI_CLI_SETTINGS_FILE;
+    const document = await loadConfig(settings ? settings : new URL('dokebi.yaml', base));
+    const app = new Application({ config: document.options, runtime: { describing: true } });
+    const { registerPlugins } = await import(new URL('src/dokebi.generated.ts', base).href);
+    await registerPlugins(app);
+    const previewInput = process.env.DOKEBI_CLI_MAIL_PREVIEW;
+    if (previewInput) {
+      const input = JSON.parse(previewInput);
+      const { dependency } = await import('@dokebi/mail');
+      const point = definePoint('core:describe');
+      app.register({
+        metadata: { name: 'cli-mail-preview', version: '1.0.0', core: '*', dependencies: [dependency], contributes: ['core:describe'] },
+        setup(context) {
+          const mail = context.getDependency(dependency);
+          context.logger.log('debug', 'Preparing mail template preview', { template: input.name });
+          context.contribute(point, { section: 'mail-preview', describe: async () => {
+            if (typeof mail.preview !== 'function') throw Object.assign(new Error('Upgrade @dokebi/mail for template preview'), { code: 'MAIL_PREVIEW_UNSUPPORTED' });
+            const result = await mail.preview(input.name, input.locale);
+            if (!result) throw Object.assign(new Error('Mail template does not exist'), { code: 'MAIL_TEMPLATE_NOT_FOUND' });
+            return result;
+          } });
+        },
+      });
+    }
+    const description = await app.describe();
+    let errors = { file: false };
+    const file = new URL('src/shared/errors.ts', base);
+    if (existsSync(file)) {
+      try {
+        const module = await import(file.href);
+        // errorCatalog of @dokebi/web 0.4.3 (D-0077 D) joins every defineErrors result exported.
+        const web = await import('@dokebi/web');
+        if (typeof web.errorCatalog !== 'function') throw Object.assign(new Error('The installed @dokebi/web has no errorCatalog (0.4.3 or later)'), { code: 'ERRORS_UNREADABLE' });
+        const definitions = (web.errorCatalog(module) ?? []).map((item) => ({
+          code: item.code,
+          status: item.status,
+          message: item.message,
+          ...(typeof item.hint === 'string' ? { hint: item.hint } : {}),
+        }));
+        errors = { file: true, definitions };
+      } catch (error) {
+        errors = { file: true, failure: { code: typeof error?.code === 'string' ? error.code : 'ERRORS_UNREADABLE', reason: reason(error) } };
+      }
+    }
+    await answer({ type: 'description', description, errors });
+  }
+} catch (error) {
+  await answer({
+    type: 'failure',
+    code: typeof error?.code === 'string' ? error.code : 'DESCRIBE_FAILED',
+    message: reason(error),
+    ...(typeof error?.plugin === 'string' ? { plugin: error.plugin } : {}),
+  });
+  process.exitCode = 1;
+}
+process.disconnect();
+`;
+function projectName(root) {
+    try {
+        const name = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).name;
+        return typeof name === 'string' ? name : null;
+    }
+    catch (error) {
+        debug('Unable to read the project name for describe', { error: describeError(error) });
+        return null;
+    }
+}
+/** Loads the project in describe mode in a child process and returns what it said. */
+async function run(root, timeoutMs, mailPreview) {
+    // M50: the app loads the file DOKEBI_CONFIG names (else dokebi.yaml), and so does describe; a
+    // named file that cannot be read is READ_FAILED, never dokebi.yaml instead.
+    const settings = await configTarget(root);
+    if (settings.fromEnvironment)
+        await readNamedSettings(root, settings);
+    debug('Describe loads the settings file', { file: settings.file });
+    const child = spawn(process.execPath, ['--input-type=module', '--disable-warning=ExperimentalWarning', '--eval', DESCRIBE_RUNNER], {
+        cwd: root,
+        // The project's .env under the CLI's environment, like dokebi start (D-0073).
+        env: {
+            ...appEnvironment(root, 'production'),
+            DOKEBI_CLI_MAIL_PREVIEW: mailPreview ? JSON.stringify(mailPreview) : '',
+            DOKEBI_CLI_SETTINGS_FILE: settings.path,
+        },
+        stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+    });
+    // The app's own log lines: kept for the error, never printed otherwise (bounded).
+    let output = '';
+    const keep = (chunk) => {
+        output = (output + chunk.toString('utf8')).slice(-16_384);
+    };
+    child.stdout?.on('data', keep);
+    child.stderr?.on('data', keep);
+    return await new Promise((resolve, reject) => {
+        let message;
+        let lingered = false;
+        let grace;
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            reject(new CliError('DESCRIBE_TIMEOUT', `The app did not describe itself within ${timeoutMs} ms`, {
+                details: {
+                    timeoutMs,
+                    fix: 'A plugin or the app code waits in setup (a connection, a long task); run with DOKEBI_LOG_LEVEL=debug, or pass --timeout-ms',
+                    output: tail(output),
+                },
+            }));
+        }, timeoutMs);
+        child.on('message', (received) => {
+            // The runner masks URL credentials itself; core's rule applies on this side as well.
+            message = maskTexts(received);
+            debug('Describe answer received', { type: message.type });
+            grace = setTimeout(() => {
+                lingered = true;
+                child.kill('SIGKILL');
+            }, EXIT_GRACE_MS);
+        });
+        child.once('error', (error) => {
+            clearTimeout(timer);
+            if (grace)
+                clearTimeout(grace);
+            reject(new CliError('DESCRIBE_FAILED', 'Unable to run the app to describe it', { cause: error }));
+        });
+        child.once('exit', (code, signal) => {
+            clearTimeout(timer);
+            if (grace)
+                clearTimeout(grace);
+            debug('Describe process exited', { code, signal, answered: message !== undefined });
+            if (message)
+                resolve({ message, lingered });
+            else
+                reject(new CliError('DESCRIBE_FAILED', 'The app exited before it described itself', {
+                    details: { exit: code ?? signal, output: tail(output) },
+                }));
+        });
+    });
+}
+/** The last lines of the app's output, URL credentials removed. */
+function tail(output) {
+    return output
+        .split('\n')
+        .filter(Boolean)
+        .slice(-20)
+        .map((line) => redaction.maskCredentials(line).slice(0, 2000));
+}
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+/** The CLI result from core's description and the error definitions. */
+export function shapeDescription(name, description, errors, ms, lingered = false) {
+    const unavailable = [...description.unavailable];
+    const lists = {
+        routes: [],
+        pages: [],
+        jobs: [],
+        schedules: [],
+        env: [],
+    };
+    const app = {
+        name,
+        core: description.core,
+        plugins: description.plugins,
+    };
+    let keys = [];
+    let db = {};
+    let constraint;
+    for (const { section, plugin, value } of description.sections) {
+        if (section === 'config' && plugin === 'core') {
+            keys = Array.isArray(record(value).keys) ? record(value).keys : [];
+            continue;
+        }
+        if (LISTS.has(section)) {
+            const list = lists[section];
+            if (Array.isArray(value))
+                for (const item of value)
+                    list.push(section === 'env' ? { ...record(item), plugin } : item);
+            else
+                unavailable.push({
+                    plugin,
+                    section,
+                    code: 'INVALID_SECTION',
+                    reason: `The ${section} section must be a list`,
+                });
+            continue;
+        }
+        if (section === 'db') {
+            db = { ...db, ...record(value) };
+            continue;
+        }
+        if (section === 'app') {
+            const given = record(value);
+            if (typeof given.constraint === 'string')
+                constraint = given.constraint;
+            for (const [key, item] of Object.entries(given))
+                if (key !== 'constraint')
+                    app[key] = item;
+            continue;
+        }
+        if (Object.hasOwn(app, section)) {
+            unavailable.push({
+                plugin,
+                section,
+                code: 'DUPLICATE_SECTION',
+                reason: `Another plugin already described ${section}`,
+            });
+            continue;
+        }
+        app[section] = value;
+    }
+    // The effective login rule of each route (dokebi-auth gives them as auth.routes).
+    const rules = new Map();
+    const auth = record(app.auth);
+    if (Array.isArray(auth.routes)) {
+        for (const item of auth.routes) {
+            const { method, url, app: owner, ...rule } = record(item);
+            rules.set(`${String(method)} ${String(url)} ${typeof owner === 'string' ? owner : ''}`, rule);
+        }
+        const { routes: _routes, ...rest } = auth;
+        app.auth = rest;
+    }
+    // The app a route belongs to: dokebi-app's route constraint (its name is in the app section).
+    const routes = lists.routes.map((route) => {
+        const constraints = record(route.constraints);
+        const owner = constraint === undefined ? undefined : constraints[constraint];
+        const host = constraints.host;
+        const rule = rules.get(`${String(route.method)} ${String(route.url)} ${typeof owner === 'string' ? owner : ''}`);
+        return {
+            ...route,
+            ...(typeof owner === 'string' ? { app: owner } : {}),
+            ...(typeof host === 'string' ? { host } : {}),
+            ...(rule === undefined ? {} : { auth: rule }),
+        };
+    });
+    const env = new Map();
+    for (const item of lists.env)
+        if (typeof item.name === 'string' && !env.has(item.name))
+            env.set(item.name, item);
+    const definitions = [...(errors.definitions ?? [])];
+    if (errors.failure)
+        unavailable.push({
+            plugin: 'project',
+            section: 'errors',
+            code: errors.failure.code,
+            reason: errors.failure.reason,
+        });
+    return {
+        schemaVersion: DESCRIBE_SCHEMA_VERSION,
+        app,
+        routes,
+        pages: lists.pages,
+        jobs: lists.jobs,
+        schedules: lists.schedules,
+        errors: definitions,
+        config: { keys, env: [...env.values()] },
+        db: { ...db, unavailable: DB_NOT_READ },
+        unavailable,
+        ...(lingered
+            ? {
+                warnings: [
+                    {
+                        code: 'DESCRIBE_PROCESS_LINGERED',
+                        message: 'The app kept running after it described itself (an open handle) and was stopped',
+                    },
+                ],
+            }
+            : {}),
+        ms,
+    };
+}
+/** `dokebi describe`: loads the project in describe mode and returns the description. */
+export async function describeProject(root, options = {}) {
+    const started = Date.now();
+    await checkProject(root);
+    const core = installedVersion(root, '@dokebi/core');
+    if (core && core[0] === 0 && (core[1] < 4 || (core[1] === 4 && core[2] < 2)))
+        throw new CliError('DESCRIBE_UNSUPPORTED', `@dokebi/core ${core.join('.')} cannot describe an app`, {
+            details: {
+                core: core.join('.'),
+                fix: 'Install @dokebi/core 0.4.2 or later in the project (npm install @dokebi/core@^0.4.2)',
+            },
+        });
+    const timeoutMs = options.timeoutMs ?? DESCRIBE_TIMEOUT_MS;
+    debug('Describing the project', { timeoutMs });
+    const { message, lingered } = await run(root, timeoutMs, options.mailPreview);
+    if (message.type === 'failure')
+        throw new CliError(message.code, `The app could not be described: ${message.message}`, {
+            details: {
+                ...(message.plugin ? { plugin: message.plugin } : {}),
+                fix: message.code === 'DESCRIBE_UNSUPPORTED'
+                    ? 'Install @dokebi/core 0.4.2 or later in the project'
+                    : 'npx dokebi doctor, then fix what the message names (the app fails the same way at start)',
+            },
+        });
+    const result = shapeDescription(projectName(root), message.description, message.errors, Date.now() - started, lingered);
+    if (!options.withDb)
+        return result;
+    // D-0077 F: a separate step that connects (describe mode itself never does).
+    const listed = Array.isArray(result.db.connections)
+        ? result.db.connections
+        : [];
+    const connections = await describeDatabases(root, listed, timeoutMs);
+    return { ...result, db: { connections }, ms: Date.now() - started };
+}
+/** The db line of the summary. */
+function dbText(db) {
+    const connections = Array.isArray(db.connections)
+        ? db.connections
+        : [];
+    // D-0127: an optional connection is marked; the default (required) is not.
+    const named = (item) => `${String(item.name)}${item.startup === 'optional' ? ' [optional]' : ''}`;
+    if (typeof db.unavailable === 'string')
+        return `db: ${connections.length ? `${connections.map((item) => `${named(item)} (${String(item.adapter)})`).join(', ')}; ` : ''}${db.unavailable}`;
+    if (!connections.length)
+        return 'db: no connections';
+    return `db: ${connections
+        .map((item) => {
+        if (typeof item.unavailable === 'string')
+            return `${named(item)} unavailable (${item.unavailable})`;
+        const tables = Array.isArray(item.tables) ? item.tables : undefined;
+        const collections = Array.isArray(item.collections) ? item.collections : [];
+        return `${named(item)} (${String(item.dialect)}) ${tables ? `${tables.length} tables` : `${collections.length} collections`}`;
+    })
+        .join('; ')}`;
+}
+/** Module plugins are `dokebi-module.<name>` (D-0032). */
+const MODULE_PREFIX = 'dokebi-module.';
+/**
+ * D-0130: what each module contributes to and who collects it, one line per module point, e.g.
+ * `module points: dokebi-module.notes -> dokebi-mcp:tools (collected by dokebi-mcp)`. A point no
+ * plugin collects says so: its values are dropped (warn POINT_NOT_COLLECTED at start).
+ */
+export function modulePointsText(plugins) {
+    const collectors = new Map();
+    for (const plugin of plugins)
+        for (const point of plugin.collects ?? [])
+            collectors.set(point, [...(collectors.get(point) ?? []), plugin.name]);
+    const lines = [];
+    for (const plugin of plugins) {
+        if (!plugin.name.startsWith(MODULE_PREFIX))
+            continue;
+        for (const point of plugin.contributes ?? []) {
+            const by = collectors.get(point);
+            lines.push(`module points: ${plugin.name} -> ${point} (${by ? `collected by ${by.join(', ')}` : 'no plugin collects it: the values are dropped'})`);
+        }
+    }
+    return lines;
+}
+/** The short human summary. */
+export function describeText(result) {
+    const plugins = result.app.plugins;
+    const methods = new Map();
+    for (const route of result.routes) {
+        const method = String(route.method);
+        methods.set(method, (methods.get(method) ?? 0) + 1);
+    }
+    const guarded = result.routes.filter((route) => record(route.auth).mode === 'required').length;
+    const engines = new Map();
+    for (const page of result.pages)
+        engines.set(String(page.engine), (engines.get(String(page.engine)) ?? 0) + 1);
+    const count = (map) => [...map].map(([key, value]) => `${key} ${value}`).join(', ');
+    const lines = [
+        `app ${result.app.name ?? '(no name)'}: ${plugins.length} plugins, core ${String(result.app.core)}`,
+        `routes: ${result.routes.length}${methods.size ? ` (${count(methods)})` : ''}${guarded ? `, ${guarded} need a login` : ''}`,
+        `pages: ${result.pages.length}${engines.size ? ` (${count(engines)})` : ''}`,
+        `jobs: ${result.jobs.length}, schedules: ${result.schedules.length}, error codes: ${result.errors.length}`,
+        `config: ${result.config.keys.length} option keys; environment: ${result.config.env.map((item) => item.name).join(', ') || 'none'}`,
+        dbText(result.db),
+        ...modulePointsText(plugins),
+        ...result.unavailable.map((item) => `unavailable: ${item.plugin}${item.section ? ` (${item.section})` : ''}: ${item.code} ${item.reason}`),
+        ...(result.warnings ?? []).map((item) => `warning: ${item.code} ${item.message}`),
+        'npx dokebi describe --json has every route, page, job, schedule, error code and option key',
+    ];
+    return `${lines.join('\n')}\n`;
+}

package/dist/dev-compose.d.ts

@@ -0,0 +1,20 @@
+/**
+ * D-0165: the passwords and tokens of the connections in dokebi.yaml, as the variables
+ * `dokebi dev-infra up` gives Compose: `DOKEBI_<PLUGIN>_<CONNECTION>_PASSWORD` (and `_TOKEN`), and
+ * without the connection for `main` (`DOKEBI_REDIS_PASSWORD`). A password is the one of a URL
+ * (`url`, `servers`) or a `password` or `pass` field; placeholders (`<…>`) are none. R5 Codex T4:
+ * a Redis with a password in compose.yaml could only get it from `.env` or a script of its own.
+ */
+export declare function connectionSecrets(options: Record<string, unknown>): Record<string, string>;
+/**
+ * Compose gets the passwords of dokebi.yaml in its child environment: the main database's as
+ * DOKEBI_DB_PASSWORD, and every connection's (D-0165, `connectionSecrets`).
+ */
+export declare function databaseEnvironment(root: string): Promise<NodeJS.ProcessEnv>;
+/** Fixed actions only: never expose Compose config/env output or delete data volumes. */
+export declare function runDevCompose(root: string, action: string, files?: string[]): Promise<{
+    action: string;
+    files: string[];
+    stdout: string;
+    stderr: string;
+}>;

package/dist/dev-compose.js

@@ -0,0 +1,154 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { loadConfig } from '@dokebi/core';
+import { configTarget, missingConfig } from './configuration.js';
+import { debug, describeError } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { exists, securePath } from './filesystem.js';
+const exec = promisify(execFile);
+const actions = {
+    up: ['up', '-d', '--wait'],
+    start: ['start'],
+    stop: ['stop'],
+    down: ['down'],
+    status: ['ps', '--format', 'json'],
+};
+/** A variable name part: `dokebi-redis` → `REDIS`, `cache.eu` → `CACHE_EU`. */
+function variablePart(name) {
+    return name
+        .replace(/^dokebi-/, '')
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, '_')
+        .replace(/^_|_$/g, '');
+}
+/** The password of a URL (`redis://:secret@host`), or undefined. */
+function urlPassword(value) {
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(value))
+        return undefined;
+    try {
+        const password = new URL(value).password;
+        return password ? decodeURIComponent(password) : undefined;
+    }
+    catch (error) {
+        // Not a URL after all (the plugin reports its own option): no password to pass.
+        debug('A connection value is not a URL', { error: describeError(error) });
+        return undefined;
+    }
+}
+/**
+ * D-0165: the passwords and tokens of the connections in dokebi.yaml, as the variables
+ * `dokebi dev-infra up` gives Compose: `DOKEBI_<PLUGIN>_<CONNECTION>_PASSWORD` (and `_TOKEN`), and
+ * without the connection for `main` (`DOKEBI_REDIS_PASSWORD`). A password is the one of a URL
+ * (`url`, `servers`) or a `password` or `pass` field; placeholders (`<…>`) are none. R5 Codex T4:
+ * a Redis with a password in compose.yaml could only get it from `.env` or a script of its own.
+ */
+export function connectionSecrets(options) {
+    const found = {};
+    for (const [section, value] of Object.entries(options)) {
+        const connections = value?.connections;
+        if (!connections || typeof connections !== 'object' || Array.isArray(connections))
+            continue;
+        for (const [name, connection] of Object.entries(connections)) {
+            const secrets = {};
+            const walk = (item, key) => {
+                if (typeof item === 'string') {
+                    if (item.trim().startsWith('<'))
+                        return;
+                    if (key === 'token')
+                        secrets.TOKEN ??= item;
+                    else if (key === 'password' || key === 'pass')
+                        secrets.PASSWORD ??= item;
+                    else {
+                        const password = urlPassword(item);
+                        if (password !== undefined)
+                            secrets.PASSWORD ??= password;
+                    }
+                }
+                else if (Array.isArray(item))
+                    for (const entry of item)
+                        walk(entry, key);
+                else if (item && typeof item === 'object')
+                    for (const [child, entry] of Object.entries(item))
+                        walk(entry, child);
+            };
+            walk(connection, '');
+            const prefix = `DOKEBI_${variablePart(section)}`;
+            for (const [kind, secret] of Object.entries(secrets)) {
+                found[`${prefix}_${variablePart(name)}_${kind}`] = secret;
+                if (name === 'main')
+                    found[`${prefix}_${kind}`] = secret;
+            }
+        }
+    }
+    return found;
+}
+/**
+ * Compose gets the passwords of dokebi.yaml in its child environment: the main database's as
+ * DOKEBI_DB_PASSWORD, and every connection's (D-0165, `connectionSecrets`).
+ */
+export async function databaseEnvironment(root) {
+    // M50: the file the app reads; an empty DOKEBI_CONFIG is no value (D-0154 D4), never the
+    // project folder itself (`??` kept '' and loaded the folder).
+    const target = await configTarget(root);
+    // R3 Claude T4 review: a fresh copy without dokebi.yaml got INTERNAL_ERROR ("Unable to read
+    // configuration file") from dev-infra up.
+    if (!target.fromEnvironment && !(await exists(target.path)))
+        throw missingConfig(root, 'No dokebi.yaml: dev-infra up reads the database password from it');
+    const config = await loadConfig(target.path);
+    const db = config.options['dokebi-db'];
+    const value = db?.connections?.main?.options?.url;
+    const secrets = connectionSecrets(config.options);
+    if (value === undefined)
+        return secrets;
+    if (typeof value !== 'string' || value.startsWith('<'))
+        throw new CliError('DEV_INFRA_CONFIG_INVALID', 'Set the main database URL in dokebi.yaml first', {
+            details: {
+                // R3 Claude T4 review: the sample's placeholder names `npx dokebi dev-infra`; the error did not.
+                fix: 'run npx dokebi dev-infra first: it writes the development database URL into dokebi.yaml (and compose.yaml when there is none); or set your own URL there',
+            },
+        });
+    try {
+        return { ...secrets, DOKEBI_DB_PASSWORD: decodeURIComponent(new URL(value).password) };
+    }
+    catch {
+        // dokebi-check: allow missing-cause the URL error carries its input, which holds the database password
+        throw new CliError('DEV_INFRA_CONFIG_INVALID', 'The main database URL is invalid');
+    }
+}
+/** Fixed actions only: never expose Compose config/env output or delete data volumes. */
+export async function runDevCompose(root, action, files = ['compose.yaml']) {
+    if (!Object.hasOwn(actions, action))
+        throw new CliError('USAGE', 'dev-infra action must be up, start, stop, down or status');
+    if (!files.length)
+        throw new CliError('USAGE', 'At least one Compose file is required');
+    const paths = await Promise.all(files.map((file) => securePath(root, file)));
+    const environment = await databaseEnvironment(root);
+    const password = environment.DOKEBI_DB_PASSWORD;
+    const mask = (value) => {
+        if (!password)
+            return value;
+        return value
+            .replaceAll(password, '<secret>')
+            .replaceAll(encodeURIComponent(password), '<secret>');
+    };
+    debug('Running development infrastructure', { action, files });
+    try {
+        const { stdout, stderr } = await exec('docker', [
+            'compose',
+            ...paths.flatMap((path) => ['-f', path]),
+            ...actions[action],
+        ], {
+            cwd: root,
+            env: { ...process.env, ...environment },
+            timeout: 300_000,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        return { action, files, stdout: mask(stdout), stderr: mask(stderr) };
+    }
+    catch (error) {
+        const failure = error;
+        throw new CliError('DEV_INFRA_FAILED', mask(failure.stderr || failure.message), {
+            details: { action, files },
+        });
+    }
+}

package/dist/dev-guard.js

@@ -1,8 +1,52 @@
 // Preloaded (`node --import`) into the processes `dokebi dev` starts (D-0044). They get an IPC
 // channel to dev; when dev dies, even by SIGKILL, the channel closes and the process drains
 // (SIGTERM) instead of living on as an orphan that holds the port or keeps building.
+//
+// D-0154: dev drives configuration reloads. It marks the process (core then does not watch
+// dokebi.yaml itself) and, when dokebi.yaml changed, asks over the channel; the app's reload hook
+// (registered by core's Application or @dokebi/cluster's runner once running) reads the file
+// again and the answer says whether dev must restart the app instead.
+const RELOAD_HOOK = Symbol.for('dokebi.config.reload.v1');
+const RELOAD_EXTERNAL = Symbol.for('dokebi.config.reload.external.v1');
+/** The fields of a reload result dev reads: outcome, code and paths, never values. */
+function answerOf(result) {
+    const list = (value) => Array.isArray(value) ? value.slice(0, 64).map((item) => String(item)) : undefined;
+    return {
+        outcome: typeof result.outcome === 'string' ? result.outcome : 'failed',
+        code: typeof result.code === 'string' ? result.code : undefined,
+        paths: list(result.paths),
+        restartRequired: list(result.restartRequired),
+    };
+}
 if (process.send) {
     process.once('disconnect', () => process.kill(process.pid, 'SIGTERM'));
+    const global = globalThis;
+    global[RELOAD_EXTERNAL] = true;
+    process.on('message', (message) => {
+        const request = message;
+        if (request?.dokebi !== 'dev-reload' || typeof request.id !== 'number')
+            return;
+        const id = request.id;
+        const reply = (fields) => {
+            try {
+                process.send?.({ dokebi: 'dev-reload-result', id, ...fields });
+            }
+            catch {
+                // dokebi-check: allow empty-catch the channel to dev is gone; dev restarts the app when no answer comes
+            }
+        };
+        const hook = global[RELOAD_HOOK];
+        if (typeof hook !== 'function') {
+            // An app without the hook (an older core, not running yet): dev restarts it.
+            reply({ outcome: 'unsupported' });
+            return;
+        }
+        Promise.resolve()
+            .then(() => hook('dev'))
+            .then((result) => reply(answerOf(result)), 
+        // The app logged why (core logs every failed reload); dev restarts it.
+        () => reply({ outcome: 'failed', code: 'CONFIG_RELOAD_FAILED' }));
+    });
     // The channel must not keep a finished process alive.
     process.channel?.unref();
 }

package/dist/dev-host.d.ts

@@ -0,0 +1,13 @@
+/** The answer that asks the CLI for the default development host (`--domain auto`, `--domains auto`). */
+export declare const AUTO_DOMAIN = "auto";
+/** A DNS label (RFC 1035): lower-case letters, digits and inner dashes, at most 63 characters. */
+export declare function hostLabel(value: string): string;
+/** The project's label: from the package.json name, else the folder name, else `dokebi-app`. */
+export declare function projectHostLabel(packageName: unknown, folder: string): string;
+/** `<app>.<project>.localhost`: the development host of one app of one project. */
+export declare function devHost(app: string, project: string): string;
+/**
+ * The label of the project at `root` (D-0102). Before `init` (a recipe planning a new folder)
+ * there is no package.json yet: the folder name is what init writes as the package name.
+ */
+export declare function readProjectHostLabel(root: string): Promise<string>;