@dokebi/cli 0.4.2 → 0.4.27

package/dist/transaction.js

@@ -4,6 +4,7 @@ import { hash as hashing } from '@dokebi/core/libraries';
 import { debug, debugEnabled, describeError, reportError } from './diagnostics.js';
 import { CliError } from './errors.js';
 import { exists, fingerprint, hash, json, securePath } from './filesystem.js';
+import { lockDiagnostic, lockHolder } from './project-inspector.js';
 /**
  * What is at `path` now, without following a symlink: null when nothing is there, `file:<sha256>`
  * for a file, `directory:<dev>:<ino>` for a folder (its identity: a folder's content is not
@@ -34,11 +35,156 @@ function differs(installed, now) {
         return 'symlink';
     return installed?.startsWith('file:') && now.startsWith('file:') ? 'modified' : 'replaced';
 }
+/**
+ * DUPLICATE_CHANGE (D-0116): two parts of one change wrote the same path (two plugins with the
+ * same target, a file where a folder goes). A defect of the packages or the CLI, never of the user.
+ */
+function duplicateChange(path) {
+    return new CliError('DUPLICATE_CHANGE', `${path} would be written twice by this change; nothing was written`, {
+        details: {
+            path,
+            fix: 'two packages of this change claim the same path: install them one at a time to see which, and report it to their authors',
+        },
+        phase: 'plan',
+    });
+}
+/**
+ * INTERRUPTED: a termination signal (Ctrl+C, SIGTERM, SIGHUP) came before the commit, so the
+ * change was not applied; the lock and the staging folder are removed as after any refusal.
+ */
+export function interruptedError(signal, cause) {
+    return new CliError('INTERRUPTED', `${signal} received: the change was cancelled before it was applied`, {
+        ...(cause === undefined ? {} : { cause }),
+        details: {
+            signal,
+            fix: 'nothing was written; run the command again when you want the change',
+        },
+        phase: 'plan',
+    });
+}
+const TERMINATION = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+/** The open changes of this process; while there is one, a signal cancels instead of killing. */
+const active = new Set();
+const cancellers = new Map();
+function releaseSignals() {
+    for (const [signal, handler] of cancellers)
+        process.off(signal, handler);
+    cancellers.clear();
+}
+function unwatchSignals(item) {
+    active.delete(item);
+    if (!active.size)
+        releaseSignals();
+}
+/**
+ * The first termination signal while a change is open cancels it: a child npm gets the signal
+ * from its own forwarder (process-group.ts) and fails, a commit not yet begun throws INTERRUPTED,
+ * and the command ends through its usual cleanup, which removes .dokebi/lock and the staging
+ * folder. Killed by the default action instead, the process left both behind, and every later
+ * command was PROJECT_LOCKED until a person looked, although nothing had been applied. A commit
+ * that has begun runs to its end (or its rollback). A second signal ends the process at once.
+ */
+function watchSignals(change) {
+    active.add(change);
+    if (cancellers.size)
+        return;
+    for (const signal of TERMINATION) {
+        const handler = () => {
+            const again = [...active].some((item) => item.interrupted !== undefined);
+            if (again || !active.size) {
+                debug('Second termination signal: ending at once', { signal });
+                releaseSignals();
+                if (process.listenerCount(signal) === 0)
+                    process.kill(process.pid, signal);
+                return;
+            }
+            // dokebi-check: allow console-output the user's terminal: what the first Ctrl+C does
+            process.stderr.write(`dokebi: ${signal} received, cancelling the change (nothing is applied); send it again to stop at once\n`);
+            for (const item of active)
+                item.cancel(signal);
+        };
+        cancellers.set(signal, handler);
+        process.on(signal, handler);
+    }
+}
+/**
+ * A change without a transaction that a termination signal cancels like one (R4CB-3: `dokebi
+ * init`, whose staging folder a killed CLI left in the target folder, so the next init was
+ * PROJECT_EXISTS). Open it before the work, `check()` before the step that makes the change
+ * visible, `failure(error)` for what the work threw, and `close()` in a finally.
+ */
+export class Interruption {
+    #signal;
+    #closed = false;
+    constructor() { }
+    static open() {
+        const interruption = new Interruption();
+        watchSignals(interruption);
+        return interruption;
+    }
+    get interrupted() {
+        return this.#signal;
+    }
+    cancel(signal) {
+        this.#signal ??= signal;
+        debug('Change cancelled by a termination signal', { signal });
+    }
+    /** Throws INTERRUPTED when a signal came. */
+    check() {
+        if (this.#signal)
+            throw interruptedError(this.#signal);
+    }
+    /** INTERRUPTED (with `error` as its cause) when a signal came, else `error` itself. */
+    failure(error) {
+        if (!this.#signal || (error instanceof CliError && error.code === 'INTERRUPTED'))
+            return error;
+        return interruptedError(this.#signal, error);
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        unwatchSignals(this);
+    }
+}
 export class Transaction {
     root;
     directory;
     #snapshots = new Map();
+    #interrupted;
+    #committing = false;
+    /** The termination signal that cancelled this change, if one came. */
+    get interrupted() {
+        return this.#interrupted;
+    }
+    /** Marks the change cancelled (watchSignals); a commit that has begun is not affected. */
+    cancel(signal) {
+        this.#interrupted ??= signal;
+        debug('Change cancelled by a termination signal', { signal, committing: this.#committing });
+    }
+    /**
+     * What a command that owns this transaction throws for `error` (R4CB-4): INTERRUPTED when a
+     * signal cancelled the change before its commit began, whatever part of it then failed (an npm
+     * run other than the staging install, an install module the terminal's Ctrl+C reached too), so
+     * the result says nothing was applied (phase plan, mutation none). From the commit on, the
+     * error stays as it is (COMMIT_FAILED, RECOVERY_REQUIRED, ...).
+     */
+    failure(error) {
+        if (!this.#interrupted || this.#committing)
+            return error;
+        if (error instanceof CliError && error.code === 'INTERRUPTED')
+            return error;
+        return interruptedError(this.#interrupted, error);
+    }
     #changes = [];
+    /**
+     * Paths written with the content they already have: nothing is written there (S-a), but they
+     * stay claimed (a second write is DUPLICATE_CHANGE) and watched (an edit before the commit is
+     * CONCURRENT_CHANGE), as a real change is (R7).
+     */
+    #unchanged = new Set();
+    /** Staging files are numbered when a write starts, so writes in flight never share one. */
+    #staged = 0;
     #keep = false;
     constructor(root, directory) {
         this.root = root;
@@ -53,7 +199,25 @@ export class Transaction {
             handle = await open(lock, 'wx');
         }
         catch (cause) {
-            throw new CliError('PROJECT_LOCKED', 'Another operation or interrupted transaction owns .dokebi/lock', { cause });
+            if (cause.code !== 'EEXIST')
+                throw new CliError('LOCK_FAILED', 'Cannot create .dokebi/lock', {
+                    cause,
+                    details: {
+                        error: cause.code ?? describeError(cause),
+                        fix: 'the project folder (.dokebi) must be writable by this user',
+                    },
+                    phase: 'unknown',
+                });
+            // Who holds it and what to do, as doctor says it (AI-M04 F6): the error had no details.
+            const holder = await lockHolder(root);
+            const { hint, details } = lockDiagnostic(holder ?? { pid: null, running: null, since: null }, []);
+            throw new CliError('PROJECT_LOCKED', 'Another operation or interrupted transaction owns .dokebi/lock', {
+                cause,
+                details: {
+                    ...details,
+                    fix: hint,
+                },
+            });
         }
         try {
             await handle.writeFile(json({ pid: process.pid }));
@@ -61,7 +225,9 @@ export class Transaction {
             if ((await readdir(control)).some((name) => name.startsWith('transaction-'))) {
                 throw new CliError('RECOVERY_REQUIRED', 'Interrupted transaction found; preserve .dokebi/transaction-* for recovery', { phase: 'unknown' });
             }
-            return new Transaction(root, await mkdtemp(join(control, 'transaction-')));
+            const transaction = new Transaction(root, await mkdtemp(join(control, 'transaction-')));
+            watchSignals(transaction);
+            return transaction;
         }
         catch (cause) {
             await handle.close().catch((error) => {
@@ -83,7 +249,7 @@ export class Transaction {
             const planned = this.#changes.find((change) => change.path === current);
             if (planned) {
                 if (planned.kind !== 'directory')
-                    throw new CliError('DUPLICATE_CHANGE', current);
+                    throw duplicateChange(current);
                 continue;
             }
             await this.capture(current);
@@ -91,15 +257,55 @@ export class Transaction {
             if (expected === null)
                 this.#changes.push({ path: current, kind: 'directory' });
             else if (!expected?.startsWith('directory:'))
-                throw new CliError('PATH_CONFLICT', current);
+                throw new CliError('PATH_CONFLICT', `${current} is not a folder, but the change needs a folder there for ${path}`, {
+                    details: {
+                        path: current,
+                        needed: path,
+                        fix: `move ${current} away (a file or link is in the way), then repeat this command`,
+                    },
+                    phase: 'plan',
+                });
+        }
+    }
+    /** The current text of `path` in the project, or undefined when there is none. */
+    async #text(path) {
+        try {
+            return await readFile(await securePath(this.root, path), 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
         }
     }
     async read(path) {
         await this.capture(path);
         return readFile(await securePath(this.root, path), 'utf8');
     }
+    /**
+     * Rewrites text before it is staged (D-0154: the reloadable marks of dokebi.yaml and
+     * dokebi.example.yaml). Set by the operation that owns the transaction.
+     */
+    transformText;
     async write(path, content) {
-        const source = join(this.directory, `new-${this.#changes.length}`);
+        if (typeof content === 'string' && this.transformText) {
+            const transformed = await this.transformText(path, content);
+            // An edit that only dropped marks the file already has (a section rewritten without its
+            // schema at hand) is no change: the file stays as it is and is not reported as changed.
+            content = transformed;
+        }
+        // S-a: the content the file already has is no change: never rewritten (a rewrite with the
+        // same text gave src/dokebi.generated.ts a new time, and dokebi dev restarted the app).
+        if (typeof content === 'string' &&
+            !this.#claimed(path) &&
+            (await this.#text(path)) === content) {
+            await this.capture(path);
+            if (this.#claimed(path))
+                throw duplicateChange(path);
+            this.#unchanged.add(path);
+            return;
+        }
+        const source = join(this.directory, `new-${this.#staged++}`);
         await writeFile(source, content, { mode: 0o600 });
         await this.#add(path, source, `file:${hash(content)}`);
     }
@@ -107,10 +313,17 @@ export class Transaction {
     async replace(path, source) {
         await this.#add(path, source);
     }
+    /** A change of this transaction already claims `path` (a write, a removal, an unchanged write). */
+    #claimed(path) {
+        return this.#unchanged.has(path) || this.#changes.some((change) => change.path === path);
+    }
     async #add(path, source, installs) {
-        if (this.#changes.some((change) => change.path === path))
-            throw new CliError('DUPLICATE_CHANGE', path);
+        if (this.#claimed(path))
+            throw duplicateChange(path);
         await this.capture(path);
+        // Again after the await: a change of the same path may have been added meanwhile.
+        if (this.#claimed(path))
+            throw duplicateChange(path);
         this.#changes.push(source === undefined ? { path } : installs ? { path, source, installs } : { path, source });
     }
     get paths() {
@@ -126,16 +339,36 @@ export class Transaction {
      * in the transaction folder, and the commit ends with RECOVERY_REQUIRED naming those paths.
      */
     async commit(beforeApply, afterApply) {
+        if (this.#interrupted)
+            throw interruptedError(this.#interrupted);
+        this.#committing = true;
         for (const [path, expected] of this.#snapshots) {
             if ((await fingerprint(await securePath(this.root, path))) !== expected) {
                 throw new CliError('CONCURRENT_CHANGE', `File changed while planning: ${path}`);
             }
         }
+        // A staged folder is recognised by its dev:ino, and a file system hands a freed inode number
+        // out again at once (Linux: nearly every time): a node_modules the user removes and creates
+        // while afterApply runs would look like ours, and the rollback would remove the user's folder.
+        // A handle open on each staged folder until the commit ends keeps its inode in use, so no new
+        // folder can get the same number (not on Windows, where a folder cannot be opened).
+        const held = [];
+        try {
+            await this.#apply(held, beforeApply, afterApply);
+        }
+        finally {
+            await Promise.all(held.map((handle) => handle.close()));
+        }
+    }
+    /** The journal, the changes in order and `afterApply`; a failure rolls back (commit). */
+    async #apply(held, beforeApply, afterApply) {
         const journal = [];
         for (const [index, change] of this.#changes.entries()) {
             // What this change installs, to recognise it again in a rollback: a written file's hash, a
             // staged file's hash or a staged folder's identity (node_modules).
             const installs = change.installs ?? (change.source ? await observe(change.source) : null) ?? undefined;
+            if (change.source && installs?.startsWith('directory:') && process.platform !== 'win32')
+                held.push(await open(change.source, 'r'));
             journal.push({
                 ...change,
                 ...(installs ? { installs } : {}),
@@ -317,6 +550,7 @@ export class Transaction {
         return true;
     }
     async close() {
+        unwatchSignals(this);
         if (this.#keep)
             return;
         if (await exists(this.directory)) {

package/dist/verify-tests.d.ts

@@ -0,0 +1,98 @@
+/** Default time limit of the test step (`--test-timeout-ms`), like typecheck and build. */
+export declare const TEST_TIMEOUT_MS = 300000;
+/** At most this many results are listed; failures always are (`omitted` counts the rest). */
+export declare const MAX_TEST_RESULTS = 1000;
+/** A leading `[ABC-12] ` tag of a test name: the id (D-0077 A; the framework gives it no meaning). */
+export declare const TEST_ID: RegExp;
+/** One test of the project (a leaf test, or a suite or parent that failed by itself). */
+export interface TestCaseResult {
+    /** The test's name after the names of its suites and parent tests (` > `). */
+    readonly name: string;
+    /** The `[ID]` tag at the start of its name (else of the nearest suite or parent with one). */
+    readonly id?: string;
+    readonly ok: boolean;
+    readonly ms: number;
+    /** The test file relative to the project (`/` separators). */
+    readonly file?: string;
+    readonly skipped?: true;
+    readonly todo?: true;
+    /** First line of the failure message, secrets masked. */
+    readonly error?: string;
+}
+/** `tests` of the verify result. */
+export type TestReport = {
+    readonly runner: 'node';
+    readonly total: number;
+    readonly passed: number;
+    readonly failed: number;
+    readonly skipped: number;
+    readonly todo: number;
+    readonly ms: number;
+    readonly exitCode: number | null;
+    readonly results: TestCaseResult[];
+    /** Passed or skipped tests left out of `results` beyond MAX_TEST_RESULTS. */
+    readonly omitted?: number;
+} | {
+    readonly runner: 'other';
+    readonly ms: number;
+    readonly exitCode: number | null;
+    /** Why the tests were not run with the per-test reporter. */
+    readonly reason: string;
+};
+/** How the test script is run. */
+export type TestPlan = {
+    readonly runner: 'node';
+    /** The node arguments of the script (reporter flags removed). */
+    readonly args: string[];
+    /** `KEY=value` words before `node`. */
+    readonly env: Record<string, string>;
+} | {
+    readonly runner: 'other';
+    readonly reason: string;
+};
+/**
+ * The words of a script, or undefined when it uses anything a shell would interpret (operators,
+ * substitutions, escapes, globs outside quotes are kept as words: node expands them itself).
+ */
+export declare function scriptWords(script: string): string[] | undefined;
+/** Whether verify can run `script` with its reporter, and how. */
+export declare function planTests(script: string, scripts: Readonly<Record<string, unknown>>): TestPlan;
+/** The id of a test: the tag of its own name, else of the nearest parent with one. */
+export declare function testId(name: string, parents?: readonly string[]): string | undefined;
+/**
+ * The credentials core's `maskCredentials` hides in a text (`//user:pa/ss@` of a URL, also with a
+ * raw `/` in the password; `Password=...` of a connection string): the text itself and the hidden
+ * part, read off its masked form, so verify hides exactly what the logs hide (no rule of its own).
+ */
+export declare function maskedCredentials(text: string): string[];
+/**
+ * Every secret value verify can know for this project: the values of .env, of environment
+ * variables named like a secret (core's `redaction.isSecretEnvironmentName`: the field rule of the
+ * logs plus `*_KEY`, `*_PASS`; never PWD or OLDPWD, which would cut the project folder out of
+ * every error line), and of the options of the settings file (DOKEBI_CONFIG, else dokebi.yaml) `config show` hides. Throws when they cannot be
+ * read (the caller then drops the error lines).
+ */
+export declare function knownSecrets(root: string): Promise<string[]>;
+/** An error line with the known secret values and secret-looking parts replaced by `***`. */
+export declare function maskLine(line: string, secrets: readonly string[]): string;
+/** What the test step reports: the check fields and the `tests` of the verify result. */
+export interface TestStep {
+    readonly ok: boolean;
+    readonly skipped?: string;
+    readonly code?: string;
+    readonly message?: string;
+    readonly details?: unknown;
+    readonly tests?: TestReport;
+}
+/**
+ * The test step of verify for the project at `root` whose package.json scripts are `scripts`.
+ * Throws a CliError (ENV_FILE_INVALID, TEST_FAILED) only when the tests cannot be run at all.
+ */
+export declare function runTests(root: string, scripts: Readonly<Record<string, unknown>>, options?: {
+    readonly timeoutMs?: number;
+}): Promise<TestStep>;
+/**
+ * The human lines verify prints under its test check: one per failing test, then a summary
+ * (each line starts with a newline and two spaces).
+ */
+export declare function testLines(report: TestReport): string;