@dokebi/cli 0.4.0 → 0.4.2

package/dist/log-writer-control.js

@@ -26,8 +26,13 @@ import { debug, describeError, reportError } from './diagnostics.js';
 export const CONTROL_HOST = '127.0.0.1';
 const HELLO = 'dokebi-log-writer';
 const VERSION = 1;
-/** A longer line is not this protocol. */
+/** A longer line (in bytes, without its newline) is not this protocol. */
 const MAX_LINE = 4096;
+/** Messages (and their bytes) received but not yet read; the protocol needs one at a time. */
+const MAX_QUEUED = 2;
+const MAX_QUEUED_BYTES = MAX_QUEUED * MAX_LINE;
+const NEWLINE = 0x0a;
+const UTF8 = new TextDecoder('utf-8', { fatal: true });
 /** An unauthenticated connection is closed after this long. */
 const HANDSHAKE_MS = 5000;
 /** The longest stop a client may ask for (one day). */
@@ -43,17 +48,30 @@ function matches(given, expected) {
     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. */
+/**
+ * Newline-delimited JSON over a socket: read one message at a time, write messages.
+ *
+ * ISSUE-0006 A05: the limits hold whatever the TCP chunking. Bytes are split on `\n` as they
+ * come; every line (complete or still open) is held to MAX_LINE bytes before it is decoded or
+ * parsed, and a line is taken only while the peer may send one: `expected` messages at first,
+ * then the `replies` each `send` asks for. Anything more is a protocol violation: the queue is
+ * dropped (nothing queued is acted on), next() rejects and the connection is destroyed.
+ */
 class LineSocket {
     socket;
-    #buffer = '';
+    /** The bytes of the line still open (no newline yet). */
+    #pending = [];
+    #pendingBytes = 0;
     #queue = [];
+    #queuedBytes = 0;
+    /** How many more messages the peer may send at this step of the protocol. */
+    #allowance;
     #waiting;
     #failure;
     closed;
-    constructor(socket) {
+    constructor(socket, expected) {
         this.socket = socket;
-        socket.setEncoding('utf8');
+        this.#allowance = expected;
         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));
@@ -61,28 +79,64 @@ class LineSocket {
         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);
+        if (this.#failure)
+            return;
+        let start = 0;
+        for (let end = chunk.indexOf(NEWLINE); end >= 0; end = chunk.indexOf(NEWLINE, start)) {
+            const piece = chunk.subarray(start, end);
+            start = end + 1;
+            const bytes = this.#pendingBytes + piece.length;
+            if (!this.#acceptable(bytes))
+                return;
+            const line = this.#pendingBytes ? Buffer.concat([...this.#pending, piece]) : piece;
+            this.#pending = [];
+            this.#pendingBytes = 0;
+            if (this.#queue.length >= MAX_QUEUED || this.#queuedBytes + bytes > MAX_QUEUED_BYTES) {
+                this.#violation('too many messages waiting');
+                return;
+            }
             let message;
             try {
-                message = JSON.parse(line);
+                message = JSON.parse(UTF8.decode(line));
             }
             catch (error) {
-                this.#fail(new Error(`not a protocol message: ${describeError(error).split('\n')[0]}`));
-                this.socket.destroy();
+                this.#violation(`not a protocol message: ${describeError(error).split('\n')[0]}`);
                 return;
             }
-            this.#queue.push(message);
+            this.#allowance--;
+            this.#queue.push({ message, bytes });
+            this.#queuedBytes += bytes;
         }
-        if (this.#buffer.length > MAX_LINE) {
-            this.#fail(new Error(`a line longer than ${MAX_LINE} characters`));
-            this.socket.destroy();
-            return;
+        const rest = chunk.subarray(start);
+        if (rest.length) {
+            if (!this.#acceptable(this.#pendingBytes + rest.length))
+                return;
+            this.#pending.push(rest);
+            this.#pendingBytes += rest.length;
         }
         this.#deliver();
     }
+    /** A line of `bytes` so far may go on: a message is expected and the line is short enough. */
+    #acceptable(bytes) {
+        if (this.#allowance <= 0) {
+            this.#violation('a message the protocol does not expect at this step');
+            return false;
+        }
+        if (bytes > MAX_LINE) {
+            this.#violation(`a line longer than ${MAX_LINE} bytes`);
+            return false;
+        }
+        return true;
+    }
+    #violation(reason) {
+        debug('Control connection broke the protocol', { reason });
+        this.#queue = [];
+        this.#queuedBytes = 0;
+        this.#pending = [];
+        this.#pendingBytes = 0;
+        this.#fail(new Error(reason));
+        this.socket.destroy();
+    }
     #fail(error) {
         this.#failure ??= error;
         this.#deliver();
@@ -92,7 +146,13 @@ class LineSocket {
         if (!waiting || (!this.#queue.length && !this.#failure))
             return;
         this.#waiting = undefined;
-        waiting(this.#queue.length ? this.#queue.shift() : this.#failure);
+        const next = this.#queue.shift();
+        if (next) {
+            this.#queuedBytes -= next.bytes;
+            waiting(next.message);
+        }
+        else
+            waiting(this.#failure);
     }
     /** The next message; rejects when the connection fails or closes first, or after `ms`. */
     next(ms) {
@@ -113,7 +173,9 @@ class LineSocket {
             this.#deliver();
         });
     }
-    send(message) {
+    /** Sends `message`; the peer may then send `replies` messages (the protocol's next step). */
+    send(message, replies = 0) {
+        this.#allowance += replies;
         if (!this.socket.destroyed)
             this.socket.write(`${JSON.stringify(message)}\n`);
     }
@@ -178,7 +240,8 @@ export class ControlServer {
     #connection(socket) {
         this.#sockets.add(socket);
         socket.once('close', () => this.#sockets.delete(socket));
-        const lines = new LineSocket(socket);
+        // The client speaks only after the hello (which allows its proof).
+        const lines = new LineSocket(socket, 0);
         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);
@@ -187,7 +250,7 @@ export class ControlServer {
     }
     async #serve(lines) {
         const challenge = randomBytes(24).toString('base64url');
-        lines.send({ hello: HELLO, version: VERSION, challenge });
+        lines.send({ hello: HELLO, version: VERSION, challenge }, 1);
         const hello = await lines.next(HANDSHAKE_MS);
         if (!matches(hello.answer, controlAnswer(this.token, 'client', challenge))) {
             debug('Control client refused: wrong instance proof');
@@ -208,7 +271,7 @@ export class ControlServer {
             answer: controlAnswer(this.token, 'writer', hello.challenge),
             writer: process.pid,
             app: { pid: app.pid, running: app.running() },
-        });
+        }, 1);
         const request = await lines.next(HANDSHAKE_MS);
         if (request.op === 'status') {
             lines.send({ ok: true, app: { pid: app.pid, running: app.running() } });
@@ -266,7 +329,8 @@ export async function askLogWriter(port, token, request,
 stepMs = 3000) {
     const path = `${CONTROL_HOST}:${port}`;
     const socket = createConnection({ host: CONTROL_HOST, port });
-    const lines = new LineSocket(socket);
+    // The writer greets first: one message expected.
+    const lines = new LineSocket(socket, 1);
     const unreached = (reason) => {
         socket.destroy();
         debug('Log writer not reached', { path, reason });
@@ -291,7 +355,7 @@ stepMs = 3000) {
         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) });
+        lines.send({ challenge, answer: controlAnswer(token, 'client', hello.challenge) }, 1);
         const proof = await lines.next(stepMs);
         if (proof.code === 'NOT_READY')
             return unreached('the log writer has not started the app yet');
@@ -303,7 +367,7 @@ stepMs = 3000) {
         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);
+        lines.send(request, 1);
         const replyMs = request.op === 'stop' ? request.timeoutMs + (request.force ? 5000 : 0) + stepMs : stepMs;
         const reply = await lines.next(replyMs);
         return {

package/dist/npm-client.d.ts

@@ -17,6 +17,8 @@ export interface NpmRun {
     /** The last NPM_OUTPUT_TAIL_BYTES bytes of each stream, redacted. */
     readonly stderr: string;
     readonly stdout: string;
+    /** npm's error code, summary, log file and report file from the whole stderr. */
+    readonly notes: ReturnType<NpmFailureNotes['details']>;
 }
 /**
  * Runs npm in `directory` (the npm that started this CLI when there is one, else `npm` on PATH)
@@ -54,6 +56,23 @@ export declare class OutputTail {
     push(chunk: Buffer): void;
     text(): string;
 }
+/**
+ * What npm says about a failure, read from its whole stderr (not only the bounded tail, which a
+ * long ERESOLVE explanation fills): the error code (`npm error code ERESOLVE`), the line after it
+ * (the summary), the debug log (`A complete log of this run can be found in: …`) and the report
+ * file (`For a full report see:`). Values are redacted; lines are bounded.
+ */
+export declare class NpmFailureNotes {
+    #private;
+    push(chunk: Buffer): void;
+    /** The notes found so far, as NPM_FAILED details (absent ones are left out). */
+    details(): {
+        npmCode?: string;
+        npmSummary?: string;
+        logFile?: string;
+        reportFile?: string;
+    };
+}
 /**
  * Removes credentials npm may print: `user:password@` in URLs, `_authToken=`/`_auth=`/
  * `_password=` values (npmrc lines), bearer tokens and npm access tokens (`npm_…`).

package/dist/npm-client.js

@@ -110,6 +110,7 @@ export class NpmClient {
                 timedOut: result.timedOut,
                 stderr: result.stderr,
                 stdout: result.stdout,
+                ...result.notes,
             },
         });
     }
@@ -135,8 +136,12 @@ export function runNpm(directory, npmArgs, options) {
         // npm's own words are the cause of a failure: keep the end of both streams (bounded).
         const stdout = new OutputTail();
         const stderr = new OutputTail();
+        const notes = new NpmFailureNotes();
         child.stdout.on('data', (chunk) => stdout.push(chunk));
-        child.stderr.on('data', (chunk) => stderr.push(chunk));
+        child.stderr.on('data', (chunk) => {
+            stderr.push(chunk);
+            notes.push(chunk);
+        });
         let timedOut = false;
         const timer = setTimeout(() => {
             timedOut = true;
@@ -166,6 +171,7 @@ export function runNpm(directory, npmArgs, options) {
                 timedOut,
                 stderr: stderr.text(),
                 stdout: stdout.text(),
+                notes: notes.details(),
             });
         });
     });
@@ -220,6 +226,67 @@ export class OutputTail {
         return redactNpmOutput(this.bytes > this.#buffer.length ? `…${text}` : text);
     }
 }
+/** Longest stderr line NpmFailureNotes keeps while waiting for its end. */
+const NOTE_LINE_BYTES = 2048;
+/**
+ * What npm says about a failure, read from its whole stderr (not only the bounded tail, which a
+ * long ERESOLVE explanation fills): the error code (`npm error code ERESOLVE`), the line after it
+ * (the summary), the debug log (`A complete log of this run can be found in: …`) and the report
+ * file (`For a full report see:`). Values are redacted; lines are bounded.
+ */
+export class NpmFailureNotes {
+    #pending = '';
+    #code;
+    #summary;
+    #logFile;
+    #reportFile;
+    #afterCode = false;
+    #reportNext = false;
+    push(chunk) {
+        const lines = (this.#pending + chunk.toString('utf8')).split('\n');
+        this.#pending = (lines.pop() ?? '').slice(-NOTE_LINE_BYTES);
+        for (const line of lines)
+            this.#line(line.slice(0, NOTE_LINE_BYTES));
+    }
+    #line(raw) {
+        const text = raw.replace(/^npm (?:error|ERR!) ?/, '').trim();
+        if (text === raw.trim())
+            return;
+        const code = /^code (\S+)$/.exec(text);
+        if (code?.[1] && this.#code === undefined) {
+            this.#code = code[1];
+            this.#afterCode = true;
+            return;
+        }
+        if (this.#afterCode && text) {
+            this.#summary = text;
+            this.#afterCode = false;
+        }
+        if (this.#reportNext && text) {
+            this.#reportFile = text;
+            this.#reportNext = false;
+        }
+        const log = /A complete log of this run can be found in:\s*(\S+)/.exec(text);
+        if (log?.[1])
+            this.#logFile = log[1];
+        if (/^For a full report see:$/.test(text))
+            this.#reportNext = true;
+    }
+    /** The notes found so far, as NPM_FAILED details (absent ones are left out). */
+    details() {
+        if (this.#pending) {
+            this.#line(this.#pending);
+            this.#pending = '';
+        }
+        const redacted = (value) => value === undefined ? undefined : redactNpmOutput(value);
+        return Object.fromEntries(Object.entries({
+            npmCode: this.#code,
+            npmSummary: redacted(this.#summary),
+            logFile: redacted(this.#logFile),
+            reportFile: redacted(this.#reportFile),
+        }).filter(([, value]) => value !== undefined));
+    }
+}
 /**
  * Removes credentials npm may print: `user:password@` in URLs, `_authToken=`/`_auth=`/
  * `_password=` values (npmrc lines), bearer tokens and npm access tokens (`npm_…`).

package/dist/output.d.ts

@@ -1,3 +1,3 @@
-export declare const CLI_VERSION = "0.4.0";
+export declare const CLI_VERSION = "0.4.2";
 export declare function envelope(command: string, result: unknown, ok?: boolean): object;
 export declare function failure(command: string, error: unknown, mutationStarted: boolean): object;

package/dist/output.js

@@ -1,5 +1,5 @@
 import { CliError } from './errors.js';
-export const CLI_VERSION = '0.4.0';
+export const CLI_VERSION = '0.4.2';
 export function envelope(command, result, ok = true) {
     return { schemaVersion: 1, cliVersion: CLI_VERSION, command, ok, result, error: null };
 }

package/dist/plugin-lifecycle.js

@@ -1,12 +1,11 @@
-import { realpath } from 'node:fs/promises';
-import { join } from 'node:path';
+import { debug, debugEnabled, describeError } from './diagnostics.js';
 import { CliError } from './errors.js';
 import { object } from './filesystem.js';
-import { InstallPlanningError, PHASE_MISSING, runInstallModule, } from './install-module.js';
+import { InstallPlanningError, installReadRoots, PHASE_MISSING, runInstallModule, } from './install-module.js';
 import { readInstallPlan } from './install-plan.js';
 import { assertLayout } from './layout.js';
 import { ID } from './manifest.js';
-import { packageFile, workspaceRootOf } from './workspace.js';
+import { packageDirectory, packageFile } from './workspace.js';
 // Printable single line: no control characters (log/terminal injection) and a short bound.
 const HINT = /^[^\p{Cc}]{1,200}$/u;
 const CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
@@ -75,11 +74,12 @@ async function run(input, phase, extra = {}) {
     const modulePath = input.plugin.installModule;
     if (!modulePath)
         return PHASE_MISSING;
+    const directory = await packageDirectory(input.base, input.plugin.packageName);
     const path = await packageFile(input.base, input.plugin.packageName, modulePath);
-    // A workspace member's packages live anywhere below the workspace root (D-0035).
-    const workspace = await workspaceRootOf(input.base);
-    const nodeModules = await realpath(workspace ?? join(input.base, 'node_modules'));
     try {
+        // Only the plugin's package and its dependencies are readable (R9), never the project or
+        // the workspace root with their .env files.
+        const readRoots = await installReadRoots(directory);
         return await runInstallModule(path, phase, {
             options: optionsOf(input.options, input.plugin.id),
             plugins: input.plugins.map(({ id, version, packageName }) => ({
@@ -89,9 +89,16 @@ async function run(input, phase, extra = {}) {
             })),
             projectPackages: [...input.projectPackages],
             ...extra,
-        }, [nodeModules]);
+        }, readRoots);
     }
     catch (error) {
+        // The caller sees only the code; debug keeps the cause of an unexpected failure.
+        if (!(error instanceof InstallPlanningError) && debugEnabled())
+            debug('Install module could not be run', {
+                plugin: input.plugin.id,
+                phase,
+                error: describeError(error),
+            });
         throw new CliError('PLUGIN_INSTALL_FAILED', input.plugin.id +
             ': ' +
             (error instanceof InstallPlanningError ? error.code : 'INSTALL_MODULE_FAILED'), { details: { plugin: input.plugin.id, phase } });

package/dist/project-guide.js

@@ -133,7 +133,8 @@ Run the command-line tools installed in this project by their bin names from the
 - **Refuse input with \`throw validationError({ field: 'message' })\`** (\`import { validationError } from '@dokebi/web'\`), not with your own \`reply.code(422).send(...)\`. Clients then get exactly what a refused route schema gives them: 422 \`VALIDATION_FAILED\` with \`fields: [{ field, message }]\` and \`errors: { field: message }\`. Other refusals throw a \`DokebiError\` with a \`status\` (403, 404, 409…).
 - **JSON or HTML is decided for you**: Inertia requests, \`fetch\`/XHR, Bearer API clients and JSON bodies get JSON errors; only plain browser pages (a navigation, an HTML form post) get an HTML page. Read errors from the JSON (\`body.errors.name\`); do not parse HTML.
 - **Inertia forms** (\`useForm().post/put/patch/delete\`, \`router.post/…\`): pass \`only\` with the props the submit changes, for example \`form.post(url, { only: ['items'] })\`. With @dokebi/session a validation error goes back (303) with the messages in \`form.errors.<field>\` (\`errors\` always comes along); without \`only\` the GET after the redirect sends every prop of the page again. \`npx dokebi check\` warns about a submit without \`only\` (\`inertia-form-only\`).
-- **Error pages**: an EJS app shows \`views/<template>/errors/<status>.ejs\` (then \`errors/error.ejs\`) for browser pages, with \`status\`, \`error\`, \`message\`, \`hint\` and \`fields\`; an Inertia app may set \`inertia: { errorPage: 'Error' }\` to render its \`Error\` page component.
+- **EJS (HTML) forms come back with their errors**: with @dokebi/session (\`npx dokebi add @dokebi/session\`) an HTML form post refused with 422 goes back (303) to the page it came from, and every EJS page has \`data.errors\` (\`{ field: message }\`), \`data.old\` (the typed values, never passwords) and \`data.flash\` (other flash, for example \`data.flash.notice\`), always objects. Write each field as \`<input name="title" value="<%= data.old.title ?? '' %>">\` with \`<% if (data.errors.title) { %><small><%= data.errors.title %></small><% } %>\`. Do not call \`request.session.takeFlash()\` in a route that renders a page (the page takes the flash). Without a session the refused form shows \`errors/422.ejs\` (else \`errors/error.ejs\`) with \`fields\`, \`errors\` and \`old\`. HTML forms need \`dokebi-web.formBody: true\`.
+- **Error pages**: an EJS app shows \`views/<template>/errors/<status>.ejs\` (then \`errors/error.ejs\`) for browser pages, with \`status\`, \`error\`, \`message\`, \`hint\`, \`fields\`, \`errors\` and \`old\`; an Inertia app may set \`inertia: { errorPage: 'Error' }\` to render its \`Error\` page component.
 
 ## Installed packages
 

package/dist/project.js

@@ -1596,9 +1596,16 @@ export class Project {
                 await this.npm.installWorkspace(workspace.root);
             }
             catch (cause) {
-                throw new CliError('WORKSPACE_SYNC_FAILED', 'Project files were rolled back; run npm install at the workspace root', {
-                    cause: new AggregateError([failure, cause]),
-                    details: { workspaceRoot: workspace.root },
+                // A rollback that kept user changes (RECOVERY_REQUIRED) stays in the cause and message.
+                const recovery = error instanceof CliError && error.code === 'RECOVERY_REQUIRED' ? error : undefined;
+                throw new CliError('WORKSPACE_SYNC_FAILED', recovery
+                    ? `Project rollback needs recovery (${recovery.message}); then run npm install at the workspace root`
+                    : 'Project files were rolled back; run npm install at the workspace root', {
+                    cause: new AggregateError(recovery ? [recovery, failure, cause] : [failure, cause]),
+                    details: {
+                        workspaceRoot: workspace.root,
+                        ...(recovery ? { recovery: recovery.details } : {}),
+                    },
                 });
             }
             throw error instanceof CliError && error.code === 'RECOVERY_REQUIRED' ? error : failure;

package/dist/recipe.js

@@ -602,9 +602,17 @@ function nextSteps(catalog, recipe, answers, plan, port) {
                 why: 'a refused field comes back to the form (422 → 303 back with errors, @dokebi/session); only keeps the GET after the redirect to the props that changed (npx dokebi check warns: inertia-form-only)',
             }
             : {
-                command: "edit: every write form — in the handler throw validationError({ <field>: '<message>' }) from @dokebi/web; the app's views/default/errors/error.ejs lists the fields for an HTML form post, a fetch reads body.errors.<field>",
-                why: 'a refused route schema and the app check give the same 422 VALIDATION_FAILED with fields and errors (D-0074); never send a hand-made 422',
+                command: 'edit: every write form — <form method="post">, each field value="<%= data.old.<field> ?? \'\' %>" and its message from data.errors.<field>; in the handler throw validationError({ <field>: \'<message>\' }) from @dokebi/web',
+                why: plan.some((step) => step.id === 'session')
+                    ? 'a refused route schema and the app check give the same 422 VALIDATION_FAILED (D-0074); with @dokebi/session (in this plan) the refused form comes back to its page (303) with data.errors and data.old; never send a hand-made 422'
+                    : 'a refused route schema and the app check give the same 422 VALIDATION_FAILED (D-0074); never send a hand-made 422. Without a session the refused form shows views/default/errors/422.ejs (else errors/error.ejs) with fields, errors and old',
             });
+    // D-0074 addendum 1: an EJS write form comes back to its page only with a session.
+    if (recipe.web.forms && !plan.some((step) => step.id === 'view-plugin' || step.id === 'session'))
+        result.push({
+            command: 'npx dokebi add @dokebi/session',
+            why: 'so a refused HTML form goes back to its page with the typed values and the field messages (D-0074 addendum 1) instead of the 422 page; ask the user first (it writes DOKEBI_SESSION_SECRETS into .env and keeps sessions in memory until another store is configured)',
+        });
     const absent = catalog.absent.map((entry) => entry.capability).join(', ');
     result.push({
         command: 'npx dokebi plugins search <feature> --json',

package/dist/server.d.ts

@@ -75,6 +75,13 @@ export interface ProcessInfo {
  * be alive, so callers never treat that as a stale pid file.
  */
 export type ProcessReader = (pid: number) => Promise<ProcessInfo | undefined>;
+/**
+ * Whether a /proc read failed because the process is gone: ENOENT (no /proc/<pid>), or ESRCH,
+ * which Linux returns when the process exits while one of its files is open. Anything else
+ * (permissions, a changed /proc) is a failure. ESRCH was found by the v0.4.1 tag pipeline: an
+ * app that stopped during `stop`'s check ended as PROCESS_INFO_FAILED.
+ */
+export declare function procGone(error: unknown): boolean;
 export declare function status(root: string, 
 /** Tests replace how a process is read; the CLI uses ps (/proc on Linux). */
 read?: ProcessReader,