@dokebi/cli 0.4.2 → 0.4.27

package/dist/server.js

@@ -30,17 +30,19 @@ import { existsSync, readFileSync, watch } from 'node:fs';
 import { mkdir, open, readdir, readFile, rename, rm, stat, utimes, writeFile, } from 'node:fs/promises';
 import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
-import { basename, dirname, join } from 'node:path';
+import { basename, dirname, join, relative } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 import { appUrls, readAppHosts } from './app-urls.js';
-import { CONFIG_FILE, parseProjectConfig } from './configuration.js';
+import { CONFIG_FILE, configTarget, parseProjectConfig, readProjectSettings, } from './configuration.js';
+import { WatchedState } from './dev-watch.js';
 import { debug, debugEnabled, describeError, isMissing, reportError } from './diagnostics.js';
-import { appEnvironment, readEnvFile } from './env-file.js';
+import { appEnvironment, envFileWarnings, readEnvFile } from './env-file.js';
 import { CliError } from './errors.js';
 import { askLogWriter, CONTROL_HOST } from './log-writer-control.js';
 import { redactNpmOutput } from './npm-client.js';
+import { endLeftovers, holdTermination, killGroup, PROCESS_GROUPS } from './process-group.js';
 import { ProjectInspector } from './project-inspector.js';
 import { logFiles } from './rotating-log.js';
 import { ViteHostProcess, viteHostScript } from './vite-host-process.js';
@@ -63,6 +65,8 @@ const paths = (root) => ({
     pid: join(root, RUN, 'app.pid'),
     log: join(root, RUN, 'app.log'),
     writerLog: join(root, RUN, 'log-writer.log'),
+    /** D-0154: the outcome of the app's last configuration reload (RELOAD_STATUS_ENV). */
+    reloadStatus: join(root, RUN, 'reload.json'),
     lock: join(root, RUN, 'start.lock'),
     entry: join(root, ENTRY),
 });
@@ -434,15 +438,18 @@ function pidState(pid, kill) {
         return 'unknown';
     }
 }
-/** The web address dokebi.yaml configures, for pid files that recorded none. */
+/**
+ * The web address the settings file configures (DOKEBI_CONFIG, else dokebi.yaml: the one the app
+ * reads, M50), for pid files that recorded none.
+ */
 async function configuredUrl(root) {
     let source;
     try {
-        source = await readFile(join(root, CONFIG_FILE), 'utf8');
+        source = (await readProjectSettings(root)).source;
     }
     catch (error) {
         if (!isMissing(error))
-            reportError('CONFIG_READ_FAILED', `Unable to read ${CONFIG_FILE}`, error);
+            reportError('CONFIG_READ_FAILED', 'Unable to read the settings file of the project', error);
         return undefined;
     }
     let web;
@@ -603,7 +610,7 @@ async function withoutProcessInfo(root, record, failure, kill) {
         },
     });
 }
-async function checkProject(root) {
+export async function checkProject(root) {
     const { entry } = paths(root);
     if (!existsSync(entry))
         throw new CliError('ENTRY_MISSING', `${ENTRY} does not exist`);
@@ -664,6 +671,42 @@ async function tail(file, lines, current) {
     }
     return result.length ? `${result.join('\n')}\n` : '';
 }
+/** The line the log writer writes before each start (log-writer.ts). */
+const START_MARK = '--- dokebi start ';
+/**
+ * R1 T4 review: why a start failed, from the app log of this start only (after its last start
+ * mark): the first record with an error, as `<code>: <first line>` and, when the error has
+ * causes, `… <its last Caused by line>`. A START_FAILED said only "exited with code 1", and its
+ * tail began with an earlier start's lines. Undefined when no record says.
+ */
+export function startFailureCause(lines) {
+    const from = lines.findLastIndex((line) => line.startsWith(START_MARK));
+    for (const line of lines.slice(from + 1)) {
+        // Records are JSON lines; a stack line or a plain console line is not one.
+        if (!line.startsWith('{'))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch (error) {
+            debug('A log line that starts like a record is not JSON', { error: describeError(error) });
+            continue;
+        }
+        if (record === null || typeof record !== 'object')
+            continue;
+        const error = typeof record.error === 'string' ? record.error : undefined;
+        if (error === undefined && record.level !== 'error')
+            continue;
+        const text = error ?? String(record.message ?? '');
+        const first = text.split('\n')[0] ?? '';
+        const causes = text.split('\n').filter((each) => each.startsWith('Caused by: '));
+        const deepest = causes.at(-1)?.slice('Caused by: '.length);
+        const code = typeof record.code === 'string' ? `${record.code}: ` : '';
+        return `${code}${first}${deepest ? ` … ${deepest}` : ''}`.slice(0, 600);
+    }
+    return undefined;
+}
 /** Rejects rotation settings outside LOG_LIMITS; bytes below 1 MB are allowed for tests. */
 function logSettings(options) {
     const maxBytes = options.logMaxBytes ?? LOG_LIMITS.maxMb.default * MB;
@@ -689,8 +732,26 @@ check = checkProject) {
     const lock = await StartLock.acquire(files.lock);
     if (!lock)
         throw new CliError('START_IN_PROGRESS', 'Another dokebi start is running for this project');
+    // R4CC-1: a SIGINT, SIGTERM or SIGHUP while the start runs (Ctrl+C, an agent's command time
+    // limit during verify's start step) ends what it started and its lock first, then the command
+    // ends as the signal says. Before, the app and its writer ran on with a stale start lock, and
+    // the next verify refused with ALREADY_RUNNING.
+    const termination = holdTermination();
+    const interrupted = () => {
+        const signal = termination.signal();
+        if (signal)
+            throw new CliError('INTERRUPTED', `dokebi start was interrupted (${signal}); nothing it started is left running`, { details: { signal } });
+    };
+    /** This start wrote the pid file (removed again when it is interrupted). */
+    let wrote = false;
+    /** The start returned: the app is the caller's from here on. */
+    let returned = false;
     const warnings = [];
     let writer;
+    /** The writer's process group while a failure must not leave it (and the app) running. */
+    let leftover;
+    /** The app's own process group (the log writer spawns it detached), once it was spawned. */
+    let appGroup;
     try {
         const current = await statusOf(root, readProcess, signalProcess, true);
         if (current.running)
@@ -698,12 +759,19 @@ check = checkProject) {
                 details: current,
             });
         const entry = await check(root);
+        interrupted();
         // The project's .env under the CLI's environment (D-0073); a malformed file stops here.
         const token = randomBytes(24).toString('base64url');
         const env = appEnvironment(root, 'production', {
             ...options.env,
             [INSTANCE_TOKEN_ENV]: token,
+            // D-0154: the app writes the outcome of each configuration reload here (dokebi reload).
+            [RELOAD_STATUS_ENV]: files.reloadStatus,
         });
+        // R4CC-7: what .env sets that the app does not get (DOKEBI_CONFIG) is said, never dropped
+        // silently.
+        for (const warning of envFileWarnings(root))
+            warnings.push(`${warning.code} (${warning.path}): ${warning.hint}`);
         // Lines this start writes begin here (the web listening line is parsed from them).
         const logOffset = await stat(files.log).then((info) => info.size, (error) => {
             if (!isMissing(error))
@@ -733,13 +801,16 @@ check = checkProject) {
         const writerPid = writer.pid;
         if (writerPid === undefined)
             throw new CliError('START_FAILED', 'The log writer process could not be spawned');
+        leftover = writerPid;
         const state = {};
         writer.on('message', (message) => {
             // The writer sends its control port before it spawns the app (IPC keeps the order).
             if (typeof message?.control === 'number')
                 state.control = message.control;
-            if (typeof message?.spawned === 'number')
+            if (typeof message?.spawned === 'number') {
                 state.pid = message.spawned;
+                appGroup = message.spawned;
+            }
             if (message?.ready)
                 state.ready = true;
             if (message && 'exited' in message)
@@ -757,11 +828,15 @@ check = checkProject) {
         debug('Log writer spawned; waiting for the app', { writer: writerPid, waitMs, maxBytes, keep });
         const failure = async (message) => {
             await rm(files.pid, { force: true });
-            return new CliError('START_FAILED', message, {
+            // This start's lines only (after its mark), and the cause in the message itself.
+            const recent = (await tail(files.log, 200)).split('\n');
+            const mark = recent.findLastIndex((line) => line.startsWith(START_MARK));
+            const cause = startFailureCause(recent);
+            return new CliError('START_FAILED', cause ? `${message}: ${redactNpmOutput(cause)}` : message, {
                 details: {
                     log: files.log,
                     // App output in a result: credentials masked like npm output (logs prints it as is).
-                    tail: redactNpmOutput(await tail(files.log, 30)),
+                    tail: redactNpmOutput(recent.slice(Math.max(mark + 1, recent.length - 31)).join('\n')),
                     logWriterLog: redactNpmOutput((await lastLines(files.writerLog, 30)).join('\n')),
                 },
             });
@@ -771,11 +846,13 @@ check = checkProject) {
             await rm(`${files.pid}.tmp`, { force: true });
             await writeFile(`${files.pid}.tmp`, `${JSON.stringify(record)}\n`, { mode: 0o600 });
             await rename(`${files.pid}.tmp`, files.pid);
+            wrote = true;
         };
         const deadline = performance.now() + waitMs;
         let recorded;
         while (performance.now() < deadline) {
             await delay(50);
+            interrupted();
             if (state.pid !== undefined && recorded === undefined) {
                 recorded = {
                     pid: state.pid,
@@ -791,27 +868,29 @@ check = checkProject) {
                 await save(recorded);
                 debug('App process spawned; waiting for the start line', { pid: state.pid });
             }
-            if (state.exited !== undefined)
+            if (state.exited !== undefined) {
+                // Nothing is left to stop: the writer writes the app's last lines and ends by itself.
+                leftover = undefined;
                 throw await failure(`The application exited with ${state.exited}`);
+            }
             if (state.failed !== undefined)
                 throw await failure(`The application could not be started: ${state.failed}`);
             if (state.ready && recorded !== undefined)
                 break;
         }
-        if (recorded === undefined) {
-            // The writer never started the app: do not leave it (or a late app) behind. The writer
-            // leads its own process group (detached), so the group signal reaches both.
-            process.kill(-writerPid, 'SIGKILL');
+        if (recorded === undefined)
             throw await failure(`The log writer did not start the application within ${waitMs} ms`);
-        }
         const ready = state.ready === true;
         if (!ready)
-            warnings.push(`"${STARTED}" was not logged within ${waitMs} ms; the process is running but may not be ready`);
-        const listen = ready ? await startedUrls(files.log, logOffset) : [];
+            warnings.push(`"${STARTED}" was not logged within ${waitMs} ms; the process is running but may not be ready (a src/main.ts of your own: send process.send?.({ dokebi: 'started' }) after app.start(), as the generated one does, so a logging.level above info still shows the start)`);
+        const listen = ready ? await listeningAfterStart(root, files.log, logOffset, deadline) : [];
         // Where stop and status ask for the instance proof when ps is unavailable (D-0073): the
         // listening address (the proof does not depend on the Host header).
         if (listen.length)
             await save({ ...recorded, urls: listen });
+        const urls = appUrls(listen, await appHostsOrNone(root));
+        interrupted();
+        returned = true;
         return {
             pid: recorded.pid,
             log: files.log,
@@ -819,18 +898,45 @@ check = checkProject) {
             logMaxBytes: maxBytes,
             logFiles: keep,
             ready,
-            urls: appUrls(listen, await appHostsOrNone(root)),
+            urls,
             listen,
             ms: Math.round(performance.now() - began),
             warnings,
         };
     }
+    catch (error) {
+        // A start that fails once the writer runs leaves neither it nor the app behind: the writer
+        // never started the app in time (or a late app), the writer died (the app it spawned would
+        // keep running and hold the port, and verify stops only what start returned), or the pid
+        // file could not be written. The writer leads its own process group (detached) and the app
+        // leads one below it (with what the app started), so both groups are signalled.
+        if (leftover !== undefined) {
+            if (killGroup(leftover, 'SIGKILL'))
+                debug('Killed the log writer group of a failed start', { writer: leftover });
+            if (appGroup !== undefined && killGroup(appGroup, 'SIGKILL'))
+                debug('Killed the app group of a failed start', { pid: appGroup });
+        }
+        // An interrupted start leaves no pid file naming what it ended (a failed one removed it).
+        if (wrote && termination.signal())
+            await rm(files.pid, { force: true });
+        throw error;
+    }
     finally {
         // The writer and the app outlive this command.
         if (writer?.connected)
             writer.disconnect();
         writer?.unref();
         await lock.release();
+        // A signal during these last steps of a start that returned: this command ends with it (just
+        // below), and nobody would stop the app, so it is ended like an interrupted start.
+        if (returned && termination.signal() && leftover !== undefined) {
+            killGroup(leftover, 'SIGKILL');
+            if (appGroup !== undefined)
+                killGroup(appGroup, 'SIGKILL');
+            await rm(files.pid, { force: true });
+        }
+        // A signal that came meanwhile ends this command now, as it would have without the hold.
+        termination.release();
     }
 }
 /**
@@ -885,6 +991,38 @@ export async function appHostsOrNone(root) {
         return { hosted: false, domains: [], answersUnknown: false };
     }
 }
+/**
+ * The listening URLs once the app said it started. The start message comes over IPC, the
+ * listening line through the log, a path with more hops (the logger's worker thread; a cluster's
+ * primary relaying whole lines, M51): the line can reach app.log just after the message. So with
+ * @dokebi/web in the project the log is read again until the line is there or the start's own
+ * deadline passes; a project without web logs no such line and is read once.
+ */
+async function listeningAfterStart(root, log, offset, deadline) {
+    let listen = await startedUrls(log, offset);
+    if (listen.length || !hasWebDependency(root))
+        return listen;
+    while (!listen.length && performance.now() < deadline) {
+        await delay(25);
+        listen = await startedUrls(log, offset);
+    }
+    if (!listen.length)
+        debug('No web listening line in the log before the start deadline', { log });
+    return listen;
+}
+/** Whether package.json depends on @dokebi/web (a malformed one counts as no). */
+function hasWebDependency(root) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+        return manifest.dependencies?.['@dokebi/web'] !== undefined;
+    }
+    catch (error) {
+        debug('package.json not read while waiting for the listening line', {
+            error: describeError(error),
+        });
+        return false;
+    }
+}
 async function startedUrls(log, offset) {
     try {
         const bytes = await readFile(log);
@@ -1115,7 +1253,9 @@ export async function stopStarted(root, started, timeoutMs = 30_000, force = fal
  * it finishes its file, then reads each rotated file newer than it (found by inode, oldest
  * first) before following the new app.log, so several rotations between two polls skip no line.
  */
-export async function logs(root, lines = 100, follow = false, write = (text) => process.stdout.write(text), signal) {
+export async function logs(root, lines = 100, follow = false, 
+// dokebi-check: allow console-output dokebi logs prints the app log lines to the terminal
+write = (text) => process.stdout.write(text), signal) {
     const file = paths(root).log;
     if (!follow) {
         if (!existsSync(file))
@@ -1332,7 +1472,7 @@ export async function foreground(root) {
     }
 }
 /** The installed version of a package, looked up like Node does (node_modules up the tree). */
-function installedVersion(root, name) {
+export function installedVersion(root, name) {
     for (let directory = root;; directory = dirname(directory)) {
         try {
             const { version } = JSON.parse(readFileSync(join(directory, 'node_modules', name, 'package.json'), 'utf8'));
@@ -1358,16 +1498,87 @@ function inertiaDevServer(root) {
 }
 /** Files the Vite dev server owns: a change reaches the browser by HMR, not by a restart. */
 const VIEW_FILE = /(^|[\\/])views[\\/].*\.(js|mjs|ts)$|\.(vue|css|scss|sass|less)$/;
+let devReloadId = 0;
+/**
+ * D-0154: asks the app `dokebi dev` runs to read dokebi.yaml again (through the IPC channel of
+ * its preload, dev-guard.ts). Resolves with its answer, or undefined when it cannot be asked,
+ * exits or does not answer within `timeoutMs`.
+ */
+function askDevReload(app, timeoutMs) {
+    if (!app.connected || app.exitCode !== null || app.signalCode !== null)
+        return Promise.resolve(undefined);
+    const id = ++devReloadId;
+    return new Promise((resolve) => {
+        const finish = (answer) => {
+            clearTimeout(timer);
+            app.off('message', onMessage);
+            app.off('exit', onExit);
+            resolve(answer);
+        };
+        const onMessage = (message) => {
+            const reply = message;
+            if (reply?.dokebi === 'dev-reload-result' &&
+                reply.id === id &&
+                typeof reply.outcome === 'string')
+                finish(reply);
+        };
+        const onExit = () => finish(undefined);
+        const timer = setTimeout(() => finish(undefined), timeoutMs);
+        app.on('message', onMessage);
+        app.once('exit', onExit);
+        try {
+            app.send({ dokebi: 'dev-reload', id }, (error) => {
+                if (error) {
+                    debug('dev: the reload request could not be sent; restarting instead', {
+                        error: describeError(error),
+                    });
+                    finish(undefined);
+                }
+            });
+        }
+        catch (error) {
+            debug('dev: the reload request could not be sent; restarting instead', {
+                error: describeError(error),
+            });
+            finish(undefined);
+        }
+    });
+}
+/** How long dev waits for a reload answer: the app's prepareTimeoutMs (dokebi.yaml) and 5 s. */
+async function devReloadTimeout(root) {
+    try {
+        const options = parseProjectConfig((await readProjectSettings(root)).source).options;
+        const reload = options.reload;
+        const ms = reload?.prepareTimeoutMs;
+        return (typeof ms === 'number' && Number.isSafeInteger(ms) && ms > 0 ? ms : 30_000) + 5000;
+    }
+    catch (error) {
+        // A broken dokebi.yaml: the app answers `invalid` at once; the default bounds the wait.
+        debug('dev: dokebi.yaml not read for the reload timeout', { error: describeError(error) });
+        return 35_000;
+    }
+}
 /**
  * Development loop: runs the app, restarts it (SIGTERM, drain, start) 300 ms after a change in
- * src/, dokebi.yaml or .env. With a Vite config, Inertia views come from the Vite dev server
- * (HMR, D-0045) when template-inertia supports it, otherwise from watch builds that restart the
- * app. With template-inertia 0.4.0 that Vite is one host process beside the app, shared by every
- * cluster worker and kept across app restarts (D-0045 addendum 3); older ones start it inside the app.
+ * src/, dokebi.yaml or .env (a path whose state differs from the recorded one, see dev-watch.ts).
+ * D-0154: a change of dokebi.yaml alone is first offered to the running app: when every changed
+ * option is reloadable it applies them and keeps running; an invalid file keeps the app as it is;
+ * anything else (an option that needs a restart, an app without reloads) restarts it.
+ * With a Vite config, Inertia views come from the Vite dev server (HMR, D-0045) when
+ * template-inertia supports it, otherwise from watch builds that restart the app. With
+ * template-inertia 0.4.0 that Vite is one host process beside the app, shared by every cluster
+ * worker and kept across app restarts (D-0045 addendum 3); older ones start it inside the app.
  * The first Ctrl+C drains everything; a second one kills.
  */
 export async function dev(root, say) {
     const entry = await checkProject(root);
+    // R4CC-7: a DOKEBI_CONFIG line of .env is not passed to the app; dev says so once.
+    for (const warning of envFileWarnings(root))
+        say(`${warning.code} (${warning.path}): ${warning.hint}`);
+    // M50: the settings file the app reads (DOKEBI_CONFIG, else dokebi.yaml) is the one watched
+    // for a reload and named in what dev says.
+    const settings = await configTarget(root);
+    const settingsName = settings.file;
     // The project's .env (D-0073), read again before every (re)start: a change restarts the app
     // with the new values. A malformed file fails here and, later, fails that restart only.
     let fileEnv = readEnvFile(root);
@@ -1386,10 +1597,14 @@ export async function dev(root, say) {
             : `listening on ${configured}; the app answers only the Host names of its domains (none is a loopback name such as localhost)`);
     }
     const guard = new URL('./dev-guard.js', import.meta.url).href;
-    // stdio fd 3 is the IPC channel the guard watches.
-    const child = (args, extra = {}) => spawn(process.execPath, ['--import', guard, ...args], {
+    // stdio fd 3 is the IPC channel the guard watches. `group`: the app leads a process group of
+    // its own (POSIX), so what it started and left running when it exits (a restart, a crash) is
+    // found there and ended instead of holding a port against the next start. Ctrl+C reaches it
+    // through dev (SIGTERM), and the guard still ends it when dev dies.
+    const child = (args, extra = {}, group = false) => spawn(process.execPath, ['--import', guard, ...args], {
         cwd: root,
         stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
+        detached: group && PROCESS_GROUPS,
         // DOKEBI_DEV: a cluster app runs one worker (@dokebi/cluster, DOKEBI_DEV_WORKERS for more).
         env: appEnvironment(root, 'development', { DOKEBI_DEV: '1', ...(hot ? { DOKEBI_VITE_DEV: '1' } : {}), ...extra }, fileEnv),
     });
@@ -1415,24 +1630,52 @@ export async function dev(root, say) {
                 return;
             extra = { DOKEBI_VITE_DEV_URL: address.url, DOKEBI_VITE_DEV_KEY: address.key };
         }
-        app = child([entry], extra);
+        app = child([entry], extra, true);
         const current = app;
         current.once('exit', (code, signal) => {
             if (app === current && !exiting)
                 say(`app exited (${signal ?? code}); waiting for a change to restart`);
+            if (current.pid !== undefined)
+                void leftovers(current.pid);
         });
     };
-    const halt = async (target, limitMs = 15_000) => {
-        if (!target || target.exitCode !== null || target.signalCode !== null)
+    /** Ends what an exited app left in its process group, and says so. */
+    const ended = new Map();
+    const leftovers = (pid) => {
+        let done = ended.get(pid);
+        if (!done) {
+            done = endLeftovers(pid, 2000).then((how) => {
+                if (how !== 'none')
+                    say(`processes the app started were still running after it exited; ended them (${how === 'killed' ? 'SIGKILL' : 'SIGTERM'})`);
+            });
+            ended.set(pid, done);
+        }
+        return done;
+    };
+    /**
+     * R4CC-4: apps dev is stopping (a restart drains the old one while `app` is already unset): a
+     * second Ctrl+C kills them too. Since the app leads its own group it no longer gets the
+     * terminal's Ctrl+C itself, so without this the old app drained on for up to 15 s.
+     */
+    const halting = new Set();
+    const halt = async (target, limitMs = 15_000, group = false) => {
+        if (!target)
             return;
-        const exited = new Promise((resolve) => target.once('exit', resolve));
-        target.kill('SIGTERM');
-        const timer = setTimeout(() => target.kill('SIGKILL'), limitMs);
-        await exited;
-        clearTimeout(timer);
+        if (target.exitCode === null && target.signalCode === null) {
+            const exited = new Promise((resolve) => target.once('exit', resolve));
+            halting.add(target);
+            target.kill('SIGTERM');
+            const timer = setTimeout(() => target.kill('SIGKILL'), limitMs);
+            await exited;
+            clearTimeout(timer);
+            halting.delete(target);
+        }
+        // The next app must not meet a port that a process of this one still holds.
+        if (group && target.pid !== undefined)
+            await leftovers(target.pid);
     };
-    // Vite builds in watch mode beside the app. The app starts after every first build (a build
-    // empties dist/ first, and the SSR bundle is read once at start) and restarts after rebuilds.
+    // Vite builds in watch mode beside the app. The app starts after every first build (the
+    // manifest and the SSR bundle it reads once at start must exist) and restarts after rebuilds.
     const helpers = [];
     const firstBuilds = [];
     let built = () => { };
@@ -1484,23 +1727,52 @@ export async function dev(root, say) {
         throw error;
     }
     let timer;
-    let restarting = run().catch((error) => {
-        // Keep the loop alive: the next change tries again.
-        reportError('DEV_START_FAILED', 'Starting the app failed', error);
-    });
+    // The first start is chained below, once the watched files are recorded.
+    let restarting = Promise.resolve();
+    /** What changed since the last restart or reload: dokebi.yaml alone may be reloaded. */
+    let pending = { config: false, other: undefined };
     const changed = (what) => {
         if (exiting)
             return;
+        if (what === settingsName)
+            pending.config = true;
+        else
+            pending.other ??= what;
         clearTimeout(timer);
         timer = setTimeout(() => {
+            const batch = pending;
+            pending = { config: false, other: undefined };
             restarting = restarting
                 .then(async () => {
                 if (exiting)
                     return;
+                if (batch.config && batch.other === undefined && app) {
+                    const answer = await askDevReload(app, await devReloadTimeout(root));
+                    debug('dev: reload answer', {
+                        outcome: answer?.outcome ?? 'no-answer',
+                        code: answer?.code,
+                    });
+                    if (answer?.outcome === 'applied') {
+                        say(`${settingsName} reloaded without a restart${answer.paths?.length ? `: ${answer.paths.join(', ')}` : ''}`);
+                        return;
+                    }
+                    if (answer?.outcome === 'unchanged')
+                        return;
+                    if (answer?.outcome === 'invalid') {
+                        say(`${settingsName} is invalid; the app keeps its current settings (its log says where); fix it and save again`);
+                        return;
+                    }
+                    // S-c: an app with no reload hook is still starting, or passes no configFile (R12).
+                    if (answer?.outcome === 'unsupported')
+                        say(`${settingsName}: the app did not take it (it is still starting, or src/main.ts passes no configFile to new Application or ClusterRunner: doctor says RELOAD_NOT_WIRED then)`);
+                    if (answer?.outcome === 'restart-required' && answer.restartRequired?.length)
+                        say(`${settingsName}: ${answer.restartRequired.join(', ')} ${answer.restartRequired.length === 1 ? 'needs' : 'need'} a restart`);
+                }
+                const what = batch.other ?? settingsName;
                 say(`${what} changed; restarting`);
                 const previous = app;
                 app = undefined;
-                await halt(previous);
+                await halt(previous, undefined, true);
                 if (!exiting)
                     await run();
             })
@@ -1511,27 +1783,62 @@ export async function dev(root, say) {
         }, 300);
     };
     built = (label) => changed(`${label} build`);
+    // Events restart the app only for paths that really changed since they were recorded (see
+    // dev-watch.ts: macOS also reports writes made before the watch started). An event without a
+    // name cannot be checked and restarts.
+    const source = join(root, 'src');
+    // Styles and components reach the app through Vite (HMR, or the watch builds that restart it).
+    const viewFile = (name) => (hot && VIEW_FILE.test(name)) ||
+        (helpers.length > 0 && /\.(vue|css|scss|sass|less)$/.test(name));
+    const watched = new WatchedState({ skip: (path) => viewFile(relative(source, path)) });
     const watchers = [
-        watch(join(root, 'src'), { recursive: true }, (_event, name) => {
-            // Styles and components reach the app through the Vite builds (restart after the build).
-            if (hot && name && VIEW_FILE.test(name))
+        watch(source, { recursive: true }, (_event, name) => {
+            if (name && viewFile(name))
                 return;
-            if (helpers.length && name && /\.(vue|css|scss|sass|less)$/.test(name))
+            if (name && !watched.changedIn(source, name))
                 return;
             changed(`src/${name ?? ''}`);
         }),
         watch(root, (_event, name) => {
-            if (name === 'dokebi.yaml' || name === '.env')
-                changed(name);
+            if (!name)
+                return;
+            if ((name === CONFIG_FILE && !settings.fromEnvironment) || name === '.env') {
+                if (watched.changed(join(root, name)))
+                    changed(name);
+            }
             // A running Vite reloads its own config; a host that failed to start tries again.
-            else if (viteHost && name && /^vite\.config\.[cm]?[jt]s$/.test(name) && !viteHost.running)
-                changed(name);
+            else if (viteHost && /^vite\.config\.[cm]?[jt]s$/.test(name) && !viteHost.running) {
+                if (watched.changed(join(root, name)))
+                    changed(name);
+            }
         }),
     ];
+    // A settings file DOKEBI_CONFIG names: its own folder is watched for it (any folder, also one
+    // outside the project: dev only reads it).
+    if (settings.fromEnvironment)
+        watchers.push(watch(dirname(settings.path), (_event, name) => {
+            if (name === basename(settings.path) && watched.changed(settings.path))
+                changed(settingsName);
+        }));
+    // After the watchers start and before the app starts: a write after this point is an event
+    // with a new state; a write before it is already what the app reads.
+    watched.recordTree(source);
+    for (const path of [settings.path, join(root, '.env')])
+        watched.record(path);
+    for (const extension of ['ts', 'mts', 'cts', 'js', 'mjs', 'cjs'])
+        watched.record(join(root, `vite.config.${extension}`));
+    restarting = run().catch((error) => {
+        // Keep the loop alive: the next change tries again.
+        reportError('DEV_START_FAILED', 'Starting the app failed', error);
+    });
     return await new Promise((resolve) => {
         const finish = async () => {
             if (exiting) {
-                app?.kill('SIGKILL');
+                for (const target of new Set([...(app ? [app] : []), ...halting])) {
+                    target.kill('SIGKILL');
+                    if (target.pid !== undefined && PROCESS_GROUPS)
+                        killGroup(target.pid, 'SIGKILL');
+                }
                 for (const helper of helpers)
                     helper.kill('SIGKILL');
                 await viteHost?.stop(0, true);
@@ -1544,7 +1851,10 @@ export async function dev(root, say) {
             for (const watcher of watchers)
                 watcher.close();
             await restarting;
-            await Promise.all([halt(app), ...helpers.map((helper) => halt(helper, 5000))]);
+            await Promise.all([
+                halt(app, undefined, true),
+                ...helpers.map((helper) => halt(helper, 5000)),
+            ]);
             // After the app: its requests and server renders go to the host until it has drained.
             await viteHost?.stop();
             resolve(0);
@@ -1553,3 +1863,242 @@ export async function dev(root, say) {
         process.on('SIGTERM', () => void finish());
     });
 }
+/** The variable that tells the app where to write its reload outcomes (core RELOAD_STATUS_ENV). */
+const RELOAD_STATUS_ENV = 'DOKEBI_RELOAD_STATUS';
+/** The app's last reload outcome (RELOAD_STATUS_ENV), or undefined. */
+async function reloadStatusOf(file) {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        // Not written yet (no reload so far), or being replaced: no outcome to read now.
+        if (isMissing(error) || error instanceof SyntaxError)
+            return undefined;
+        throw error;
+    }
+}
+/** The log codes a reload ends with; the app writes one after every SIGHUP (D-0154). */
+const RELOAD_OUTCOMES = new Set([
+    'CONFIG_RELOADED',
+    'CONFIG_RELOAD_UNCHANGED',
+    'CONFIG_RELOAD_INVALID',
+    'CONFIG_RELOAD_RESTART_REQUIRED',
+    'CONFIG_RELOAD_FAILED',
+    'CONFIG_RELOAD_TIMEOUT',
+    'CONFIG_RELOAD_PARTIAL',
+    'CONFIG_RELOAD_UNAVAILABLE',
+]);
+/** Versions of @dokebi/core whose Application reads dokebi.yaml again on SIGHUP. */
+const RELOAD_CORE = [0, 4, 2];
+function newer(version, than) {
+    for (let index = 0; index < 3; index++) {
+        const a = version[index] ?? 0;
+        const b = than[index] ?? 0;
+        if (a !== b)
+            return a > b;
+    }
+    return true;
+}
+/**
+ * Whether the background app reads dokebi.yaml again on SIGHUP: core 0.4.2 or newer and a
+ * src/main.ts that gives its Application (or @dokebi/cluster runner) `configFile`, unchanged since
+ * the app started. Without that a SIGHUP would end the app, so the command refuses.
+ */
+async function reloadSupport(root, record) {
+    const core = installedVersion(root, '@dokebi/core');
+    if (!core || !newer(core, RELOAD_CORE))
+        return `@dokebi/core ${core ? core.join('.') : '(not installed)'} cannot read dokebi.yaml again; it needs 0.4.2 or newer`;
+    const main = paths(root).entry;
+    const [text, info] = await Promise.all([readFile(main, 'utf8'), stat(main)]);
+    if (!/\bconfigFile\s*:/.test(text))
+        return `${ENTRY} gives the app no configFile, so a SIGHUP would end it instead of reloading`;
+    if (info.mtimeMs > Date.parse(record.startedAt) + 1000)
+        return `${ENTRY} changed after the app started; the running app may not read dokebi.yaml again`;
+    return undefined;
+}
+/** The first reload outcome the app logged after `offset` of app.log (a SIGHUP's, `trigger: signal`). */
+async function reloadOutcome(log, offset) {
+    let text;
+    try {
+        const handle = await open(log, 'r');
+        try {
+            const { size } = await handle.stat();
+            // A rotation since the signal starts a new file: read it from the beginning.
+            const from = size < offset ? 0 : offset;
+            const length = Math.min(size - from, 4 * MB);
+            const buffer = Buffer.alloc(Math.max(0, length));
+            if (length > 0)
+                await handle.read(buffer, 0, length, from);
+            text = buffer.toString('utf8');
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+    for (const line of text.split('\n')) {
+        if (!line.includes('CONFIG_RELOAD'))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            // dokebi-check: allow empty-catch a log line that is not JSON (a readable line, a cut line) is not the outcome
+            continue;
+        }
+        if (typeof record.code === 'string' &&
+            RELOAD_OUTCOMES.has(record.code) &&
+            record.trigger === 'signal')
+            return record;
+    }
+    return undefined;
+}
+/**
+ * `dokebi reload` (D-0154): asks the background app to read dokebi.yaml again (SIGHUP to the pid
+ * `start` recorded, proven like `stop`; through its log writer when this shell may not signal
+ * it), then reads its outcome from .dokebi/run/app.log. Options marked reloadable apply without
+ * a restart; an option that needs one (`RELOAD_RESTART_REQUIRED`), an invalid file
+ * (`RELOAD_INVALID`) or a plugin that could not prepare (`RELOAD_FAILED`) change nothing.
+ */
+export async function reload(root, timeoutMs, read = readProcess, kill = signalProcess) {
+    daemonOnly();
+    const record = await readRecord(root);
+    if (!record)
+        return { running: false };
+    let proof = 'process';
+    let found;
+    try {
+        found = Boolean(await live(record, read));
+    }
+    catch (error) {
+        if (!processInfoFailure(error))
+            throw error;
+        const how = await withoutProcessInfo(root, record, error, kill);
+        found = how !== 'gone';
+        if (how !== 'gone')
+            proof = how;
+    }
+    if (!found)
+        return { running: false, pid: record.pid };
+    const unsupported = await reloadSupport(root, record);
+    if (unsupported)
+        throw new CliError('RELOAD_UNSUPPORTED', unsupported, {
+            details: {
+                pid: record.pid,
+                fix: `give the Application configFile in ${ENTRY} (new Application({ config: document.options, configFile: configPath, … }); the generated ${ENTRY} does since @dokebi/cli 0.4.26), then restart: npx dokebi stop && npx dokebi start`,
+            },
+        });
+    const wait = timeoutMs ?? (await devReloadTimeout(root));
+    const { log, reloadStatus } = paths(root);
+    // The outcome file of the app (whatever its log level) is preferred; the log is the fallback.
+    const before = await reloadStatusOf(reloadStatus);
+    const offset = await stat(log).then((info) => info.size, (error) => {
+        if (isMissing(error))
+            return 0;
+        throw error;
+    });
+    const began = performance.now();
+    let via = 'signal';
+    const throughWriter = async (refused) => {
+        const asked = await askWriter(record, { op: 'reload' });
+        if (!asked.reached)
+            throw new CliError('RELOAD_FAILED', `Unable to signal pid ${record.pid}: this shell may not signal it and its log writer could not be asked (${asked.reason})`, {
+                cause: refused,
+                details: {
+                    pid: record.pid,
+                    fix: 'run npx dokebi reload from a shell that may signal the app (outside the sandbox), or save dokebi.yaml (the app watches it unless options.reload.watch is false)',
+                },
+            });
+        await asked.closed(0);
+        via = 'log-writer';
+    };
+    debug('Sending SIGHUP to reload the configuration', { pid: record.pid, proof });
+    if (proof === 'log-writer')
+        await throughWriter();
+    else
+        try {
+            kill(record.pid, 'SIGHUP');
+        }
+        catch (error) {
+            if (error.code !== 'EPERM')
+                throw error;
+            debug('SIGHUP refused; asking the log writer', { pid: record.pid });
+            await throughWriter(error);
+        }
+    const until = performance.now() + wait;
+    let outcome;
+    while (performance.now() < until) {
+        const status = await reloadStatusOf(reloadStatus);
+        if (status &&
+            (status.pid !== before?.pid || status.sequence !== before?.sequence) &&
+            typeof status.code === 'string') {
+            outcome = status;
+            break;
+        }
+        outcome = await reloadOutcome(log, offset);
+        if (outcome)
+            break;
+        await delay(100);
+    }
+    const ms = Math.round(performance.now() - began);
+    const list = (value) => Array.isArray(value) ? value.slice(0, 64).map((item) => String(item)) : undefined;
+    if (!outcome)
+        return {
+            running: true,
+            pid: record.pid,
+            outcome: 'unknown',
+            ms,
+            proof,
+            via,
+            warnings: [
+                `no reload outcome in ${log} within ${wait} ms: the app may log above info (options.logging.level), or be busy; npx dokebi logs shows what it said`,
+            ],
+        };
+    const code = String(outcome.code);
+    const paths_ = list(outcome.paths);
+    if (code === 'CONFIG_RELOADED' || code === 'CONFIG_RELOAD_UNCHANGED')
+        return {
+            running: true,
+            pid: record.pid,
+            outcome: code === 'CONFIG_RELOADED' ? 'applied' : 'unchanged',
+            code,
+            ...(typeof outcome.revision === 'number' ? { revision: outcome.revision } : {}),
+            ...(paths_ ? { paths: paths_ } : {}),
+            ms,
+            proof,
+            via,
+        };
+    const details = {
+        pid: record.pid,
+        code,
+        ...(paths_ ? { paths: paths_ } : {}),
+        ...(list(outcome.restartRequired) ? { restartRequired: list(outcome.restartRequired) } : {}),
+        ...(list(outcome.issues) ? { issues: list(outcome.issues) } : {}),
+        ...(typeof outcome.line === 'number' ? { line: outcome.line, column: outcome.column } : {}),
+        ...(typeof outcome.plugin === 'string' ? { plugin: outcome.plugin } : {}),
+        ...(typeof outcome.reason === 'string' ? { reason: outcome.reason } : {}),
+        ...(typeof outcome.fix === 'string' ? { fix: outcome.fix } : {}),
+    };
+    if (code === 'CONFIG_RELOAD_RESTART_REQUIRED')
+        throw new CliError('RELOAD_RESTART_REQUIRED', `The change needs a restart (${(list(outcome.restartRequired) ?? []).join(', ')}); nothing was applied`, {
+            details: {
+                ...details,
+                fix: 'restart the app to apply these options: npx dokebi stop && npx dokebi start',
+            },
+        });
+    if (code === 'CONFIG_RELOAD_INVALID')
+        throw new CliError('RELOAD_INVALID', 'dokebi.yaml is invalid; the app keeps its current settings', {
+            details: {
+                ...details,
+                fix: 'correct the named paths or line of dokebi.yaml (npx dokebi doctor checks it), then run npx dokebi reload again',
+            },
+        });
+    throw new CliError('RELOAD_FAILED', `The app did not reload (${code}); nothing was applied`, {
+        details,
+    });
+}