@dokebi/cli 0.2.5 → 0.4.1

package/dist/guide.js

@@ -0,0 +1,90 @@
+import { COMMANDS } from './commands.js';
+import { CLI_VERSION } from './output.js';
+/** The short pointer printed at the top of `dokebi --help`. */
+export const HELP_POINTER = 'AI and automation: read `dokebi guide` (--json) first. Ask the user every choice and end your turn until they answer; finish with `dokebi verify` and say done only when it is ok. Every command takes --json and changing commands take --dry-run. Outside a project run npx -y @dokebi/cli (inside, npx dokebi uses the project copy); the npm package named "dokebi" is not this CLI\n';
+export const GUIDE_STEPS = [
+    {
+        command: 'npx -y @dokebi/cli init <folder> && cd <folder>',
+        why: 'Only when there is no project yet: creates core, config, this CLI, TypeScript and AGENTS.md (never npx -y dokebi: that npm package belongs to someone else). If the work folder you were given is empty, init . inside it works too',
+    },
+    {
+        command: 'npx dokebi recipe list --json',
+        why: 'Pick the recipe that fits the request (a blog → blog, a JSON API → api). If none fits, use plugins search',
+    },
+    {
+        command: 'npx dokebi recipe <name> --json',
+        why: 'Without answers it installs nothing and returns questions[] (waitForUser: true). Show the user every question with its options, pros/cons and default, then **end your turn**. Ask these questions and end your turn; do not run recipe/add/config until the user answers. Only use --defaults if the user said to decide.',
+    },
+    {
+        command: 'npx dokebi recipe <name> --view <v> --db <d> --dev-infra <i> --admin <a> --answers-from user --dry-run --json',
+        why: 'Only after the user answered: see the plan (plan.steps) and the preflight for those answers. Ask the user about a preflight error (never switch the database or a port behind their back)',
+    },
+    {
+        command: 'npx dokebi recipe <name> --view <v> --db <d> --dev-infra <i> --admin <a> --answers-from user --json',
+        why: 'Apply the plan. Applying needs the source of the answers: --answers-from user (the user answered) or --defaults (the user said to decide); without one it is ANSWERS_SOURCE_REQUIRED. Tell the user the report of the result. Each step runs an existing transactional command; a failure stops with completedSteps, and the same command resumes',
+    },
+    {
+        command: 'npx dokebi plugins doc <id> --json',
+        why: 'Read the AI.md of the installed version of every installed plugin (AGENTS.md lists the paths under "Installed packages")',
+    },
+    {
+        command: '(write the app code) src/apps/<app>, src/shared/modules/<module>',
+        why: "Follow the nextSteps of the recipe result: attach the module to the app and write the features. Build what Dokebi does not have (absent) in app code, as its instead says. Errors and forms (D-0074): refuse input with throw validationError({ field: 'message' }) from @dokebi/web (422 with errors by field, like a refused schema); Inertia form submits pass only (the props they change) and show form.errors; EJS forms show data.errors.<field> and data.old.<field> (with @dokebi/session a refused form comes back to its page, 303); EJS apps may add views/<template>/errors/404.ejs, errors/422.ejs and errors/error.ejs",
+    },
+    {
+        command: 'npx dokebi check --json',
+        why: 'Convention check while you write code (empty catch, promise without await, syntax Node cannot strip, private @dokebi paths, missing packages, edited generated files, secrets that would be committed). Every problem has file, line and fix',
+    },
+    {
+        command: 'npx dokebi verify --json',
+        why: "doctor, check, typecheck, build, start, HTTP checks and stop. Tell the user it is done only when ok: true. Your final message to the user must include verify's tellUser lines (the recipe's choices with who made them, defaults with their reasons, and notices such as no CSRF protection)",
+    },
+];
+export const GUIDE_RULES = [
+    'Never decide choices such as the view, the database, the development database or an admin area yourself. Ask the user the questions[] of the recipe and end your turn. Run no recipe, add or config before they answer (never "I will go on with the defaults while you choose")',
+    'Use --defaults only when the user left the choice to you ("you decide"), and report the chosen values with their defaultReason afterwards. When the user answered, use --answers-from user',
+    'Never invent a plugin, a flag or an API for something Dokebi does not have (absent: auth, csrf, upload, mail, markdown, sqlite, React and more)',
+    'Never install or run a package outside @dokebi/ (THIRD_PARTY_PACKAGE) without the permission of the user',
+    'Never pass a secret with --set or config set (the shell history keeps it). Write it into dokebi.yaml or use the value dev-infra generated',
+    'Preview every changing command with --dry-run --json first. Never blindly re-run a failure, and never delete the lock or a backup',
+    'Only src/dokebi.generated.ts, .dokebi/state.json and the part of AGENTS.md between the dokebi:installed markers are rewritten by the CLI: never edit them by hand. Every other file the CLI or a plugin created (the shared layout src/shared/views/layouts/main.ejs, entry files, app and module files) is user code: edit it where it is (do not move it)',
+    "Never say done before verify returns ok: true. Your final message to the user must include verify's tellUser lines",
+    'Errors (D-0074): Inertia, fetch/XHR, Bearer and JSON-body requests get JSON errors and only plain browser pages get HTML, so read errors from the JSON. Refuse input with validationError({ field: message }) (422 VALIDATION_FAILED, fields and errors), never a hand-made 422; give every Inertia form submit an only option; an EJS write form shows data.errors.<field> and data.old.<field> (add @dokebi/session so a refused form comes back to its page)',
+];
+export function buildGuide(catalog) {
+    const recipes = catalog.recipes.map((recipe) => ({
+        name: recipe.name,
+        summary: recipe.summary,
+        questions: recipe.questions,
+    }));
+    const absent = catalog.absent.map((entry) => entry.capability);
+    const text = [
+        `# Dokebi CLI ${CLI_VERSION} — AI first page`,
+        '',
+        'When the user asks in one line, such as "make me a blog with the Dokebi framework (@dokebi/cli)", follow these steps in order.',
+        '',
+        ...GUIDE_STEPS.map((step, index) => `${index + 1}. ${step.command}\n   ${step.why}`),
+        '',
+        '## Rules',
+        ...GUIDE_RULES.map((rule) => `- ${rule}`),
+        '',
+        '## Recipes',
+        ...recipes.map((recipe) => `- ${recipe.name}: ${recipe.summary} (questions: ${recipe.questions.join(', ')})`),
+        '',
+        `## What Dokebi does not have (absent): ${absent.join(', ')}`,
+        'Details: npx dokebi plugins search <word> --json',
+        '',
+        '## Commands',
+        ...COMMANDS.map((item) => `${item.usage}\n    ${item.summary}`),
+        '',
+    ].join('\n');
+    return {
+        cliVersion: CLI_VERSION,
+        steps: GUIDE_STEPS,
+        rules: GUIDE_RULES,
+        recipes,
+        absent,
+        commands: COMMANDS.map(({ usage, summary }) => ({ usage, summary })),
+        text,
+    };
+}

package/dist/install-plan.d.ts

@@ -1,4 +1,12 @@
 import type { Template } from './manifest.js';
+/**
+ * Who edits a written file (D-0065 §11): `user` — a scaffold written once for the developer to
+ * change (layouts, views, examples); doctor never reports an edit, upgrade keeps an edited copy.
+ * `cli` — a file the CLI or plugin regenerates; an edit is doctor MODIFIED_TEMPLATE (warning) and
+ * a `dokebi check` generated-file problem. Absent means `user`; entry files are always `user`.
+ */
+export declare const FILE_OWNERS: readonly ['user', 'cli'];
+export type FileOwner = (typeof FILE_OWNERS)[number];
 export interface InstallPlan {
     files: Template[];
     directories?: string[];

package/dist/install-plan.js

@@ -2,16 +2,30 @@ import { path as paths } from '@dokebi/core/libraries';
 import { CliError } from './errors.js';
 import { object, relativePath, templateTarget } from './filesystem.js';
 import { validateDefaults } from './merge-install-defaults.js';
+/**
+ * Who edits a written file (D-0065 §11): `user` — a scaffold written once for the developer to
+ * change (layouts, views, examples); doctor never reports an edit, upgrade keeps an edited copy.
+ * `cli` — a file the CLI or plugin regenerates; an edit is doctor MODIFIED_TEMPLATE (warning) and
+ * a `dokebi check` generated-file problem. Absent means `user`; entry files are always `user`.
+ */
+export const FILE_OWNERS = ['user', 'cli'];
 const ENTRY_EXTENSION = /\.(?:ts|mts|js|mjs)$/;
 function template(value, label) {
     const file = object(value, label);
-    if (Object.keys(file).some((key) => key !== 'source' && key !== 'target') ||
+    if (Object.keys(file).some((key) => key !== 'source' && key !== 'target' && key !== 'owner') ||
         typeof file.source !== 'string' ||
-        typeof file.target !== 'string')
-        throw new CliError('INVALID_MANIFEST', `Invalid ${label}`);
+        typeof file.target !== 'string' ||
+        (file.owner !== undefined && !FILE_OWNERS.includes(file.owner)))
+        throw new CliError('INVALID_MANIFEST', `Invalid ${label} (keys: source, target, owner: ${FILE_OWNERS.join(' | ')})`);
     relativePath(file.source);
     templateTarget(file.target);
-    return { source: file.source, target: file.target };
+    return {
+        source: file.source,
+        target: file.target,
+        // `user` is the default: kept implicit so a manifest that spells it out records the same as
+        // one from before the field (otherwise doctor reports MANIFEST_CHANGED for equal manifests).
+        ...(file.owner === 'cli' ? { owner: 'cli' } : {}),
+    };
 }
 /**
  * Validates one installation plan and merges it after the given files.
@@ -47,6 +61,9 @@ export function readInstallPlan(value, legacy, extended = true) {
         }
         if (plan.entry !== undefined) {
             entry = template(plan.entry, 'install entry');
+            // The entry is the developer's code (D-0064): it is never a CLI-owned file.
+            if (entry.owner === 'cli')
+                throw new CliError('INVALID_MANIFEST', 'Install entry is user-owned (owner: "cli" is not allowed)');
             if (!ENTRY_EXTENSION.test(entry.target))
                 throw new CliError('INVALID_MANIFEST', 'Install entry must be a .ts, .mts, .js or .mjs file');
         }

package/dist/layout.d.ts

@@ -4,14 +4,15 @@ import type { InstallPlan } from './install-plan.js';
  * - `src/shared/<area>/…` — shared business code: models, modules (D-0032), views
  * - `src/infra/<name>/…` — code that wires a plugin up (connections, types, shared props …)
  * Files sit inside such a folder; plugins may also create the folder itself.
- * The app plugin also prepares `src/apps/` (each app's folder is made by `dokebi app add`).
+ * The plugin that hosts apps (manifest `dokebi.hosts: ["apps"]`, D-0070) also prepares `src/apps/`
+ * (each app's folder is made by `dokebi app add`).
  */
-export declare function layoutAllowed(path: string, pluginId: string, kind?: 'file' | 'directory'): boolean;
+export declare function layoutAllowed(path: string, hosts?: readonly string[], kind?: 'file' | 'directory'): boolean;
 /** Rejects plugin files and folders outside the layout with INVALID_MANIFEST. */
 export declare function assertLayout(plan: Pick<InstallPlan, 'files' | 'directories'> & {
     entry?: {
         target: string;
     } | undefined;
-}, pluginId: string): void;
+}, pluginId: string, hosts?: readonly string[]): void;
 /** Installed entry paths from before D-0031 keep working; doctor reports them once. */
-export declare function legacyLayout(path: string, pluginId: string): boolean;
+export declare function legacyLayout(path: string, hosts?: readonly string[]): boolean;

package/dist/layout.js

@@ -5,9 +5,10 @@ import { CliError } from './errors.js';
  * - `src/shared/<area>/…` — shared business code: models, modules (D-0032), views
  * - `src/infra/<name>/…` — code that wires a plugin up (connections, types, shared props …)
  * Files sit inside such a folder; plugins may also create the folder itself.
- * The app plugin also prepares `src/apps/` (each app's folder is made by `dokebi app add`).
+ * The plugin that hosts apps (manifest `dokebi.hosts: ["apps"]`, D-0070) also prepares `src/apps/`
+ * (each app's folder is made by `dokebi app add`).
  */
-export function layoutAllowed(path, pluginId, kind = 'file') {
+export function layoutAllowed(path, hosts = [], kind = 'file') {
     const key = paths.portablePathKey(path);
     // Files live inside a named folder: src/shared/<area>/… (models, modules, views — D-0032) or
     // src/infra/<name>/…
@@ -16,20 +17,20 @@ export function layoutAllowed(path, pluginId, kind = 'file') {
         : /^src\/(shared\/(models|modules|views)|infra\/[^/]+)(\/.+)?$/;
     if (area.test(key))
         return true;
-    return pluginId === 'dokebi-app' && (key === 'src/apps' || key.startsWith('src/apps/'));
+    return hosts.includes('apps') && (key === 'src/apps' || key.startsWith('src/apps/'));
 }
 /** Rejects plugin files and folders outside the layout with INVALID_MANIFEST. */
-export function assertLayout(plan, pluginId) {
+export function assertLayout(plan, pluginId, hosts = []) {
     const targets = [
         ...plan.files.map((file) => [file.target, 'file']),
         ...(plan.entry ? [[plan.entry.target, 'file']] : []),
         ...(plan.directories ?? []).map((directory) => [directory, 'directory']),
     ];
     for (const [target, kind] of targets)
-        if (!layoutAllowed(target, pluginId, kind))
+        if (!layoutAllowed(target, hosts, kind))
             throw new CliError('INVALID_MANIFEST', `Plugin ${pluginId} writes outside src/shared/{models,modules,views}/ and src/infra/<name>/: ${target}`);
 }
 /** Installed entry paths from before D-0031 keep working; doctor reports them once. */
-export function legacyLayout(path, pluginId) {
-    return !layoutAllowed(path, pluginId);
+export function legacyLayout(path, hosts = []) {
+    return !layoutAllowed(path, hosts);
 }

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

@@ -0,0 +1,55 @@
+/** The control endpoint listens on loopback only. */
+export declare const CONTROL_HOST = "127.0.0.1";
+/** The proof one side gives for the other side's challenge. */
+export declare function controlAnswer(token: string, role: 'client' | 'writer', challenge: string): string;
+/** What the writer controls: the app it started. */
+export interface ControlledApp {
+    readonly pid: number;
+    running(): boolean;
+    /** Resolves true once the app exited, false when it still runs after `ms`. */
+    exited(ms: number): Promise<boolean>;
+    signal(signal: NodeJS.Signals): void;
+}
+/** The writer's side: listens, authenticates and drain-stops the app on request. */
+export declare class ControlServer {
+    #private;
+    readonly token: string;
+    constructor(token: string);
+    /** The app the writer started; requests before it are answered with NOT_READY. */
+    attach(app: ControlledApp): void;
+    /** Listens on a random loopback port: the port, or undefined (reported) when it cannot. */
+    listen(): Promise<number | undefined>;
+    /** Lets pending replies go out, then ends every connection (the writer is done). */
+    close(): Promise<void>;
+}
+export type ControlRequest = {
+    op: 'status';
+} | {
+    op: 'stop';
+    timeoutMs: number;
+    force: boolean;
+};
+/** The writer answered: its proven identity and its reply to the request. */
+export interface ControlReached {
+    readonly reached: true;
+    readonly writer: number;
+    readonly app: {
+        readonly pid: number;
+        readonly running: boolean;
+    };
+    readonly reply: Record<string, unknown>;
+    /** True once the writer closed the connection (it exited) within `ms`. */
+    closed(ms: number): Promise<boolean>;
+}
+/** The writer could not be asked, or did not prove the token; `reason` says why. */
+export interface ControlUnreached {
+    readonly reached: false;
+    readonly reason: string;
+}
+/**
+ * Asks the log writer listening on the loopback `port` to do `request`, after both sides proved
+ * `token`. Never throws: an unreachable or unproven writer is `reached: false`.
+ */
+export declare function askLogWriter(port: number, token: string, request: ControlRequest, 
+/** How long each step of the handshake may take; a stop's reply waits for the stop itself. */
+stepMs?: number): Promise<ControlReached | ControlUnreached>;

package/dist/log-writer-control.js

@@ -0,0 +1,327 @@
+// The control endpoint of the log writer (D-0073 addendum, AI-M03). Agent sandboxes such as
+// Codex CLI run every shell command in its own sandbox instance and refuse signals across
+// instances: a later `dokebi stop` cannot even `kill(pid, 0)` the app a previous `dokebi start`
+// left running. The log writer was started in that same instance (it is the app's parent) and
+// can signal it, so it listens on a loopback TCP port (127.0.0.1, a random port that `start`
+// records in the 0600 pid file as `control`) and stops the app on request. Loopback TCP rather
+// than a Unix socket: agent sandboxes allow loopback connections when they allow the app's own
+// HTTP port, but may refuse Unix sockets that are not on their allow list (Claude Code).
+//
+// Both sides prove the per-start instance token (DOKEBI_INSTANCE_TOKEN, kept in the pid file)
+// before anything is done; the token never goes on the wire. Newline-delimited JSON:
+//   writer → { hello: 'dokebi-log-writer', version: 1, challenge: W }
+//   client → { challenge: C, answer: HMAC(token, 'dokebi-log-writer:client:' + W) }
+//   writer → { ok: false, code: 'UNAUTHORIZED' } and closes, or
+//            { ok: true, answer: HMAC(token, 'dokebi-log-writer:writer:' + C), writer, app }
+//   client → { op: 'status' } | { op: 'stop', timeoutMs, force }   (only after checking answer)
+//   writer → status: { ok: true, app: { pid, running } }
+//            stop:   { ok: true, stopped, forced, ms } | { ok: false, code: 'STOP_TIMEOUT', message }
+// Only `status` and `stop` exist. The writer closes the connection when it exits, so a client
+// that asked for a stop knows the writer finished (its log closed) when the connection ends.
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createConnection, createServer } from 'node:net';
+import { setTimeout as delay } from 'node:timers/promises';
+import { debug, describeError, reportError } from './diagnostics.js';
+/** The control endpoint listens on loopback only. */
+export const CONTROL_HOST = '127.0.0.1';
+const HELLO = 'dokebi-log-writer';
+const VERSION = 1;
+/** A longer line is not this protocol. */
+const MAX_LINE = 4096;
+/** An unauthenticated connection is closed after this long. */
+const HANDSHAKE_MS = 5000;
+/** The longest stop a client may ask for (one day). */
+const MAX_TIMEOUT_MS = 86_400_000;
+/** The proof one side gives for the other side's challenge. */
+export function controlAnswer(token, role, challenge) {
+    return createHmac('sha256', token).update(`${HELLO}:${role}:${challenge}`).digest('base64url');
+}
+function matches(given, expected) {
+    if (typeof given !== 'string')
+        return false;
+    const a = Buffer.from(given);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** Newline-delimited JSON over a socket: read one message at a time, write messages. */
+class LineSocket {
+    socket;
+    #buffer = '';
+    #queue = [];
+    #waiting;
+    #failure;
+    closed;
+    constructor(socket) {
+        this.socket = socket;
+        socket.setEncoding('utf8');
+        socket.on('data', (chunk) => this.#data(chunk));
+        // Reported to whoever reads next (next() rejects); the socket closes after an error.
+        socket.on('error', (error) => this.#fail(error));
+        this.closed = new Promise((resolve) => socket.once('close', () => resolve()));
+        void this.closed.then(() => this.#fail(new Error('connection closed')));
+    }
+    #data(chunk) {
+        this.#buffer += chunk;
+        for (let end = this.#buffer.indexOf('\n'); end >= 0; end = this.#buffer.indexOf('\n')) {
+            const line = this.#buffer.slice(0, end);
+            this.#buffer = this.#buffer.slice(end + 1);
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch (error) {
+                this.#fail(new Error(`not a protocol message: ${describeError(error).split('\n')[0]}`));
+                this.socket.destroy();
+                return;
+            }
+            this.#queue.push(message);
+        }
+        if (this.#buffer.length > MAX_LINE) {
+            this.#fail(new Error(`a line longer than ${MAX_LINE} characters`));
+            this.socket.destroy();
+            return;
+        }
+        this.#deliver();
+    }
+    #fail(error) {
+        this.#failure ??= error;
+        this.#deliver();
+    }
+    #deliver() {
+        const waiting = this.#waiting;
+        if (!waiting || (!this.#queue.length && !this.#failure))
+            return;
+        this.#waiting = undefined;
+        waiting(this.#queue.length ? this.#queue.shift() : this.#failure);
+    }
+    /** The next message; rejects when the connection fails or closes first, or after `ms`. */
+    next(ms) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#waiting = undefined;
+                reject(new Error(`no answer within ${ms} ms`));
+            }, ms);
+            this.#waiting = (value) => {
+                clearTimeout(timer);
+                if (value instanceof Error)
+                    reject(value);
+                else if (value && typeof value === 'object')
+                    resolve(value);
+                else
+                    reject(new Error('not a protocol message'));
+            };
+            this.#deliver();
+        });
+    }
+    send(message) {
+        if (!this.socket.destroyed)
+            this.socket.write(`${JSON.stringify(message)}\n`);
+    }
+}
+/** The writer's side: listens, authenticates and drain-stops the app on request. */
+export class ControlServer {
+    token;
+    #server;
+    #sockets = new Set();
+    /** Stops under way: close() lets their reply go out first. */
+    #pending = new Set();
+    #app;
+    #port;
+    constructor(token) {
+        this.token = token;
+        this.#server = createServer((socket) => this.#connection(socket));
+        this.#server.maxConnections = 16;
+    }
+    /** The app the writer started; requests before it are answered with NOT_READY. */
+    attach(app) {
+        this.#app = app;
+    }
+    /** Listens on a random loopback port: the port, or undefined (reported) when it cannot. */
+    listen() {
+        return new Promise((resolve) => {
+            const failed = (error) => {
+                // A sandbox without network access refuses listen (EPERM): stop then needs a shell
+                // that may signal the app, as before.
+                reportError('CONTROL_LISTEN_FAILED', 'Unable to open the control port', error);
+                resolve(undefined);
+            };
+            this.#server.once('error', failed);
+            this.#server.listen(0, CONTROL_HOST, () => {
+                this.#server.off('error', failed);
+                this.#server.on('error', (error) => reportError('CONTROL_SOCKET_FAILED', 'The control port failed', error));
+                this.#port = this.#server.address().port;
+                debug('Control port listening', { host: CONTROL_HOST, port: this.#port });
+                resolve(this.#port);
+            });
+        });
+    }
+    /** Lets pending replies go out, then ends every connection (the writer is done). */
+    async close() {
+        if (this.#port === undefined)
+            return;
+        this.#port = undefined;
+        await Promise.race([Promise.allSettled(this.#pending), delay(1000)]);
+        const open = [...this.#sockets].map((socket) => new Promise((resolve) => socket.once('close', () => resolve())));
+        for (const socket of this.#sockets)
+            socket.end();
+        // Stops accepting now; the callback waits for the connections.
+        this.#server.close((error) => {
+            if (error)
+                reportError('CONTROL_SOCKET_FAILED', 'Unable to close the control port', error);
+        });
+        // Give the ended connections a moment to flush before the process exits.
+        await Promise.race([Promise.all(open), delay(1000)]);
+        for (const socket of this.#sockets)
+            socket.destroy();
+        debug('Control port closed');
+    }
+    #connection(socket) {
+        this.#sockets.add(socket);
+        socket.once('close', () => this.#sockets.delete(socket));
+        const lines = new LineSocket(socket);
+        void this.#serve(lines).catch((error) => {
+            // A client that broke the protocol or went silent: nothing was done for it.
+            reportError('CONTROL_REQUEST_FAILED', 'A control request failed', error, 5000);
+            socket.destroy();
+        });
+    }
+    async #serve(lines) {
+        const challenge = randomBytes(24).toString('base64url');
+        lines.send({ hello: HELLO, version: VERSION, challenge });
+        const hello = await lines.next(HANDSHAKE_MS);
+        if (!matches(hello.answer, controlAnswer(this.token, 'client', challenge))) {
+            debug('Control client refused: wrong instance proof');
+            lines.send({ ok: false, code: 'UNAUTHORIZED' });
+            lines.socket.end();
+            return;
+        }
+        if (typeof hello.challenge !== 'string' || hello.challenge.length < 16)
+            throw new Error('the client sent no challenge');
+        const app = this.#app;
+        if (!app) {
+            lines.send({ ok: false, code: 'NOT_READY' });
+            lines.socket.end();
+            return;
+        }
+        lines.send({
+            ok: true,
+            answer: controlAnswer(this.token, 'writer', hello.challenge),
+            writer: process.pid,
+            app: { pid: app.pid, running: app.running() },
+        });
+        const request = await lines.next(HANDSHAKE_MS);
+        if (request.op === 'status') {
+            lines.send({ ok: true, app: { pid: app.pid, running: app.running() } });
+            lines.socket.end();
+            return;
+        }
+        const timeoutMs = request.timeoutMs;
+        if (request.op !== 'stop' ||
+            !Number.isSafeInteger(timeoutMs) ||
+            timeoutMs < 0 ||
+            timeoutMs > MAX_TIMEOUT_MS) {
+            lines.send({ ok: false, code: 'USAGE', message: 'unknown request' });
+            lines.socket.end();
+            return;
+        }
+        const work = this.#stop(app, timeoutMs, request.force === true).then((reply) => lines.send(reply));
+        this.#pending.add(work);
+        try {
+            await work;
+        }
+        finally {
+            this.#pending.delete(work);
+        }
+        // The connection stays open until the writer exits (close()): the client waits for that.
+    }
+    async #stop(app, timeoutMs, force) {
+        const { pid } = app;
+        if (!app.running())
+            return { ok: true, stopped: false };
+        const began = performance.now();
+        const ms = () => Math.round(performance.now() - began);
+        debug('Stopping the app on a control request', { pid, timeoutMs, force });
+        app.signal('SIGTERM');
+        if (await app.exited(timeoutMs))
+            return { ok: true, stopped: true, forced: false, ms: ms() };
+        if (!force)
+            return {
+                ok: false,
+                code: 'STOP_TIMEOUT',
+                message: `pid ${pid} did not stop within ${timeoutMs} ms; it is still draining or stuck (use --force)`,
+            };
+        debug('Stop timed out; sending SIGKILL', { pid });
+        app.signal('SIGKILL');
+        if (await app.exited(5000))
+            return { ok: true, stopped: true, forced: true, ms: ms() };
+        return { ok: false, code: 'STOP_TIMEOUT', message: `pid ${pid} survived SIGKILL` };
+    }
+}
+/**
+ * Asks the log writer listening on the loopback `port` to do `request`, after both sides proved
+ * `token`. Never throws: an unreachable or unproven writer is `reached: false`.
+ */
+export async function askLogWriter(port, token, request, 
+/** How long each step of the handshake may take; a stop's reply waits for the stop itself. */
+stepMs = 3000) {
+    const path = `${CONTROL_HOST}:${port}`;
+    const socket = createConnection({ host: CONTROL_HOST, port });
+    const lines = new LineSocket(socket);
+    const unreached = (reason) => {
+        socket.destroy();
+        debug('Log writer not reached', { path, reason });
+        return { reached: false, reason };
+    };
+    try {
+        await new Promise((resolve, reject) => {
+            socket.once('connect', resolve);
+            socket.once('error', reject);
+        });
+    }
+    catch (error) {
+        const code = error.code;
+        return unreached(code === 'ECONNREFUSED'
+            ? `the log writer is gone (nothing listens on ${path})`
+            : code === 'EPERM' || code === 'EACCES'
+                ? `connecting to ${path} was refused (${code}: a sandbox without local network access?)`
+                : `unable to connect to ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        const hello = await lines.next(stepMs);
+        if (hello.hello !== HELLO || typeof hello.challenge !== 'string')
+            return unreached(`${path} is not a dokebi log writer`);
+        const challenge = randomBytes(24).toString('base64url');
+        lines.send({ challenge, answer: controlAnswer(token, 'client', hello.challenge) });
+        const proof = await lines.next(stepMs);
+        if (proof.code === 'NOT_READY')
+            return unreached('the log writer has not started the app yet');
+        if (proof.ok !== true)
+            return unreached(`the log writer refused the instance proof (${String(proof.code ?? 'no code')}): the pid file's token is not the one this writer was started with`);
+        if (!matches(proof.answer, controlAnswer(token, 'writer', challenge)))
+            return unreached('the process at the control socket did not prove the instance token; nothing was asked');
+        const app = proof.app;
+        if (typeof app?.pid !== 'number' || typeof proof.writer !== 'number')
+            return unreached('the log writer sent an unexpected answer');
+        debug('Log writer proved the instance token', { path, writer: proof.writer, op: request.op });
+        lines.send(request);
+        const replyMs = request.op === 'stop' ? request.timeoutMs + (request.force ? 5000 : 0) + stepMs : stepMs;
+        const reply = await lines.next(replyMs);
+        return {
+            reached: true,
+            writer: proof.writer,
+            app: { pid: app.pid, running: app.running === true },
+            reply,
+            closed: async (ms) => {
+                const done = await Promise.race([
+                    lines.closed.then(() => true),
+                    delay(ms, false, { ref: false }),
+                ]);
+                socket.destroy();
+                return done;
+            },
+        };
+    }
+    catch (error) {
+        return unreached(`the log writer did not complete the request: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}