@dokebi/cli 0.4.1 → 0.4.2

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.1";
+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.1';
+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.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/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, 

package/dist/server.js

@@ -27,7 +27,7 @@
 import { execFile, spawn } from 'node:child_process';
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { existsSync, readFileSync, watch } from 'node:fs';
-import { mkdir, open, readdir, readFile, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import { mkdir, open, readdir, readFile, rename, rm, stat, utimes, writeFile, } from 'node:fs/promises';
 import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { basename, dirname, join } from 'node:path';
@@ -70,6 +70,145 @@ 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');
 }
+/** A start lock not refreshed for this long belongs to a start that died. */
+const LOCK_STALE_MS = 60_000;
+/** A start in progress refreshes its lock this often, however long it waits. */
+const LOCK_REFRESH_MS = 10_000;
+/** Breaking a stale lock takes milliseconds; a guard this old belongs to a process that died. */
+const BREAK_STALE_MS = 10_000;
+/**
+ * The start lock `.dokebi/run/start.lock` (R3). One start at a time holds it from before it
+ * reads the running state until its pid file is written, and `status`/`stop` take it to remove a
+ * stale pid file, so a pid file is only ever replaced or removed by the lock holder. It is
+ * created with `wx`; the holder refreshes it while it waits, so a lock older than LOCK_STALE_MS
+ * belongs to a start that died and is broken (see breakStale) before trying again.
+ */
+class StartLock {
+    file;
+    timer;
+    constructor(file) {
+        this.file = file;
+        this.timer = setInterval(() => {
+            const now = new Date();
+            utimes(file, now, now).catch((error) => {
+                reportError('START_LOCK_REFRESH_FAILED', 'Unable to refresh the start lock', error);
+            });
+        }, LOCK_REFRESH_MS);
+        this.timer.unref();
+    }
+    /** The lock, or undefined while another start holds it. */
+    static async acquire(file) {
+        for (let attempt = 0; attempt < 5; attempt++) {
+            try {
+                await writeFile(file, String(process.pid), { flag: 'wx' });
+                debug('Start lock acquired', { file: basename(file) });
+                return new StartLock(file);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+            let held;
+            try {
+                held = await stat(file);
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+                debug('Start lock released meanwhile; trying again', { attempt });
+                continue;
+            }
+            if (Date.now() - held.mtimeMs < LOCK_STALE_MS)
+                return undefined;
+            if (!(await StartLock.breakStale(file, held)))
+                return undefined;
+        }
+        debug('Start lock still contended after several attempts');
+        return undefined;
+    }
+    /**
+     * Removes the stale lock `held` under the guard `<lock>.break` (created with `wx`), so only one
+     * process breaks it and never a lock another start created after `held` was read (same inode
+     * and time, checked under the guard). False when another process is breaking it right now.
+     * A guard older than BREAK_STALE_MS is left by a process that died within these few steps.
+     */
+    static async breakStale(file, held) {
+        const guard = `${file}.break`;
+        try {
+            await writeFile(guard, String(process.pid), { flag: 'wx' });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let since;
+            try {
+                since = Date.now() - (await stat(guard)).mtimeMs;
+            }
+            catch (cause) {
+                if (!isMissing(cause))
+                    throw cause;
+                debug('The stale start lock was broken meanwhile; trying again');
+                return true;
+            }
+            if (since < BREAK_STALE_MS)
+                return false;
+            debug('Removing the guard of a lock break that died', { ageMs: Math.round(since) });
+            await rm(guard, { force: true });
+            return true;
+        }
+        try {
+            let now;
+            try {
+                now = await stat(file);
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+                return true;
+            }
+            if (now.ino === held.ino && now.mtimeMs === held.mtimeMs) {
+                await rm(file, { force: true });
+                debug('Removed a stale start lock', { ageMs: Math.round(Date.now() - now.mtimeMs) });
+            }
+            return true;
+        }
+        finally {
+            await rm(guard, { force: true });
+        }
+    }
+    async release() {
+        clearInterval(this.timer);
+        await rm(this.file, { force: true });
+        debug('Start lock released', { file: basename(this.file) });
+    }
+}
+/**
+ * Removes the pid file when it still holds `record` (R3): under the start lock, so a start that
+ * wrote a newer record meanwhile keeps it. While a start holds the lock it is left to that start,
+ * which replaces the file anyway. `locked` is true when the caller holds the lock already.
+ */
+async function removeRecord(root, record, locked = false) {
+    const files = paths(root);
+    const lock = locked ? undefined : await StartLock.acquire(files.lock);
+    if (!locked && !lock) {
+        debug('A start holds the lock; leaving the pid file to it', { pid: record.pid });
+        return;
+    }
+    try {
+        const current = await readRecord(root);
+        if (current &&
+            (current.pid !== record.pid ||
+                current.startedAt !== record.startedAt ||
+                current.token !== record.token)) {
+            debug('The pid file names a newer start; keeping it', { pid: record.pid, now: current.pid });
+            return;
+        }
+        await rm(files.pid, { force: true });
+    }
+    finally {
+        await lock?.release();
+    }
+}
 async function readRecord(root) {
     let text;
     try {
@@ -118,6 +257,9 @@ async function procInfo(pid) {
         ]);
         // Fields after the parenthesised command name: state is field 3, starttime field 22.
         const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+        // A zombie has exited and only waits for its parent to reap it: gone for every caller here.
+        if (fields[0] === 'Z')
+            return undefined;
         const ticks = Number(fields[19]);
         const boot = Number(/^btime (\d+)$/m.exec(uptime)?.[1]);
         if (!Number.isFinite(ticks) || !Number.isFinite(boot))
@@ -129,14 +271,22 @@ async function procInfo(pid) {
         };
     }
     catch (error) {
-        // ENOENT: no such process. Anything else (permissions, a changed /proc) is a failure.
         if (error instanceof CliError)
             throw error;
-        if (isMissing(error))
+        if (procGone(error))
             return undefined;
         throw processInfoFailed(pid, '/proc', error);
     }
 }
+/**
+ * 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 function procGone(error) {
+    return isMissing(error) || error?.code === 'ESRCH';
+}
 const readProcess = async (pid) => {
     if (process.platform === 'linux')
         return procInfo(pid);
@@ -210,7 +360,11 @@ export async function status(root,
 read = readProcess, 
 /** Tests replace how a process is signalled; the CLI uses process.kill. */
 kill = signalProcess) {
-    const { pid, log } = paths(root);
+    return statusOf(root, read, kill, false);
+}
+/** `status`; `locked` when the caller (start) holds the start lock. */
+async function statusOf(root, read, kill, locked) {
+    const { log } = paths(root);
     const record = await readRecord(root);
     const logs = await logInfo(root);
     if (!record)
@@ -228,7 +382,7 @@ kill = signalProcess) {
             proof = found;
     }
     if (!info && proof === 'process') {
-        await rm(pid, { force: true });
+        await removeRecord(root, record, locked);
         return {
             running: false,
             stale: true,
@@ -528,48 +682,34 @@ check = checkProject) {
     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);
-    // The project's .env under the CLI's environment (D-0073); a malformed file stops here.
-    const token = randomBytes(24).toString('base64url');
-    const env = appEnvironment(root, 'production', {
-        ...options.env,
-        [INSTANCE_TOKEN_ENV]: token,
-    });
     await mkdir(files.run, { recursive: true });
     await writeFile(join(files.run, '.gitignore'), '*\n');
-    // Lines this start writes begin here (the web listening line is parsed from them).
-    const logOffset = await stat(files.log).then((info) => info.size, (error) => {
-        if (!isMissing(error))
-            throw error;
-        return 0;
-    });
-    // 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));
-    }
+    // One start at a time (R3): the lock is taken before the running state is read, so a start
+    // that waited (in its checks) while another start finished sees that start's app.
+    const lock = await StartLock.acquire(files.lock);
+    if (!lock)
+        throw new CliError('START_IN_PROGRESS', 'Another dokebi start is running for this project');
     const warnings = [];
     let writer;
     try {
+        const current = await statusOf(root, readProcess, signalProcess, true);
+        if (current.running)
+            throw new CliError('ALREADY_RUNNING', `Already running (pid ${current.pid})`, {
+                details: current,
+            });
+        const entry = await check(root);
+        // The project's .env under the CLI's environment (D-0073); a malformed file stops here.
+        const token = randomBytes(24).toString('base64url');
+        const env = appEnvironment(root, 'production', {
+            ...options.env,
+            [INSTANCE_TOKEN_ENV]: token,
+        });
+        // Lines this start writes begin here (the web listening line is parsed from them).
+        const logOffset = await stat(files.log).then((info) => info.size, (error) => {
+            if (!isMissing(error))
+                throw error;
+            return 0;
+        });
         // The writer's own diagnostics (it has no app logger) go to log-writer.log.
         const writerLog = await open(files.writerLog, 'a');
         try {
@@ -690,7 +830,7 @@ check = checkProject) {
         if (writer?.connected)
             writer.disconnect();
         writer?.unref();
-        await rm(files.lock, { force: true });
+        await lock.release();
     }
 }
 /**
@@ -763,7 +903,6 @@ read = readProcess,
 /** Tests replace how a process is signalled; the CLI uses process.kill. */
 kill = signalProcess) {
     daemonOnly();
-    const files = paths(root);
     const record = await readRecord(root);
     if (!record)
         return { stopped: false };
@@ -785,7 +924,7 @@ kill = signalProcess) {
     }
     if (!found) {
         debug('Removing a stale pid file', { pid: record.pid });
-        await rm(files.pid, { force: true });
+        await removeRecord(root, record);
         return { stopped: false, pid: record.pid, stale: true };
     }
     if (proof === 'log-writer')
@@ -829,7 +968,7 @@ kill = signalProcess) {
         if (!(await gone(app, 5000)))
             throw new CliError('STOP_TIMEOUT', `pid ${record.pid} survived SIGKILL`);
     }
-    await rm(files.pid, { force: true });
+    await removeRecord(root, record);
     const warnings = [];
     // The app is stopped and its pid file removed: a failure to read the writer is a warning.
     const writerGone = await gone(writer, 5000).catch((error) => {
@@ -857,7 +996,6 @@ kill = signalProcess) {
  * the connection). An unreachable or unproven writer leaves everything as it was.
  */
 async function stopThroughWriter(root, record, timeoutMs, force, proof, refused) {
-    const files = paths(root);
     const began = performance.now();
     const asked = await askWriter(record, { op: 'stop', timeoutMs, force });
     if (!asked.reached)
@@ -877,7 +1015,7 @@ async function stopThroughWriter(root, record, timeoutMs, force, proof, refused)
             ? reply.message
             : `The log writer could not stop pid ${record.pid} (${String(reply.code)})`);
     }
-    await rm(files.pid, { force: true });
+    await removeRecord(root, record);
     if (reply.stopped !== true) {
         debug('The log writer reports that the app had already exited', { pid: record.pid });
         await asked.closed(0);
@@ -923,11 +1061,11 @@ function pidExists(pid, kill = signalProcess) {
  */
 export async function stopStarted(root, started, timeoutMs = 30_000, force = false) {
     daemonOnly();
-    const files = paths(root);
     const forget = async () => {
         // Only the pid file of this start: another start may have replaced it meanwhile.
-        if ((await readRecord(root))?.pid === started.pid)
-            await rm(files.pid, { force: true });
+        const current = await readRecord(root);
+        if (current?.pid === started.pid)
+            await removeRecord(root, current);
     };
     const gone = async (pid, limit) => {
         const until = performance.now() + limit;

package/dist/transaction.d.ts

@@ -1,3 +1,17 @@
+/**
+ * A path the rollback left as it found it, because it is no longer what this commit put there
+ * (ISSUE-0006 A06): `modified` (other content), `replaced` (a directory or special file now),
+ * `symlink`, `created` (something appeared where the original goes back), `not-empty` (a folder
+ * this commit created now holds files), `unsafe-path` / `path-conflict` (a parent folder became a
+ * symlink or a file). `backup` is the original, kept in the transaction folder; `kept` is where a
+ * file changed during the rollback itself was left.
+ */
+export interface RollbackConflict {
+    readonly path: string;
+    readonly reason: 'modified' | 'replaced' | 'symlink' | 'created' | 'not-empty' | 'unsafe-path' | 'path-conflict';
+    readonly backup?: string;
+    readonly kept?: string;
+}
 export declare class Transaction {
     #private;
     readonly root: string;
@@ -8,11 +22,17 @@ export declare class Transaction {
     ensureDirectory(path: string): Promise<void>;
     read(path: string): Promise<string>;
     write(path: string, content: string | Uint8Array): Promise<void>;
+    /** Puts `source` (a file or folder) at `path` on commit; without `source`, removes `path`. */
     replace(path: string, source?: string): Promise<void>;
     get paths(): string[];
     /**
      * Applies every change; `afterApply` runs once they are all in place, and when it fails the
      * changes are rolled back like a failed apply (D-0035: the workspace npm install).
+     *
+     * The rollback only undoes what is still this commit's own (ISSUE-0006 A06): `afterApply` can
+     * run for minutes while the user edits files. A path that is no longer what this commit put
+     * there (or, for a removed path, where something appeared) is left as it is, its original stays
+     * in the transaction folder, and the commit ends with RECOVERY_REQUIRED naming those paths.
      */
     commit(beforeApply?: (index: number) => void, afterApply?: () => Promise<void>): Promise<void>;
     close(): Promise<void>;