@dokebi/cli 0.2.3 → 0.2.4

package/dist/output.js

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

package/dist/project-inspector.js

@@ -5,6 +5,7 @@ import { CONFIG_FILE, LEGACY_CONFIG_FILE, parseProjectConfig } from './configura
 import { CliError } from './errors.js';
 import { exists, fingerprint, hash, json, parseObject, securePath } from './filesystem.js';
 import { legacyLayout } from './layout.js';
+import { loggingDiagnostics } from './logging-config.js';
 import { orderPlugins, readManifest } from './manifest.js';
 import { dependencyMap, validateProjectPackage } from './npm-client.js';
 import { checkPlugin } from './plugin-lifecycle.js';
@@ -93,6 +94,14 @@ export class ProjectInspector {
             matches('@dokebi/core', core, null);
         if (pkg && !Object.hasOwn(pkg, '@dokebi/core'))
             issue('MISSING_CORE_DEPENDENCY', 'package.json');
+        if (config) {
+            // options.logging is the logger configuration (D-0047), not a plugin's options.
+            const known = new Set([
+                ...(state?.plugins.map((plugin) => plugin.id) ?? []),
+                ...result.requiredPlugins.map((plugin) => plugin.id),
+            ]);
+            result.diagnostics.push(...loggingDiagnostics(config.options, known));
+        }
         const generated = await check('src/dokebi.generated.ts', () => read('src/dokebi.generated.ts'));
         if (state && generated !== null && hash(generated) !== state.generatedHash)
             issue('MODIFIED_REGISTRATION', 'src/dokebi.generated.ts');

package/dist/project.js

@@ -332,16 +332,19 @@ export class Project {
                 if (await exists(await securePath(session.root, directory)))
                     preserved.push(directory);
             }
+            const warnings = [];
             if (await exists(await securePath(session.root, EXAMPLE))) {
                 const example = await tx.read(EXAMPLE);
+                let updated;
                 try {
-                    const updated = markExampleRemoved(example, removed.id);
-                    if (updated !== example)
-                        await tx.write(EXAMPLE, updated);
+                    updated = markExampleRemoved(example, removed.id);
                 }
                 catch {
-                    /* An invalid example file is reported by doctor, not by remove. */
+                    // The removal still proceeds; the caller sees why the example was left as it was.
+                    warnings.push({ code: 'EXAMPLE_INVALID', path: EXAMPLE });
                 }
+                if (updated !== undefined && updated !== example)
+                    await tx.write(EXAMPLE, updated);
             }
             state.plugins = ordered;
             state.installations = installations;
@@ -351,6 +354,7 @@ export class Project {
                 changed: tx.paths,
                 preserved,
                 ...(configRequired.length ? { configRequired } : {}),
+                ...(warnings.length ? { warnings } : {}),
             };
             return await this.#finish(session, result, dryRun);
         }

package/dist/rotating-log.d.ts

@@ -0,0 +1,27 @@
+/** `app.log`, then `app.log.1` … (newest first), for the files that exist without a gap. */
+export declare function logFiles(file: string, limit?: number): string[];
+/** Cuts a byte stream into whole lines; the unfinished end waits for the next chunk. */
+export declare class LineBuffer {
+    #private;
+    /** The whole lines of what was received so far (undefined when there is none yet). */
+    push(chunk: Buffer): Buffer | undefined;
+    get pending(): boolean;
+    /** The unfinished end (a line without its newline yet), emptied. */
+    take(): Buffer;
+}
+export declare class RotatingLog {
+    #private;
+    readonly file: string;
+    readonly maxBytes: number;
+    readonly keep: number;
+    /** Bytes that could not be written (disk full, removed folder); reported, never silent. */
+    dropped: number;
+    constructor(file: string, maxBytes: number, keep: number);
+    /** Opens (appends to) the log; a file already over the limit is rotated first. */
+    open(): void;
+    /** Appends whole lines, rotating between lines when the limit would be passed. */
+    write(data: Buffer): void;
+    /** app.log → app.log.1, app.log.1 → app.log.2 …; the oldest beyond `keep` is removed. */
+    rotate(): void;
+    close(): void;
+}

package/dist/rotating-log.js

@@ -0,0 +1,166 @@
+// Size-based rotation of the background app log (D-0053). The log writer process owns the file:
+// `app.log` is written until the next lines would pass the limit, then it becomes `app.log.1`
+// (older files shift up to `app.log.<keep>`, anything older is removed) and a new `app.log`
+// starts. Files are cut between lines, so a line is never split across two files.
+import { closeSync, existsSync, fstatSync, openSync, renameSync, rmSync, writeSync } from 'node:fs';
+import { debug, isMissing, reportError } from './diagnostics.js';
+/** `app.log`, then `app.log.1` … (newest first), for the files that exist without a gap. */
+export function logFiles(file, limit = 1000) {
+    const files = [];
+    if (existsSync(file))
+        files.push(file);
+    for (let index = 1; index <= limit && existsSync(`${file}.${index}`); index++)
+        files.push(`${file}.${index}`);
+    return files;
+}
+const NEWLINE = 0x0a;
+/** Partial lines longer than this are written without waiting for their end. */
+const MAX_PARTIAL = 64 * 1024;
+/** Cuts a byte stream into whole lines; the unfinished end waits for the next chunk. */
+export class LineBuffer {
+    #partial = Buffer.alloc(0);
+    /** The whole lines of what was received so far (undefined when there is none yet). */
+    push(chunk) {
+        const data = this.#partial.length ? Buffer.concat([this.#partial, chunk]) : chunk;
+        const end = data.lastIndexOf(NEWLINE);
+        if (end < 0 && data.length < MAX_PARTIAL) {
+            this.#partial = data;
+            return undefined;
+        }
+        const cut = end < 0 ? data.length : end + 1;
+        this.#partial = data.subarray(cut);
+        return data.subarray(0, cut);
+    }
+    get pending() {
+        return this.#partial.length > 0;
+    }
+    /** The unfinished end (a line without its newline yet), emptied. */
+    take() {
+        const rest = this.#partial;
+        this.#partial = Buffer.alloc(0);
+        return rest;
+    }
+}
+export class RotatingLog {
+    file;
+    maxBytes;
+    keep;
+    #fd;
+    #size = 0;
+    #rotateAfter = 0;
+    /** Bytes that could not be written (disk full, removed folder); reported, never silent. */
+    dropped = 0;
+    constructor(file, maxBytes, keep) {
+        this.file = file;
+        this.maxBytes = maxBytes;
+        this.keep = keep;
+    }
+    /** Opens (appends to) the log; a file already over the limit is rotated first. */
+    open() {
+        this.#fd = openSync(this.file, 'a');
+        this.#size = fstatSync(this.#fd).size;
+        debug('App log opened', { file: this.file, bytes: this.#size, maxBytes: this.maxBytes });
+        if (this.#size >= this.maxBytes)
+            this.rotate();
+    }
+    /** Appends whole lines, rotating between lines when the limit would be passed. */
+    write(data) {
+        let rest = data;
+        while (rest.length) {
+            if (this.#size + rest.length <= this.maxBytes || Date.now() < this.#rotateAfter) {
+                this.#append(rest);
+                return;
+            }
+            const room = this.maxBytes - this.#size;
+            const cut = room > 0 ? rest.lastIndexOf(NEWLINE, room - 1) : -1;
+            if (cut >= 0) {
+                this.#append(rest.subarray(0, cut + 1));
+                rest = rest.subarray(cut + 1);
+            }
+            else if (this.#size === 0) {
+                // A single line longer than the limit fills a file by itself.
+                const end = rest.indexOf(NEWLINE);
+                const length = end < 0 ? rest.length : end + 1;
+                this.#append(rest.subarray(0, length));
+                rest = rest.subarray(length);
+            }
+            if (!rest.length)
+                return;
+            this.rotate();
+        }
+    }
+    /** app.log → app.log.1, app.log.1 → app.log.2 …; the oldest beyond `keep` is removed. */
+    rotate() {
+        const began = performance.now();
+        try {
+            this.#close();
+            for (let index = this.keep - 1; index >= 1; index--)
+                this.#move(index, index + 1);
+            renameSync(this.file, `${this.file}.1`);
+            for (let index = this.keep + 1; existsSync(`${this.file}.${index}`); index++)
+                rmSync(`${this.file}.${index}`, { force: true });
+            this.#fd = openSync(this.file, 'a');
+            debug('App log rotated', {
+                file: this.file,
+                bytes: this.#size,
+                keep: this.keep,
+                ms: Math.round(performance.now() - began),
+            });
+            this.#size = 0;
+        }
+        catch (error) {
+            // Keep writing to the current file; try rotating again in 5 s.
+            reportError('LOG_ROTATE_FAILED', 'Unable to rotate the app log', error, 5000);
+            this.#rotateAfter = Date.now() + 5000;
+            this.#reopen();
+        }
+    }
+    close() {
+        this.#close();
+        if (this.dropped)
+            reportError('LOG_LINES_DROPPED', 'Some app output could not be written to the log', new Error(`${this.dropped} bytes were not written to ${this.file}`));
+    }
+    #move(from, to) {
+        try {
+            renameSync(`${this.file}.${from}`, `${this.file}.${to}`);
+        }
+        catch (error) {
+            // Fewer rotated files than `keep` exist yet: nothing to shift.
+            if (!isMissing(error))
+                throw error;
+        }
+    }
+    #close() {
+        if (this.#fd === undefined)
+            return;
+        const fd = this.#fd;
+        this.#fd = undefined;
+        closeSync(fd);
+    }
+    #reopen() {
+        if (this.#fd !== undefined)
+            return;
+        try {
+            this.#fd = openSync(this.file, 'a');
+            this.#size = fstatSync(this.#fd).size;
+        }
+        catch (error) {
+            reportError('LOG_OPEN_FAILED', 'Unable to open the app log', error, 5000);
+        }
+    }
+    #append(data) {
+        this.#reopen();
+        let offset = 0;
+        try {
+            if (this.#fd === undefined)
+                throw new Error(`${this.file} is not open`);
+            while (offset < data.length)
+                offset += writeSync(this.#fd, data, offset);
+        }
+        catch (error) {
+            this.dropped += data.length - offset;
+            reportError('LOG_WRITE_FAILED', 'Unable to write the app log; output is lost', error, 5000);
+        }
+        this.#size += offset;
+    }
+}

package/dist/server.d.ts

@@ -1,8 +1,29 @@
+/** Rotation defaults and limits (D-0053): `--log-max-mb`, `--log-files`. */
+export declare const LOG_LIMITS: {
+    readonly maxMb: {
+        readonly default: 50;
+        readonly min: 1;
+        readonly max: 10240;
+    };
+    readonly files: {
+        readonly default: 5;
+        readonly min: 1;
+        readonly max: 100;
+    };
+};
 export interface PidRecord {
     readonly pid: number;
     readonly startedAt: string;
     readonly entry: string;
     readonly node: string;
+    /** The log writer process (D-0053); absent in pid files of older CLIs. */
+    readonly logWriter?: number;
+    readonly logMaxBytes?: number;
+    readonly logFiles?: number;
+}
+export interface LogFile {
+    readonly file: string;
+    readonly bytes: number;
 }
 export interface ServerStatus {
     readonly running: boolean;
@@ -13,17 +34,40 @@ export interface ServerStatus {
     /** A pid file was left by a process that is gone (crashed or killed); it was removed. */
     readonly stale?: boolean;
     readonly log: string;
+    /** app.log and its rotated files, newest first. */
+    readonly logFiles: LogFile[];
+    /** The log writer of the running app and whether it is alive. */
+    readonly logWriter?: {
+        readonly pid: number;
+        readonly running: boolean;
+    };
+    /** The writer's own diagnostics, when it wrote any. */
+    readonly logWriterLog?: string;
 }
 export declare function status(root: string): Promise<ServerStatus>;
+export interface LogOptions {
+    /** Rotate app.log when it would pass this size (default 50 MB). */
+    readonly logMaxBytes?: number;
+    /** Rotated files to keep, app.log.1 … app.log.<n> (default 5). */
+    readonly logFiles?: number;
+}
 export interface StartResult {
     readonly pid: number;
     readonly log: string;
+    /** The detached process that writes and rotates the log (D-0053). */
+    readonly logWriter: number;
+    readonly logMaxBytes: number;
+    readonly logFiles: number;
     /** False when the process is alive but never logged the start line within the wait. */
     readonly ready: boolean;
     readonly ms: number;
     readonly warnings: string[];
 }
-export declare function start(root: string, waitMs?: number, 
+export interface StartOptions extends LogOptions {
+    /** How long to wait for the start line (default 10000 ms). */
+    readonly waitMs?: number;
+}
+export declare function start(root: string, options?: StartOptions, 
 /** Tests replace the project inspection; the CLI always inspects. */
 check?: (root: string) => Promise<string>): Promise<StartResult>;
 export interface StopResult {
@@ -32,10 +76,18 @@ export interface StopResult {
     readonly ms?: number;
     readonly forced?: boolean;
     readonly stale?: boolean;
+    /** Set when the log writer was still running 5 s after the app stopped. */
+    readonly warnings?: string[];
 }
 export declare function stop(root: string, timeoutMs?: number, force?: boolean): Promise<StopResult>;
-/** Prints the last `lines` lines; with `follow`, keeps printing what is appended until SIGINT. */
-export declare function logs(root: string, lines?: number, follow?: boolean, write?: (text: string) => void): Promise<void>;
+/**
+ * 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 declare function logs(root: string, lines?: number, follow?: boolean, write?: (text: string) => void, signal?: AbortSignal): Promise<void>;
 /** Runs the app in the foreground and forwards SIGINT/SIGTERM; resolves with its exit code. */
 export declare function foreground(root: string): Promise<number>;
 /**