@dokebi/cli 0.4.2 → 0.4.27

package/dist/template-fixes.js

@@ -0,0 +1,285 @@
+// Template drift (S-c): files copied once from a plugin template and given to the project
+// (`owner: 'user'`: the @dokebi/db adapters, the Vite configs of `app add --inertia`). A later fix
+// of the template never reaches such a copy, so doctor names the fixes it lacks
+// (TEMPLATE_FIX_MISSING), and upgrade names them against the templates it is about to install.
+// A fix is found by a marker in the template and its absence in the copy; the Vite configs are
+// judged on their own (a rolling deploy needs the chunks of the previous build whatever the
+// installed template says).
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { maskCode } from './check/form-rules.js';
+import { debug, isMissing } from './diagnostics.js';
+import { CliError } from './errors.js';
+import { securePath } from './filesystem.js';
+import { installedPath } from './workspace.js';
+const SHARED_ADAPTER_FIXES = [
+    {
+        id: 'client-error',
+        marker: /DB_CLIENT_FAILED/,
+        what: 'a socket error of a client in use is answered and logged instead of ending the worker (DB_CLIENT_FAILED)',
+    },
+    { id: 'lazy', marker: /\blazy\s*:/, what: 'the pool opens on first use (lazy, D-0127)' },
+    {
+        id: 'usage',
+        marker: /\busage\s*:/,
+        what: 'pool usage for the owner share and the metrics (usage, D-0156)',
+    },
+];
+/**
+ * The driver import of each adapter template: with an `@dokebi/db` import it tells a copy of that
+ * template that was moved or renamed (Studio v2, 10-31: copies outside src/infra/db/adapters were
+ * never compared).
+ */
+const ADAPTER_DRIVERS = {
+    pg: /\bfrom\s+['"]pg['"]/,
+    mysql2: /\bfrom\s+['"]mysql2(?:\/promise)?['"]/,
+    mariadb: /\bfrom\s+['"]mariadb['"]/,
+    mongodb: /\bfrom\s+['"]mongodb['"]/,
+};
+/** An adapter of @dokebi/db: the template types its export as one. */
+const ADAPTER_TYPE = /\bResourceAdapter\b[\s\S]*?\bfrom\s+['"]@dokebi\/db['"]|\bfrom\s+['"]@dokebi\/db['"][\s\S]*?\bResourceAdapter\b/;
+/** The code without comments (imports stay: maskCode would blank their module names). */
+const withoutComments = (text) => text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:'"`])\/\/.*$/gm, '$1');
+/** How many files under src/ the adapter search reads at most (a project, not a monorepo). */
+const MAX_SCANNED_FILES = 2000;
+/** TypeScript files under `src/` (not node_modules, not dot folders), project-relative paths. */
+async function sourceFiles(root) {
+    const found = [];
+    const walk = async (folder) => {
+        if (found.length >= MAX_SCANNED_FILES)
+            return;
+        let entries;
+        try {
+            entries = await readdir(await securePath(root, folder), { withFileTypes: true });
+        }
+        catch (error) {
+            if (isMissing(error))
+                return;
+            throw new CliError('READ_FAILED', `Cannot read ${folder}`, { cause: error });
+        }
+        for (const entry of entries) {
+            if (found.length >= MAX_SCANNED_FILES)
+                return;
+            if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                continue;
+            const path = join(folder, entry.name);
+            if (entry.isDirectory())
+                await walk(path);
+            else if (entry.isFile() && /\.(?:ts|mts)$/.test(entry.name))
+                found.push(path);
+        }
+    };
+    await walk('src');
+    return found.map((path) => relative('.', path));
+}
+/** The fixes of each @dokebi/db adapter template (`templates/adapters/<id>.ts`). */
+export const ADAPTER_FIXES = {
+    pg: [
+        ...SHARED_ADAPTER_FIXES,
+        {
+            id: 'lost',
+            marker: /\blost\?\.\(/,
+            what: "a lost connection takes readiness down at once (the periodic healthIntervalMs check covers it later otherwise): take { logger, lost } in create and call lost?.(error) in the pool's and the clients' error handlers",
+        },
+        {
+            id: 'failed-connect',
+            marker: /\.stream\.destroy\(\)/,
+            what: "a client whose connect fails ends its socket (pg-pool drops it without ending it: with a URL without a password the socket stayed open and the process never exited): pass Client: PoolClient to new pg.Pool, a pg.Client subclass whose constructor adds this.connection.on('error', () => this.connection.stream.destroy())",
+        },
+        {
+            id: 'repeats',
+            marker: /logRepeatWindowMs/,
+            what: 'errors of many pooled connections at once (a database restart) are logged in full once per logRepeatWindowMs and counted into one record with repeated (D-0047): add the logRepeatWindowMs option and log the pool and client errors through diagnostics.Repeats (see the template)',
+        },
+    ],
+    mysql2: [
+        ...SHARED_ADAPTER_FIXES,
+        {
+            id: 'idle',
+            marker: /_removeIdleTimeoutConnections/,
+            what: 'idleTimeoutMs closes idle connections (mysql2 runs its idle reaper only when maxIdle < connectionLimit, so it never ran): call pool.pool._removeIdleTimeoutConnections() once after createPool (see the template)',
+        },
+        {
+            id: 'repeats',
+            marker: /logRepeatWindowMs/,
+            what: 'errors of many pooled connections at once (a database restart) are logged in full once per logRepeatWindowMs and counted into one record with repeated (D-0047): add the logRepeatWindowMs option and log the pool and client errors through diagnostics.Repeats (see the template)',
+        },
+        {
+            id: 'connect-cause',
+            marker: /connecting: opens/,
+            what: "a pool wait that ran out while the caller's own new connection was still connecting names that connect in its cause (ETIMEDOUT), so a stopped or frozen server takes readiness down even with max: 1 (it read as a busy pool): compute opens before getConnection and pass { cause } to the deadline error (see the template)",
+        },
+        {
+            id: 'queue-leave',
+            marker: /_connectionQueue/,
+            what: 'a caller whose pool wait ran out leaves mysql2\'s queue (it stayed there and counted against maxWaiting, so live callers got "Queue limit reached."): remove the settle callback from pool._connectionQueue at the deadline (see the template)',
+        },
+    ],
+    mariadb: [
+        ...SHARED_ADAPTER_FIXES,
+        {
+            id: 'lost',
+            marker: /\blost\?\.\(/,
+            what: "a lost connection takes readiness down at once (the periodic healthIntervalMs check covers it later otherwise): take { logger, lost } in create and call lost?.(error) in the pool's and the clients' error handlers",
+        },
+        {
+            id: 'url-query',
+            marker: /\.search\s*===\s*(['"])\1/,
+            what: "a URL with a query is refused instead of dropped (the adapter reads user, password, host, port and database only, so ?ssl=true connected without TLS): add the refine { test: (url) => URL.canParse(url) && new URL(url).search === '', message: ... } to the url option and set connector options such as ssl in the adapter file",
+        },
+        {
+            id: 'idle',
+            marker: /minimumIdle\s*:\s*0\b/,
+            what: 'connections open when callers need them and idle ones end after idleTimeoutMs (the connector kept max connections open at all times): minimumIdle: 0 in createPool',
+        },
+        {
+            id: 'ipv6',
+            marker: /hostname\.replace\(/,
+            what: "an IPv6 literal connects (the URL keeps its brackets, [::1]): host: address.hostname.replace(/^\\[(.*)\\]$/, '$1') in createPool",
+        },
+        {
+            id: 'repeats',
+            marker: /logRepeatWindowMs/,
+            what: 'errors of many pooled connections at once (a database restart) are logged in full once per logRepeatWindowMs and counted into one record with repeated (D-0047): add the logRepeatWindowMs option and log the pool and client errors through diagnostics.Repeats (see the template)',
+        },
+    ],
+    mongodb: SHARED_ADAPTER_FIXES,
+};
+/** The Vite configs `app add --inertia` writes (browser build, server build) and why each keeps its outDir. */
+const VITE_CONFIGS = [
+    {
+        base: 'vite.config',
+        template: 'vite.config.ts',
+        why: 'a rolling deploy serves two builds at once, and the pages of the previous build load hashed chunks this build deleted (404); @dokebi/template-inertia serves every hashed file of dist/assets, so keep them and remove old ones with pruneBuildFiles of @dokebi/template-inertia/prune, which keeps every file the current manifest names (an age-only find also removes the current build after a week without a deploy)',
+    },
+    {
+        base: 'vite.ssr.config',
+        template: 'vite.ssr.config.ts',
+        why: 'a worker started before the build still imports the lazy chunks of its own SSR bundle from dist/ssr until it is replaced',
+    },
+];
+const VITE_EXTENSIONS = ['ts', 'mts', 'js', 'mjs'];
+/** `script: { fs: … }` in the options of the Vue plugin: the compiler reads imported types. */
+const VUE_TYPE_FILES = /\bscript\s*:\s*\{[^}]*\bfs\s*:/;
+async function readOptional(path, label) {
+    try {
+        return await readFile(await path(), 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw new CliError('READ_FAILED', `Cannot read ${label}`, {
+            cause: error,
+            details: { path: label },
+        });
+    }
+}
+/**
+ * TEMPLATE_FIX_MISSING warnings for the copies under `root`. Templates resolve from `base`
+ * (the project, or upgrade's staging install) like Node in a workspace member (D-0035).
+ */
+export async function templateFixes(root, base, sources) {
+    const found = [];
+    // Every copy of an adapter template under src/: the place `dokebi add` writes it, and a file
+    // moved or renamed since (it imports the driver and @dokebi/db's ResourceAdapter).
+    const files = sources.db ? await sourceFiles(root) : [];
+    const texts = new Map();
+    for (const path of files) {
+        const text = await readOptional(() => securePath(root, path), path);
+        if (text !== undefined)
+            texts.set(path, text);
+    }
+    if (sources.db)
+        for (const [adapter, fixes] of Object.entries(ADAPTER_FIXES)) {
+            const usual = `src/infra/db/adapters/${adapter}.ts`;
+            const driver = ADAPTER_DRIVERS[adapter];
+            const copies = [...texts].filter(([path, text]) => path === usual ||
+                (driver.test(withoutComments(text)) && ADAPTER_TYPE.test(withoutComments(text))));
+            if (!copies.length)
+                continue;
+            const template = `node_modules/${sources.db}/templates/adapters/${adapter}.ts`;
+            const source = await readOptional(() => installedPath(base, template), template);
+            if (source === undefined)
+                continue;
+            for (const [path, copy] of copies) {
+                const missing = fixes.filter((fix) => fix.marker.test(source) && !fix.marker.test(copy));
+                if (missing.length)
+                    found.push({
+                        code: 'TEMPLATE_FIX_MISSING',
+                        severity: 'warning',
+                        path,
+                        plugin: 'dokebi-db',
+                        details: { template, missing: missing.map((fix) => fix.id) },
+                        hint: `${path} was copied from ${template} before it got: ${missing.map((fix) => fix.what).join('; ')}. Compare the two files and bring the fixes over (the copy is yours: the CLI never rewrites it)`,
+                    });
+            }
+        }
+    if (sources.inertia)
+        for (const config of VITE_CONFIGS) {
+            let path;
+            let text;
+            for (const extension of VITE_EXTENSIONS) {
+                const name = `${config.base}.${extension}`;
+                text = await readOptional(() => securePath(root, name), name);
+                if (text !== undefined) {
+                    path = name;
+                    break;
+                }
+            }
+            if (path === undefined || text === undefined)
+                continue;
+            // Comments and strings masked: a word in a comment changes no build.
+            const code = maskCode(text);
+            const template = sources.apps
+                ? `node_modules/${sources.apps.packageName}/templates/inertia-build/${config.template}`
+                : undefined;
+            const missing = [];
+            const hints = [];
+            if (!/\bemptyOutDir\s*:\s*false\b/.test(code)) {
+                const explicit = /\bemptyOutDir\s*:\s*true\b/.test(code);
+                debug('Vite config empties its outDir', { path, explicit });
+                missing.push('keep-chunks');
+                hints.push(`${path} ${explicit ? 'sets build.emptyOutDir: true' : 'does not set build.emptyOutDir, and Vite empties its outDir by default'}, so every build deletes the previous build's files: ${config.why}. Set build.emptyOutDir: false in ${path}${template ? ` as ${template} does` : ''}`);
+            }
+            // R4CB-8: the template's fix of 558faf7a (AI-M49 D3), found by its marker in the template.
+            const source = template
+                ? await readOptional(() => installedPath(base, template), template)
+                : undefined;
+            if (source !== undefined &&
+                VUE_TYPE_FILES.test(maskCode(source)) &&
+                !VUE_TYPE_FILES.test(code)) {
+                debug('Vite config gives the Vue compiler no file access', { path });
+                missing.push('vue-type-files');
+                hints.push(`${path} gives the Vue compiler no file access, so a page whose props type comes from another file (defineProps<HomeProps>() with HomeProps imported) fails the build: TypeScript 7 has no JavaScript API for the compiler to read files with. Pass vue({ script: { fs: { fileExists, readFile, realpath } } }) built from node:fs, as ${template} does`);
+            }
+            if (!missing.length)
+                continue;
+            found.push({
+                code: 'TEMPLATE_FIX_MISSING',
+                severity: 'warning',
+                path,
+                plugin: sources.apps?.id ?? 'dokebi-template-inertia',
+                details: { ...(template ? { template } : {}), missing },
+                hint: `${hints.join('. ')} (the file is yours: the CLI never rewrites it)`,
+            });
+        }
+    // R4CB-1: the generated src/main.ts read DOKEBI_CONFIG with `??`, so an empty value was taken
+    // for a path (the working folder) and the app failed to start, while every CLI command reads
+    // dokebi.yaml then (D-0154 D4). Not a plugin's template: doctor names it, upgrade does not.
+    const main = await readOptional(() => securePath(root, MAIN_FILE), MAIN_FILE);
+    if (main !== undefined && EMPTY_CONFIG_ENV.test(maskCode(main))) {
+        debug('src/main.ts takes an empty DOKEBI_CONFIG for a path', { path: MAIN_FILE });
+        found.push({
+            code: 'TEMPLATE_FIX_MISSING',
+            severity: 'warning',
+            path: MAIN_FILE,
+            plugin: null,
+            details: { missing: ['empty-config-env'] },
+            hint: `${MAIN_FILE} reads process.env.DOKEBI_CONFIG with ??, so an empty DOKEBI_CONFIG (DOKEBI_CONFIG= in a shell, an empty CI or container variable) is taken for a path: the app reads the working folder and stops with CONFIG_READ_FAILED, while every dokebi command reads dokebi.yaml then. Write process.env.DOKEBI_CONFIG || where it says process.env.DOKEBI_CONFIG ?? (the file is yours: the CLI never rewrites it)`,
+        });
+    }
+    return found;
+}
+const MAIN_FILE = 'src/main.ts';
+/** `process.env.DOKEBI_CONFIG ??` in code (comments and strings masked). */
+const EMPTY_CONFIG_ENV = /\bprocess\.env\.DOKEBI_CONFIG\s*\?\?/;

package/dist/test-reporter.d.ts

@@ -0,0 +1,49 @@
+/** One line of the report (JSON): a finished test. */
+export interface ReportedTest {
+    /** Its own name. */
+    readonly name: string;
+    /** Names of the suites and parent tests around it, outermost first. */
+    readonly parents: string[];
+    readonly ok: boolean;
+    readonly ms: number;
+    /** Absolute path of the test file, when node:test gave one. */
+    readonly file?: string;
+    readonly skipped?: true;
+    readonly todo?: true;
+    /** First line of the failure message (bounded, not yet masked). */
+    readonly error?: string;
+}
+/** Longest error line kept. */
+export declare const ERROR_LINE_CHARACTERS = 300;
+interface TestData {
+    name?: unknown;
+    nesting?: unknown;
+    file?: unknown;
+    entryFile?: unknown;
+    message?: unknown;
+    skip?: unknown;
+    todo?: unknown;
+    details?: {
+        duration_ms?: unknown;
+        type?: unknown;
+        error?: unknown;
+    };
+}
+/** The first non-empty line of a value's message, bounded; `undefined` when there is none. */
+export declare function firstLine(value: unknown): string | undefined;
+/**
+ * A compared value as it may appear in the report: numbers, booleans, null, undefined and
+ * upper-case codes (`'CSRF_FAILED'`); any other string only by its length (a test password such
+ * as `'hunter2'` never leaves), other values by kind. verify masks the known secrets again.
+ */
+export declare function shownValue(value: unknown): string;
+/**
+ * `name.test.ts:688`: the first frame of the stack in the test file itself. A frame names the file
+ * as a path or as a `file:` URL, where spaces and non-ASCII letters are percent-encoded.
+ */
+export declare function thrownAt(thrown: unknown, file: string): string | undefined;
+export default function dokebiVerifyReporter(source: AsyncIterable<{
+    type: string;
+    data?: TestData;
+}>): AsyncGenerator<string>;
+export {};

package/dist/test-reporter.js

@@ -0,0 +1,190 @@
+// The node:test reporter `dokebi verify` runs the project's tests with (D-0077 H):
+// `node --test --test-reporter=<this file> --test-reporter-destination=<temp file>`. It writes one
+// JSON object per finished test and nothing else: no stdout or stderr of the tests is copied, so
+// a test that prints a secret never puts it in verify's result. Only the first line of a failure
+// message is kept (for a test file that fails before any test runs, the first `…Error` line it
+// printed), bounded in length; verify masks secrets in it again before it reports it. An
+// assertion whose message node wrote itself ("Expected values to be strictly equal:") says
+// nothing on that line, so the values it compared follow when they are short and plain (numbers,
+// booleans, upper-case codes: `401 !== 200`; other strings by length, other values by kind), and every failure ends with
+// where in the test file it was thrown (`portal.test.ts:688`).
+//
+// Node's own machine-readable reporters were the alternative: `tap` and `junit` need a parser
+// for a text format (and junit loses the todo/skip difference and the nesting), while the event
+// stream here is node:test's own structured API, stable since Node 20 and unchanged in 24.
+//
+// Only leaf tests are written (a parent test or a suite passes or fails with its subtests), plus a
+// parent or suite that failed for its own reason (a hook, an assertion after its subtests).
+import { basename, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** Longest error line kept. */
+export const ERROR_LINE_CHARACTERS = 300;
+/** The first non-empty line of a value's message, bounded; `undefined` when there is none. */
+export function firstLine(value) {
+    let text;
+    if (value instanceof Error) {
+        const message = String(value.message ?? '');
+        text = value.name && value.name !== 'Error' ? `${value.name}: ${message}` : message;
+    }
+    else if (typeof value === 'string')
+        text = value;
+    else if (value === undefined || value === null)
+        return undefined;
+    else
+        text = String(value);
+    const line = text
+        .split(/\r?\n/)
+        .map((item) => item.trim())
+        .find((item) => item.length > 0);
+    if (!line)
+        return undefined;
+    return line.length > ERROR_LINE_CHARACTERS ? `${line.slice(0, ERROR_LINE_CHARACTERS)}…` : line;
+}
+/**
+ * A compared value as it may appear in the report: numbers, booleans, null, undefined and
+ * upper-case codes (`'CSRF_FAILED'`); any other string only by its length (a test password such
+ * as `'hunter2'` never leaves), other values by kind. verify masks the known secrets again.
+ */
+export function shownValue(value) {
+    if (value === null || value === undefined || typeof value === 'boolean')
+        return String(value);
+    if (typeof value === 'number' || typeof value === 'bigint')
+        return String(value);
+    if (typeof value === 'string')
+        // A code: upper-case words of at most 15 letters joined by `_`, digits only after one; never
+        // an access key id (AKIA…), a base32 TOTP secret or a licence key (R11).
+        return /^[A-Z]{1,15}(?:_[A-Z0-9]{1,15}){0,5}$/.test(value)
+            ? `'${value}'`
+            : `a string of ${value.length} character${value.length === 1 ? '' : 's'}`;
+    if (Array.isArray(value))
+        return `an array of ${value.length}`;
+    return typeof value === 'object' ? 'an object' : typeof value;
+}
+const OPERATORS = {
+    strictEqual: '!==',
+    equal: '!=',
+    notStrictEqual: '===',
+    notEqual: '==',
+    deepStrictEqual: 'differs from',
+    deepEqual: 'differs from',
+};
+/** What a generated assertion message leaves out: the two values it compared. */
+function compared(thrown) {
+    const failure = thrown;
+    if (failure?.code !== 'ERR_ASSERTION' || failure.generatedMessage !== true)
+        return undefined;
+    const operator = typeof failure.operator === 'string' ? OPERATORS[failure.operator] : undefined;
+    if (!operator)
+        return undefined;
+    return `${shownValue(failure.actual)} ${operator} ${shownValue(failure.expected)}`;
+}
+/**
+ * `name.test.ts:688`: the first frame of the stack in the test file itself. A frame names the file
+ * as a path or as a `file:` URL, where spaces and non-ASCII letters are percent-encoded.
+ */
+export function thrownAt(thrown, file) {
+    const stack = thrown?.stack;
+    if (!file || typeof stack !== 'string')
+        return undefined;
+    const names = [pathToFileURL(file).href, file];
+    for (const frame of stack.split('\n').slice(1))
+        for (const name of names) {
+            const at = frame.indexOf(name);
+            if (at < 0)
+                continue;
+            const line = /^:(\d+)/.exec(frame.slice(at + name.length));
+            if (line)
+                return `${basename(file)}:${line[1]}`;
+        }
+    return undefined;
+}
+/** The failure line of node:test's error: the thrown value (`cause`) rather than the wrapper. */
+function failureLine(error, file = '') {
+    if (!(error instanceof Error)) {
+        const line = firstLine(error);
+        return line ? { line } : {};
+    }
+    const type = error.failureType;
+    const thrown = error.code === 'ERR_TEST_FAILURE' && error.cause !== undefined
+        ? error.cause
+        : error;
+    let line = firstLine(thrown);
+    if (line !== undefined) {
+        const values = compared(thrown);
+        const at = thrownAt(thrown, file);
+        line = `${line}${values ? ` ${values}` : ''}${at ? ` (at ${at})` : ''}`;
+        if (line.length > ERROR_LINE_CHARACTERS)
+            line = `${line.slice(0, ERROR_LINE_CHARACTERS)}…`;
+    }
+    return { ...(line ? { line } : {}), ...(typeof type === 'string' ? { type } : {}) };
+}
+/** `skip` and `todo` are `true` or the reason text when set. */
+const isSet = (value) => value !== undefined && value !== false;
+const ERROR_LINE = /^(?:[A-Z][A-Za-z]*)?Error\b.*$/;
+export default async function* dokebiVerifyReporter(source) {
+    // Per test file: the names of the tests that are running, by nesting level.
+    const stacks = new Map();
+    // Per test file: the first `…Error` line it wrote to stderr (a file that fails to load).
+    const fileErrors = new Map();
+    for await (const event of source) {
+        const data = event.data ?? {};
+        const file = typeof data.file === 'string' ? resolve(data.file) : '';
+        if (event.type === 'test:stderr') {
+            const where = typeof data.entryFile === 'string' ? resolve(data.entryFile) : file;
+            if (fileErrors.has(where) || typeof data.message !== 'string')
+                continue;
+            const line = data.message
+                .split(/\r?\n/)
+                .map((item) => item.trim())
+                .find((item) => ERROR_LINE.test(item));
+            if (line)
+                fileErrors.set(where, firstLine(line));
+            continue;
+        }
+        if (event.type !== 'test:start' && event.type !== 'test:pass' && event.type !== 'test:fail')
+            continue;
+        const name = typeof data.name === 'string' ? data.name : '';
+        const nesting = typeof data.nesting === 'number' && data.nesting >= 0 ? data.nesting : 0;
+        let stack = stacks.get(file);
+        if (!stack) {
+            stack = [];
+            stacks.set(file, stack);
+        }
+        if (event.type === 'test:start') {
+            stack.length = Math.min(stack.length, nesting);
+            const parent = stack[nesting - 1];
+            if (parent)
+                parent.hasChildren = true;
+            stack[nesting] = { name, hasChildren: false };
+            continue;
+        }
+        const frame = stack[nesting];
+        const parents = stack.slice(0, nesting).map((item) => item?.name ?? '');
+        const failed = event.type === 'test:fail';
+        const failure = failed ? failureLine(data.details?.error, file) : {};
+        const suite = data.details?.type === 'suite';
+        const leaf = !suite && !(frame?.name === name && frame.hasChildren);
+        const ownFailure = failed && failure.type !== 'subtestsFailed';
+        if (frame?.name === name)
+            stack.length = nesting;
+        if (!leaf && !ownFailure)
+            continue;
+        let error = failure.line;
+        // A file that fails before its tests run: node:test says only "test failed"; the first
+        // error line the file printed says why (a syntax error, a failed import).
+        if (failed && nesting === 0 && (error === undefined || error === 'test failed'))
+            error = fileErrors.get(file) ?? error;
+        const duration = data.details?.duration_ms;
+        const report = {
+            name,
+            parents,
+            ok: !failed || isSet(data.todo),
+            ms: typeof duration === 'number' ? Math.round(duration) : 0,
+            ...(file ? { file } : {}),
+            ...(isSet(data.skip) ? { skipped: true } : {}),
+            ...(isSet(data.todo) ? { todo: true } : {}),
+            ...(failed && error ? { error } : {}),
+        };
+        yield `${JSON.stringify(report)}\n`;
+    }
+}

package/dist/transaction.d.ts

@@ -1,3 +1,4 @@
+import { CliError } from './errors.js';
 /**
  * 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),
@@ -12,15 +13,60 @@ export interface RollbackConflict {
     readonly backup?: string;
     readonly kept?: string;
 }
+/**
+ * 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 declare function interruptedError(signal: NodeJS.Signals, cause?: unknown): CliError;
+/** Something a termination signal cancels: a transaction, or init's staging (Interruption). */
+interface Cancellable {
+    readonly interrupted: NodeJS.Signals | undefined;
+    cancel(signal: NodeJS.Signals): void;
+}
+/**
+ * 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 declare class Interruption implements Cancellable {
+    #private;
+    private constructor();
+    static open(): Interruption;
+    get interrupted(): NodeJS.Signals | undefined;
+    cancel(signal: NodeJS.Signals): void;
+    /** Throws INTERRUPTED when a signal came. */
+    check(): void;
+    /** INTERRUPTED (with `error` as its cause) when a signal came, else `error` itself. */
+    failure(error: unknown): unknown;
+    close(): void;
+}
 export declare class Transaction {
     #private;
     readonly root: string;
     readonly directory: string;
+    /** The termination signal that cancelled this change, if one came. */
+    get interrupted(): NodeJS.Signals | undefined;
+    /** Marks the change cancelled (watchSignals); a commit that has begun is not affected. */
+    cancel(signal: NodeJS.Signals): void;
+    /**
+     * 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: unknown): unknown;
     private constructor();
     static begin(root: string): Promise<Transaction>;
     capture(path: string): Promise<void>;
     ensureDirectory(path: string): Promise<void>;
     read(path: string): Promise<string>;
+    /**
+     * 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: ((path: string, text: string) => Promise<string>) | undefined;
     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>;
@@ -37,3 +83,4 @@ export declare class Transaction {
     commit(beforeApply?: (index: number) => void, afterApply?: () => Promise<void>): Promise<void>;
     close(): Promise<void>;
 }
+export {};