@dokebi/cli 0.2.2 → 0.2.4

package/dist/server.js

@@ -0,0 +1,857 @@
+// Server commands (D-0044): dev, start, stop, status and logs for the project's one process
+// (`src/main.ts`). The background process is tracked by `.dokebi/run/app.pid`. Its stdout and
+// stderr are pipes into a detached log writer (`log-writer.ts`, D-0053) that writes
+// `.dokebi/run/app.log` and rotates it by size (`app.log.1` … `app.log.<files>`). A pid is only
+// acted on when `ps` (/proc on Linux) shows it runs this project's entry and started when the pid
+// file says, so a reused pid is never signalled.
+import { execFile, spawn } from 'node:child_process';
+import { existsSync, readFileSync, watch } from 'node:fs';
+import { mkdir, open, readdir, readFile, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { debug, debugEnabled, isMissing, reportError } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { ProjectInspector } from './project-inspector.js';
+import { logFiles } from './rotating-log.js';
+const exec = promisify(execFile);
+const ENTRY = 'src/main.ts';
+const RUN = '.dokebi/run';
+/** Written by the generated `src/main.ts` once `app.start()` resolved. */
+const STARTED = 'Dokebi application started';
+/** Rotation defaults and limits (D-0053): `--log-max-mb`, `--log-files`. */
+export const LOG_LIMITS = {
+    maxMb: { default: 50, min: 1, max: 10_240 },
+    files: { default: 5, min: 1, max: 100 },
+};
+const MB = 1024 * 1024;
+const paths = (root) => ({
+    run: join(root, RUN),
+    pid: join(root, RUN, 'app.pid'),
+    log: join(root, RUN, 'app.log'),
+    writerLog: join(root, RUN, 'log-writer.log'),
+    lock: join(root, RUN, 'start.lock'),
+    entry: join(root, ENTRY),
+});
+function daemonOnly() {
+    if (process.platform === 'win32')
+        throw new CliError('UNSUPPORTED_PLATFORM', 'Background start and stop need POSIX signals; on Windows use dokebi dev or dokebi start --foreground');
+}
+async function readRecord(root) {
+    let text;
+    try {
+        text = await readFile(paths(root).pid, 'utf8');
+    }
+    catch (error) {
+        // No pid file means not started; anything else is reported and treated the same way.
+        if (!isMissing(error))
+            reportError('PID_FILE_READ_FAILED', 'Unable to read the pid file', error);
+        return undefined;
+    }
+    try {
+        const value = JSON.parse(text);
+        if (Number.isSafeInteger(value.pid) && value.pid > 0 && typeof value.entry === 'string')
+            return value;
+        debug('Pid file ignored: unexpected content', { file: `${RUN}/app.pid` });
+    }
+    catch (error) {
+        reportError('PID_FILE_INVALID', 'Pid file is not valid JSON; treating the app as stopped', error);
+    }
+    return undefined;
+}
+/**
+ * Linux reads /proc: slim container images (node:*-slim) have no `ps`. Start time is the boot
+ * time plus the process start in clock ticks (USER_HZ, 100 on Linux).
+ */
+async function procInfo(pid) {
+    try {
+        const [cmdline, stat, status, uptime] = await Promise.all([
+            readFile(`/proc/${pid}/cmdline`, 'utf8'),
+            readFile(`/proc/${pid}/stat`, 'utf8'),
+            readFile(`/proc/${pid}/status`, 'utf8'),
+            readFile('/proc/stat', 'utf8'),
+        ]);
+        // Fields after the parenthesised command name: state is field 3, starttime field 22.
+        const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+        const ticks = Number(fields[19]);
+        const boot = Number(/^btime (\d+)$/m.exec(uptime)?.[1]);
+        if (!Number.isFinite(ticks) || !Number.isFinite(boot))
+            return undefined;
+        return {
+            startedAt: (boot + ticks / 100) * 1000,
+            rssKb: Number(/^VmRSS:\s+(\d+)/m.exec(status)?.[1] ?? 0),
+            command: cmdline.split('\0').join(' ').trim(),
+        };
+    }
+    catch (error) {
+        // ENOENT: no such process. Anything else (permissions, a changed /proc) is reported.
+        if (!isMissing(error))
+            reportError('PROCESS_INFO_FAILED', 'Unable to read process information from /proc', error);
+        return undefined;
+    }
+}
+async function processInfo(pid) {
+    if (process.platform === 'linux')
+        return procInfo(pid);
+    try {
+        const { stdout } = await exec('ps', ['-ww', '-o', 'lstart=,rss=,command=', '-p', String(pid)], {
+            env: { ...process.env, LC_ALL: 'C' },
+        });
+        // lstart is a fixed 24-character date: "Thu Oct 15 00:21:26 2026".
+        const line = stdout.trim();
+        const startedAt = Date.parse(line.slice(0, 24));
+        const [rss = '', ...command] = line.slice(24).trim().split(/\s+/);
+        if (!Number.isFinite(startedAt))
+            return undefined;
+        return { startedAt, rssKb: Number(rss), command: command.join(' ') };
+    }
+    catch (error) {
+        // ps exits 1 when the pid does not exist; anything else (no ps, killed) is reported.
+        if (error.code !== 1)
+            reportError('PROCESS_INFO_FAILED', 'Unable to read process information with ps', error);
+        return undefined;
+    }
+}
+/** The recorded process, when it is still alive and still this project's process. */
+async function live(record) {
+    const info = await processInfo(record.pid);
+    if (!info?.command.includes(record.entry)) {
+        if (info)
+            debug('Recorded pid runs another command; treating it as stale', { pid: record.pid });
+        return undefined;
+    }
+    // lstart has one-second resolution; the pid file is written right after spawn.
+    if (Math.abs(info.startedAt - Date.parse(record.startedAt)) > 5000) {
+        debug('Recorded pid was reused by a later process; treating it as stale', { pid: record.pid });
+        return undefined;
+    }
+    return info;
+}
+/** Whether the record's log writer still runs (its command names the writer and the entry). */
+async function writerAlive(record) {
+    if (record.logWriter === undefined)
+        return false;
+    const info = await processInfo(record.logWriter);
+    return Boolean(info?.command.includes('log-writer') && info.command.includes(record.entry));
+}
+async function logInfo(root) {
+    const { log, writerLog } = paths(root);
+    const sizes = async (file) => stat(file).then((stats) => stats.size, (error) => {
+        // Rotated away between listing and stat: it is simply no longer there.
+        if (!isMissing(error))
+            reportError('LOG_READ_FAILED', 'Unable to read a log file size', error);
+        return undefined;
+    });
+    const files = [];
+    for (const file of logFiles(log)) {
+        const bytes = await sizes(file);
+        if (bytes !== undefined)
+            files.push({ file, bytes });
+    }
+    const writerBytes = await sizes(writerLog);
+    return { logFiles: files, ...(writerBytes ? { logWriterLog: writerLog } : {}) };
+}
+export async function status(root) {
+    const { pid, log } = paths(root);
+    const record = await readRecord(root);
+    const logs = await logInfo(root);
+    if (!record)
+        return { running: false, log, ...logs };
+    const info = await live(record);
+    if (!info) {
+        await rm(pid, { force: true });
+        return {
+            running: false,
+            stale: true,
+            pid: record.pid,
+            startedAt: record.startedAt,
+            log,
+            ...logs,
+        };
+    }
+    return {
+        running: true,
+        pid: record.pid,
+        startedAt: record.startedAt,
+        uptimeSec: Math.round((Date.now() - Date.parse(record.startedAt)) / 1000),
+        rssMb: Math.round(info.rssKb / 1024),
+        log,
+        ...logs,
+        ...(record.logWriter !== undefined
+            ? { logWriter: { pid: record.logWriter, running: await writerAlive(record) } }
+            : {}),
+    };
+}
+async function checkProject(root) {
+    const { entry } = paths(root);
+    if (!existsSync(entry))
+        throw new CliError('ENTRY_MISSING', `${ENTRY} does not exist`);
+    const inspection = await new ProjectInspector().inspect(root);
+    if (!inspection.healthy)
+        throw new CliError('START_CHECK_FAILED', 'The project has errors; run dokebi doctor', {
+            details: {
+                diagnostics: inspection.diagnostics.filter((item) => item.severity === 'error'),
+            },
+        });
+    return entry;
+}
+const environment = (mode) => ({
+    ...process.env,
+    NODE_ENV: process.env.NODE_ENV ?? mode,
+});
+/**
+ * The last `lines` lines of one file (reading at most its last `maxBytes`). An open handle is
+ * read up to `end` (the size it had when opened) and left open.
+ */
+async function lastLines(source, lines, maxBytes = MB) {
+    if (lines <= 0)
+        return [];
+    let handle;
+    try {
+        const opened = typeof source === 'string' ? await open(source, 'r') : source.handle;
+        if (typeof source === 'string')
+            handle = opened;
+        const size = typeof source === 'string' ? (await opened.stat()).size : source.end;
+        const length = Math.min(size, maxBytes);
+        const buffer = Buffer.alloc(length);
+        await opened.read(buffer, 0, length, size - length);
+        const text = buffer.toString('utf8').split('\n');
+        if (text.at(-1) === '')
+            text.pop();
+        return text.slice(-lines);
+    }
+    catch (error) {
+        // Rotated away while reading: the next older file has those lines.
+        if (!isMissing(error))
+            reportError('LOG_READ_FAILED', 'Unable to read the app log', error);
+        return [];
+    }
+    finally {
+        await handle?.close();
+    }
+}
+/**
+ * The last `lines` lines across app.log and its rotated files (D-0053). With `current` (app.log
+ * opened by the follower), app.log is read through it up to where following starts.
+ */
+async function tail(file, lines, current) {
+    let result = [];
+    const files = logFiles(file);
+    if (current && files[0] !== file)
+        files.unshift(file);
+    for (const each of files) {
+        const source = current && each === file ? current : each;
+        result = [...(await lastLines(source, lines - result.length)), ...result];
+        if (result.length >= lines)
+            break;
+    }
+    return result.length ? `${result.join('\n')}\n` : '';
+}
+/** 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;
+    const files = options.logFiles ?? LOG_LIMITS.files.default;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1024 || maxBytes > LOG_LIMITS.maxMb.max * MB)
+        throw new CliError('USAGE', `--log-max-mb must be an integer from ${LOG_LIMITS.maxMb.min} to ${LOG_LIMITS.maxMb.max}`);
+    if (!Number.isSafeInteger(files) || files < LOG_LIMITS.files.min || files > LOG_LIMITS.files.max)
+        throw new CliError('USAGE', `--log-files must be an integer from ${LOG_LIMITS.files.min} to ${LOG_LIMITS.files.max}`);
+    return { maxBytes, files };
+}
+export async function start(root, options = {}, 
+/** Tests replace the project inspection; the CLI always inspects. */
+check = checkProject) {
+    daemonOnly();
+    const { maxBytes, files: keep } = logSettings(options);
+    const waitMs = options.waitMs ?? 10_000;
+    const files = paths(root);
+    const began = performance.now();
+    const current = await status(root);
+    if (current.running)
+        throw new CliError('ALREADY_RUNNING', `Already running (pid ${current.pid})`, {
+            details: current,
+        });
+    const entry = await check(root);
+    await mkdir(files.run, { recursive: true });
+    await writeFile(join(files.run, '.gitignore'), '*\n');
+    // One start at a time; a lock left by a start that died more than a minute ago is stale.
+    try {
+        await writeFile(files.lock, String(process.pid), { flag: 'wx' });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const age = Date.now() -
+            (await stat(files.lock).catch((cause) => {
+                // The other start removed its lock meanwhile: the lock counts as stale.
+                if (!isMissing(cause))
+                    throw cause;
+                return { mtimeMs: 0 };
+            })).mtimeMs;
+        if (age < 60_000)
+            throw new CliError('START_IN_PROGRESS', 'Another dokebi start is running for this project');
+        debug('Replacing a stale start lock', { ageMs: age });
+        await writeFile(files.lock, String(process.pid));
+    }
+    const warnings = [];
+    let writer;
+    try {
+        // The writer's own diagnostics (it has no app logger) go to log-writer.log.
+        const writerLog = await open(files.writerLog, 'a');
+        try {
+            writer = spawn(process.execPath, [
+                fileURLToPath(new URL('./log-writer.js', import.meta.url)),
+                files.log,
+                String(maxBytes),
+                String(keep),
+                entry,
+            ], {
+                cwd: root,
+                detached: true,
+                stdio: ['ignore', 'ignore', writerLog.fd, 'ipc'],
+                env: environment('production'),
+            });
+        }
+        finally {
+            await writerLog.close();
+        }
+        const writerPid = writer.pid;
+        if (writerPid === undefined)
+            throw new CliError('START_FAILED', 'The log writer process could not be spawned');
+        const state = {};
+        writer.on('message', (message) => {
+            if (typeof message?.spawned === 'number')
+                state.pid = message.spawned;
+            if (message?.ready)
+                state.ready = true;
+            if (message && 'exited' in message)
+                state.exited = message.signal ? `signal ${message.signal}` : `code ${message.exited}`;
+            if (typeof message?.failed === 'string')
+                state.failed = message.failed;
+        });
+        writer.once('exit', (code, signal) => {
+            // The writer ends with 0 only after the app ended (its message may still be on the way).
+            if (code === 0)
+                state.exited ??= 'an unknown code (see the log)';
+            else
+                state.failed ??= `the log writer exited (${signal ?? code})`;
+        });
+        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, {
+                details: {
+                    log: files.log,
+                    tail: await tail(files.log, 30),
+                    logWriterLog: (await lastLines(files.writerLog, 30)).join('\n'),
+                },
+            });
+        };
+        const deadline = performance.now() + waitMs;
+        let recorded;
+        while (performance.now() < deadline) {
+            await delay(50);
+            if (state.pid !== undefined && recorded === undefined) {
+                recorded = state.pid;
+                const record = {
+                    pid: state.pid,
+                    startedAt: new Date().toISOString(),
+                    entry,
+                    node: process.version,
+                    logWriter: writerPid,
+                    logMaxBytes: maxBytes,
+                    logFiles: keep,
+                };
+                await writeFile(`${files.pid}.tmp`, `${JSON.stringify(record)}\n`);
+                await rename(`${files.pid}.tmp`, files.pid);
+                debug('App process spawned; waiting for the start line', { pid: state.pid });
+            }
+            if (state.exited !== 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');
+            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`);
+        return {
+            pid: recorded,
+            log: files.log,
+            logWriter: writerPid,
+            logMaxBytes: maxBytes,
+            logFiles: keep,
+            ready,
+            ms: Math.round(performance.now() - began),
+            warnings,
+        };
+    }
+    finally {
+        // The writer and the app outlive this command.
+        if (writer?.connected)
+            writer.disconnect();
+        writer?.unref();
+        await rm(files.lock, { force: true });
+    }
+}
+export async function stop(root, timeoutMs = 30_000, force = false) {
+    daemonOnly();
+    const files = paths(root);
+    const record = await readRecord(root);
+    if (!record)
+        return { stopped: false };
+    if (!(await live(record))) {
+        await rm(files.pid, { force: true });
+        return { stopped: false, pid: record.pid, stale: true };
+    }
+    const began = performance.now();
+    const gone = async (alive, limit) => {
+        const until = performance.now() + limit;
+        while (performance.now() < until) {
+            if (!(await alive()))
+                return true;
+            await delay(100);
+        }
+        return false;
+    };
+    const app = async () => Boolean(await live(record));
+    // SIGTERM goes to the app (core drain); the log writer exits once the app's output ends.
+    debug('Sending SIGTERM', { pid: record.pid, timeoutMs });
+    process.kill(record.pid, 'SIGTERM');
+    let forced = false;
+    if (!(await gone(app, timeoutMs))) {
+        if (!force)
+            throw new CliError('STOP_TIMEOUT', `pid ${record.pid} did not stop within ${timeoutMs} ms; it is still draining or stuck (use --force)`);
+        debug('Stop timed out; sending SIGKILL', { pid: record.pid });
+        process.kill(record.pid, 'SIGKILL');
+        forced = true;
+        if (!(await gone(app, 5000)))
+            throw new CliError('STOP_TIMEOUT', `pid ${record.pid} survived SIGKILL`);
+    }
+    await rm(files.pid, { force: true });
+    const warnings = [];
+    if (record.logWriter !== undefined && !(await gone(() => writerAlive(record), 5000))) {
+        debug('Log writer still running after the app stopped', { writer: record.logWriter });
+        warnings.push(`the log writer (pid ${record.logWriter}) was still running 5 s after the app stopped; a process the app started may hold its output`);
+    }
+    return {
+        stopped: true,
+        pid: record.pid,
+        ms: Math.round(performance.now() - began),
+        forced,
+        ...(warnings.length ? { warnings } : {}),
+    };
+}
+/**
+ * Prints the last `lines` lines (across app.log and its rotated files); with `follow`, keeps
+ * printing what is appended until SIGINT (or `signal`), following app.log across rotations.
+ * The follower remembers the inode of the file it reads. When app.log has become another file,
+ * 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) {
+    const file = paths(root).log;
+    if (!follow) {
+        if (!existsSync(file))
+            throw new CliError('NO_LOG', `${RUN}/app.log does not exist; the app was never started`);
+        write(await tail(file, lines));
+        return;
+    }
+    const stopped = new AbortController();
+    const onInt = () => stopped.abort();
+    process.once('SIGINT', onInt);
+    signal?.addEventListener('abort', onInt, { once: true });
+    const follower = new LogFollower(file, write, stopped.signal);
+    try {
+        // app.log is opened first and the tail ends where following starts: no line falls between.
+        write(await tail(file, lines, await follower.open()));
+        await follower.run();
+    }
+    finally {
+        process.off('SIGINT', onInt);
+        await follower.close();
+    }
+}
+/** `logs -f` (D-0053): reads app.log as it grows and follows it across rotations by inode. */
+class LogFollower {
+    file;
+    write;
+    signal;
+    #handle;
+    /** The inode of the file being read. */
+    #reading;
+    #position = 0;
+    constructor(file, write, signal) {
+        this.file = file;
+        this.write = write;
+        this.signal = signal;
+    }
+    /** Opens app.log at its end; the handle and that end, when it exists. */
+    async open() {
+        const opened = await this.#open(this.file);
+        await this.#use(opened, 'end');
+        return opened && { handle: opened.handle, end: opened.size };
+    }
+    async close() {
+        const handle = this.#handle;
+        this.#handle = undefined;
+        await handle?.close();
+    }
+    /** Prints what is appended until the signal aborts. */
+    async run() {
+        while (!this.signal.aborted) {
+            await delay(250);
+            if (!this.#handle) {
+                // Before the first start: follow app.log from its beginning once it exists.
+                await this.#use(await this.#open(this.file), 'start');
+                await this.#drain();
+                continue;
+            }
+            // Rotated once or more: finish this file (it is complete), then each newer one in turn.
+            let current = await this.#inode(this.file);
+            while (current !== undefined && current !== this.#reading && !this.signal.aborted) {
+                await this.#drain();
+                if (!(await this.#advance()))
+                    break; // a rotation is under way: next poll
+                current = await this.#inode(this.file);
+            }
+            await this.#drain();
+        }
+    }
+    /** Prints what the open file has beyond the position; the handle reads a renamed file too. */
+    async #drain() {
+        const handle = this.#handle;
+        if (!handle)
+            return;
+        const { size } = await handle.stat();
+        if (size < this.#position)
+            this.#position = 0; // truncated: read it again from the start
+        while (this.#position < size) {
+            const buffer = Buffer.alloc(Math.min(size - this.#position, MB));
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, this.#position);
+            if (!bytesRead)
+                break;
+            this.write(buffer.subarray(0, bytesRead).toString('utf8'));
+            this.#position += bytesRead;
+        }
+    }
+    /**
+     * Moves to the file written after the one being read; false when it cannot be told yet.
+     * The writer renames the oldest first (`.k` → `.k+1` before `.k-1` → `.k`), so `.k-1`
+     * opened while `.k` holds our inode both before and after the open is the next file;
+     * otherwise a rotation ran meanwhile and the place is looked up again. A gap that stays
+     * (a rotated file removed by hand) is stepped over to the next newer file there is.
+     */
+    async #advance() {
+        const attempts = 20;
+        for (let attempt = 0; attempt < attempts && !this.signal.aborted; attempt++) {
+            if (attempt)
+                await delay(5);
+            const rotated = await this.#rotated();
+            const index = await this.#indexOf(rotated, this.#reading);
+            if (index === undefined) {
+                if (await this.#removed())
+                    return this.#skipToOldest(rotated);
+                continue; // moved up while we looked: look again
+            }
+            // A gap at `.k-1` lasts microseconds during a rotation; one seen for ~100 ms is a hole.
+            const target = attempt < attempts - 1 ? index - 1 : (rotated.filter((each) => each < index).at(-1) ?? 0);
+            const next = await this.#open(this.#named(target));
+            if (!next)
+                continue; // `.k-1` is between its rename and the next one
+            if ((await this.#inode(this.#named(index))) === this.#reading) {
+                if (debugEnabled())
+                    debug('App log rotated; following the next file', { file: this.#named(target) });
+                await this.#use(next, 'start');
+                return true;
+            }
+            await next.handle.close();
+        }
+        return false;
+    }
+    /** The followed file was removed beyond --log-files: lines between are gone from disk too. */
+    async #skipToOldest(rotated) {
+        const oldest = rotated.at(-1) ?? 0;
+        const opened = await this.#open(this.#named(oldest));
+        if (!opened)
+            return false;
+        debug('Followed log file was removed by rotation; continuing with the oldest kept file', {
+            file: this.#named(oldest),
+        });
+        this.write('--- dokebi: logs -f fell behind; rotated lines removed before they were read ---\n');
+        await this.#use(opened, 'start');
+        return true;
+    }
+    /** The index of the rotated file with `inode` (`app.log.<index>`), when one has it. */
+    async #indexOf(rotated, inode) {
+        for (const index of rotated)
+            if ((await this.#inode(this.#named(index))) === inode)
+                return index;
+        return undefined;
+    }
+    /** Indexes of the rotated files there are, ascending (newest first). */
+    async #rotated() {
+        const name = basename(this.file);
+        const names = await readdir(dirname(this.file)).catch((error) => {
+            if (!isMissing(error))
+                reportError('LOG_READ_FAILED', 'Unable to list the rotated app logs', error, 5000);
+            return [];
+        });
+        return names
+            .filter((each) => each.startsWith(`${name}.`) && /^\d+$/.test(each.slice(name.length + 1)))
+            .map((each) => Number(each.slice(name.length + 1)))
+            .sort((a, b) => a - b);
+    }
+    /** True when the open file has no name left (removed beyond --log-files). */
+    async #removed() {
+        return (await this.#handle?.stat())?.nlink === 0;
+    }
+    /** `app.log.<index>` (`app.log` for 0). */
+    #named(index) {
+        return index ? `${this.file}.${index}` : this.file;
+    }
+    /** The inode at `name`, or undefined while it does not exist. */
+    async #inode(name) {
+        return stat(name).then((stats) => stats.ino, (error) => {
+            // Between the rename and the new file (rotation) or before the first start: absent.
+            if (!isMissing(error))
+                reportError('LOG_READ_FAILED', 'Unable to read the app log', error, 5000);
+            return undefined;
+        });
+    }
+    async #open(name) {
+        let handle;
+        try {
+            handle = await open(name, 'r');
+            const { ino, size } = await handle.stat();
+            return { handle, ino, size };
+        }
+        catch (error) {
+            await handle?.close();
+            if (!isMissing(error))
+                reportError('LOG_READ_FAILED', 'Unable to open the app log', error, 5000);
+            return undefined;
+        }
+    }
+    /** Reads `opened` from its start or end from now on, closing the file read so far. */
+    async #use(opened, from) {
+        if (!opened)
+            return;
+        await this.#handle?.close();
+        this.#handle = opened.handle;
+        this.#reading = opened.ino;
+        this.#position = from === 'end' ? opened.size : 0;
+    }
+}
+/** Runs the app in the foreground and forwards SIGINT/SIGTERM; resolves with its exit code. */
+export async function foreground(root) {
+    const entry = await checkProject(root);
+    const child = spawn(process.execPath, [entry], {
+        cwd: root,
+        stdio: 'inherit',
+        env: environment('production'),
+    });
+    const forward = (signal) => () => child.kill(signal);
+    const onInt = forward('SIGINT');
+    const onTerm = forward('SIGTERM');
+    process.on('SIGINT', onInt);
+    process.on('SIGTERM', onTerm);
+    try {
+        return await new Promise((resolve) => child.once('exit', (code, signal) => resolve(code ?? (signal ? 128 : 1))));
+    }
+    finally {
+        process.off('SIGINT', onInt);
+        process.off('SIGTERM', onTerm);
+    }
+}
+/** The installed version of a package, looked up like Node does (node_modules up the tree). */
+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'));
+            const parts = /^(\d+)\.(\d+)\.(\d+)/.exec(String(version));
+            return parts ? [Number(parts[1]), Number(parts[2]), Number(parts[3])] : undefined;
+        }
+        catch (error) {
+            // Not installed here: keep walking up like Node's resolution does.
+            if (!isMissing(error))
+                reportError('PACKAGE_READ_FAILED', `Unable to read the installed ${name} package.json`, error);
+        }
+        if (dirname(directory) === directory)
+            return undefined;
+    }
+}
+/** template-inertia 0.1.2 serves views from the Vite dev server with HMR (D-0045). */
+function inertiaDevServer(root) {
+    const version = installedVersion(root, '@dokebi/template-inertia');
+    if (!version)
+        return false;
+    const [major, minor, patch] = version;
+    return major > 0 || minor > 1 || (minor === 1 && patch >= 2);
+}
+/** 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)$/;
+/**
+ * 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
+ * inside the app (HMR, D-0045) when template-inertia supports it, otherwise from watch builds
+ * that restart the app. The first Ctrl+C drains everything; a second one kills.
+ */
+export async function dev(root, say) {
+    const entry = await checkProject(root);
+    let app;
+    let exiting = false;
+    const hasVite = ['vite.config.ts', 'vite.config.mjs', 'vite.config.js'].some((name) => existsSync(join(root, name)));
+    const hot = hasVite && inertiaDevServer(root);
+    if (hot)
+        say('Inertia views: Vite dev server with hot module replacement');
+    const guard = new URL('./dev-guard.js', import.meta.url).href;
+    // stdio fd 3 is the IPC channel the guard watches.
+    const child = (args) => spawn(process.execPath, ['--import', guard, ...args], {
+        cwd: root,
+        stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
+        // DOKEBI_DEV: a cluster app runs one worker (@dokebi/cluster, DOKEBI_DEV_WORKERS for more).
+        env: {
+            ...environment('development'),
+            DOKEBI_DEV: '1',
+            ...(hot ? { DOKEBI_VITE_DEV: '1' } : {}),
+        },
+    });
+    const run = () => {
+        app = child([entry]);
+        const current = app;
+        current.once('exit', (code, signal) => {
+            if (app === current && !exiting)
+                say(`app exited (${signal ?? code}); waiting for a change to restart`);
+        });
+    };
+    const halt = async (target, limitMs = 15_000) => {
+        if (!target || target.exitCode !== null || target.signalCode !== null)
+            return;
+        const exited = new Promise((resolve) => target.once('exit', resolve));
+        target.kill('SIGTERM');
+        const timer = setTimeout(() => target.kill('SIGKILL'), limitMs);
+        await exited;
+        clearTimeout(timer);
+    };
+    // 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.
+    const helpers = [];
+    const firstBuilds = [];
+    let built = () => { };
+    const vite = join(root, 'node_modules/vite/dist/node/index.js');
+    const watchScript = fileURLToPath(new URL('./vite-watch.js', import.meta.url));
+    for (const [config, label] of [
+        [['vite.config.ts', 'vite.config.mjs', 'vite.config.js'], 'vite'],
+        [['vite.ssr.config.ts', 'vite.ssr.config.mjs', 'vite.ssr.config.js'], 'vite ssr'],
+    ]) {
+        const file = config.find((name) => existsSync(join(root, name)));
+        if (hot || !file || !existsSync(vite))
+            continue;
+        say(`${label}: watching (${file})`);
+        const helper = child([watchScript, file]);
+        helpers.push(helper);
+        let first = true;
+        let resolveFirst;
+        let rejectFirst;
+        firstBuilds.push(new Promise((resolve, reject) => {
+            resolveFirst = resolve;
+            rejectFirst = reject;
+        }));
+        helper.on('message', (message) => {
+            if (message?.failed)
+                say(`${label} build failed; fix it and save again`);
+            if (!message?.built)
+                return;
+            if (first) {
+                first = false;
+                resolveFirst();
+            }
+            else
+                built(label);
+        });
+        helper.once('exit', (code, signal) => {
+            rejectFirst(new CliError('DEV_BUILD_FAILED', `${label} exited (${signal ?? code})`));
+            if (!exiting)
+                say(`${label} exited (${signal ?? code})`);
+        });
+    }
+    if (firstBuilds.length)
+        say('waiting for the first builds');
+    try {
+        await Promise.all(firstBuilds);
+    }
+    catch (error) {
+        exiting = true;
+        await Promise.all(helpers.map((helper) => halt(helper, 5000)));
+        throw error;
+    }
+    run();
+    let timer;
+    let restarting = Promise.resolve();
+    const changed = (what) => {
+        if (exiting)
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            restarting = restarting
+                .then(async () => {
+                if (exiting)
+                    return;
+                say(`${what} changed; restarting`);
+                const previous = app;
+                app = undefined;
+                await halt(previous);
+                if (!exiting)
+                    run();
+            })
+                .catch((error) => {
+                // Keep the loop alive: the next change tries again.
+                reportError('DEV_RESTART_FAILED', 'Restarting the app failed', error);
+            });
+        }, 300);
+    };
+    built = (label) => changed(`${label} build`);
+    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))
+                return;
+            if (helpers.length && name && /\.(vue|css|scss|sass|less)$/.test(name))
+                return;
+            changed(`src/${name ?? ''}`);
+        }),
+        watch(root, (_event, name) => {
+            if (name === 'dokebi.yaml' || name === '.env')
+                changed(name);
+        }),
+    ];
+    return await new Promise((resolve) => {
+        const finish = async () => {
+            if (exiting) {
+                app?.kill('SIGKILL');
+                for (const helper of helpers)
+                    helper.kill('SIGKILL');
+                resolve(130);
+                return;
+            }
+            exiting = true;
+            say('stopping (Ctrl+C again to kill)');
+            clearTimeout(timer);
+            for (const watcher of watchers)
+                watcher.close();
+            await restarting;
+            await Promise.all([halt(app), ...helpers.map((helper) => halt(helper, 5000))]);
+            resolve(0);
+        };
+        process.on('SIGINT', () => void finish());
+        process.on('SIGTERM', () => void finish());
+    });
+}