@dokebi/cli 0.4.1 → 0.4.26

package/dist/transaction.js

@@ -1,13 +1,190 @@
-import { lstat, mkdir, mkdtemp, open, readdir, readFile, rename, rm, rmdir, writeFile, } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { link, lstat, mkdir, mkdtemp, open, readdir, readFile, rename, rm, rmdir, unlink, writeFile, } from 'node:fs/promises';
+import { basename, dirname, join, relative } from 'node:path';
+import { hash as hashing } from '@dokebi/core/libraries';
 import { debug, debugEnabled, describeError, reportError } from './diagnostics.js';
 import { CliError } from './errors.js';
-import { exists, fingerprint, json, securePath } from './filesystem.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
+ * hashed), `symlink` or `other`.
+ */
+async function observe(path) {
+    let stat;
+    try {
+        stat = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (stat.isSymbolicLink())
+        return 'symlink';
+    if (stat.isDirectory())
+        return `directory:${stat.dev}:${stat.ino}`;
+    if (!stat.isFile())
+        return 'other';
+    return `file:${await hashing.sha256File(path)}`;
+}
+const LINK_UNSUPPORTED = new Set(['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'EMLINK', 'EXDEV']);
+/** Why `now` is not the `installed` fingerprint (both as `observe` writes them). */
+function differs(installed, now) {
+    if (now === 'symlink')
+        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;
@@ -22,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 }));
@@ -30,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) => {
@@ -52,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);
@@ -60,23 +257,74 @@ 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.replace(path, source);
+        await this.#add(path, source, `file:${hash(content)}`);
     }
+    /** Puts `source` (a file or folder) at `path` on commit; without `source`, removes `path`. */
     async replace(path, source) {
-        if (this.#changes.some((change) => change.path === path))
-            throw new CliError('DUPLICATE_CHANGE', path);
+        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.#claimed(path))
+            throw duplicateChange(path);
         await this.capture(path);
-        this.#changes.push(source === undefined ? { path } : { path, source });
+        // 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() {
         return this.#changes.map((change) => change.path);
@@ -84,20 +332,52 @@ export class Transaction {
     /**
      * 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.
      */
     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}`);
             }
         }
-        const journal = this.#changes.map((change, index) => ({
-            ...change,
-            backup: join(this.directory, `old-${index}`),
-            existed: this.#snapshots.get(change.path) !== null,
-            backedUp: false,
-            installed: false,
-        }));
+        // 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 } : {}),
+                backup: join(this.directory, `old-${index}`),
+                existed: this.#snapshots.get(change.path) !== null,
+                backedUp: false,
+                installed: false,
+            });
+        }
         await writeFile(join(this.directory, 'journal.json'), json(journal));
         try {
             for (const [index, change] of journal.entries()) {
@@ -134,41 +414,143 @@ export class Transaction {
                     changes: journal.length,
                     error: describeError(cause),
                 });
-            const failures = [];
-            for (const change of [...journal].reverse()) {
+            await this.#rollback(journal, cause);
+        }
+    }
+    async #rollback(journal, cause) {
+        const failures = [];
+        const conflicts = [];
+        for (const [index, change] of [...journal.entries()].reverse()) {
+            try {
+                const conflict = await this.#undo(change, index);
+                if (conflict) {
+                    debug('Rollback kept a path changed during the commit', { ...conflict });
+                    conflicts.push(conflict);
+                }
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length || conflicts.length) {
+            this.#keep = true;
+            const directory = relative(this.root, this.directory);
+            const kept = conflicts.length
+                ? `kept ${conflicts.length} path(s) changed during the operation: ${conflicts
+                    .map((item) => `${item.path} (${item.reason})`)
+                    .join(', ')}; `
+                : '';
+            const failed = failures.length ? `${failures.length} step(s) failed; ` : '';
+            throw new CliError('RECOVERY_REQUIRED', `Rollback ${kept}${failed}preserve ${directory} and .dokebi/lock`, {
+                cause: failures.length ? new AggregateError([cause, ...failures]) : cause,
+                phase: 'commit',
+                details: { conflicts, transaction: directory },
+            });
+        }
+        throw new CliError('COMMIT_FAILED', 'Changes were rolled back', { cause });
+    }
+    /**
+     * Undoes one change unless the path is no longer this commit's own: then leaves it and says
+     * why. The look and the removal cannot be one atomic step; the window is kept to a rename
+     * (see `#undo`'s move-aside) and documented in docs/cli/README.md.
+     */
+    async #undo(change, index) {
+        const backup = change.backedUp ? { backup: relative(this.root, change.backup) } : {};
+        let target;
+        try {
+            // The parent folders, never following a symlink; the path itself is looked at below.
+            const parent = dirname(change.path);
+            const folder = parent === '.' ? this.root : await securePath(this.root, parent);
+            target = join(folder, basename(change.path));
+        }
+        catch (error) {
+            const code = error instanceof CliError ? error.code : undefined;
+            if (code !== 'UNSAFE_PATH' && code !== 'PATH_CONFLICT')
+                throw error;
+            return {
+                path: change.path,
+                reason: code === 'UNSAFE_PATH' ? 'unsafe-path' : 'path-conflict',
+                ...backup,
+            };
+        }
+        if (change.kind === 'directory') {
+            if (!change.installed)
+                return undefined;
+            try {
+                // rmdir removes only an empty folder and never follows a symlink.
+                await rmdir(target);
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === 'ENOENT')
+                    return undefined;
+                if (code === 'ENOTEMPTY' || code === 'EEXIST')
+                    return { path: change.path, reason: 'not-empty' };
+                if (code === 'ENOTDIR')
+                    return { path: change.path, reason: 'replaced' };
+                throw error;
+            }
+            return undefined;
+        }
+        if (change.installed) {
+            const now = await observe(target);
+            if (now !== null) {
+                if (now !== change.installs)
+                    return { path: change.path, reason: differs(change.installs, now), ...backup };
+                // Move it aside (atomic), then look again: an edit between the look and the move is
+                // found here and put back, never deleted.
+                const aside = join(this.directory, `rollback-${index}`);
                 try {
-                    const target = await securePath(this.root, change.path);
-                    if (change.kind === 'directory') {
-                        if (change.installed) {
-                            try {
-                                await rmdir(target);
-                            }
-                            catch (error) {
-                                if (error.code !== 'ENOENT')
-                                    throw error;
-                            }
-                        }
-                        continue;
-                    }
-                    if (change.installed)
-                        await rm(target, { recursive: true, force: true });
-                    if (change.backedUp)
-                        await rename(change.backup, target);
+                    await rename(target, aside);
                 }
                 catch (error) {
-                    failures.push(error);
+                    if (error.code !== 'ENOENT')
+                        throw error;
                 }
+                const moved = await observe(aside);
+                if (moved !== null && moved !== change.installs) {
+                    const restored = await this.#place(aside, target);
+                    return {
+                        path: change.path,
+                        reason: differs(change.installs, moved),
+                        ...backup,
+                        ...(restored ? {} : { kept: relative(this.root, aside) }),
+                    };
+                }
+                if (moved !== null)
+                    await rm(aside, { recursive: true, force: true });
             }
-            if (failures.length) {
-                this.#keep = true;
-                throw new CliError('RECOVERY_REQUIRED', `Rollback failed; preserve ${this.directory} and .dokebi/lock`, {
-                    cause: new AggregateError([cause, ...failures]),
-                });
-            }
-            throw new CliError('COMMIT_FAILED', 'Changes were rolled back', { cause });
         }
+        if (change.backedUp && !(await this.#place(change.backup, target)))
+            return { path: change.path, reason: 'created', ...backup };
+        return undefined;
+    }
+    /**
+     * Moves `from` to `to` without replacing anything at `to`: false when something is there. A
+     * file goes by link + unlink (link fails on an existing name); a folder (or a file system
+     * without hard links) by rename after checking `to` is free, which leaves a tiny window.
+     */
+    async #place(from, to) {
+        try {
+            await link(from, to);
+            await unlink(from);
+            return true;
+        }
+        catch (error) {
+            const code = error.code ?? '';
+            if (code === 'EEXIST')
+                return false;
+            if (!LINK_UNSUPPORTED.has(code))
+                throw error;
+            debug('Rollback restores by rename (no hard link)', { path: to, code });
+        }
+        if ((await observe(to)) !== null)
+            return false;
+        await rename(from, to);
+        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;