@zyplux/spectra 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergiy Yeskov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# @zyplux/spectra
+
+Shared Vitest fixtures, matchers, polling, and journal reporting for Node CLIs and libraries. Fakes swap in at the lowest boundary (`node:child_process`, `node:readline/promises`, `node:timers/promises`, `fetch`, `console`, `process.env`) so tests exercise only public interfaces.
+
+## Install
+
+```sh
+pnpm add -D @zyplux/spectra
+```
+
+Each fake needs the Node module it stands in for mocked in that project's own vitest setup file — only the modules whose fakes you use:
+
+```ts
+import { vi } from 'vitest';
+
+vi.mock('node:child_process', async importOriginal => {
+  const actual = await importOriginal<typeof import('node:child_process')>();
+  return { ...actual, spawn: vi.fn(actual.spawn) }; // shell fake
+});
+// node:readline/promises -> createInterface (prompt fake); node:timers/promises -> setTimeout (instant sleeps)
+```
+
+Each factory wraps the original, so the module stays fully live until a fake installs an implementation. A fake whose module is unmocked says which one to add.
+
+## Use
+
+Each story domain has a named fixture module, such as `stories/repositories/repositories.ts`. Extend a base with the subjects that its tests need:
+
+```ts
+import { runPushBranch } from '@example/app';
+import { cliTest } from '@zyplux/spectra/library-test-api';
+
+export const test = cliTest.extend('runPushBranch', () => runPushBranch);
+export { describe, expect } from 'vitest';
+```
+
+```ts
+import { describe, expect, test } from './repositories.ts';
+
+describe('1.1 pushing a branch', () => {
+  test('1.1.1 pushes and reports the PR url', async ({ logs, runPushBranch, shell }) => {
+    shell.on('git rev-parse --abbrev-ref HEAD', 'feat-x');
+    shell.on('git push', '');
+
+    await runPushBranch({ command: 'push-branch', hold: false, ready: false });
+
+    expect(shell).toHaveRun('git push --set-upstream origin feat-x');
+    expect(logs).toHaveLogged('PR (draft): https://github.com/acme/repo/pull/1');
+  });
+});
+```
+
+## Entry points
+
+Each tool has a named entry point. Import the Vitest bases from `/library-test-api`; load the reporter from `/journald-reporter` in Vitest configuration.
+
+| Import path after `@zyplux/spectra` | Purpose |
+| --- | --- |
+| `/library-test-api` | Library and CLI Vitest bases |
+| `/shell-fake`, `/fetch-fake`, `/prompt-fake` | Fakes for subprocesses, HTTP, and prompts |
+| `/cli-runner`, `/temp-directory`, `/poll-until` | CLI execution, scratch directories, and test polling |
+| `/test-matchers` | Register shared Vitest matchers |
+| `/console-capture` | Capture console messages |
+| `/journald-reporter` | Record Vitest results and console output in systemd's journal |
+| `/package.json` | Package metadata |
+
+Internal helpers stay beside the tools that use them: pattern matching and module mock validation live in `helpers`; journal stream writing lives in `reporters`.
+
+## Bases
+
+- `libraryTest` — lazy fixtures: `shell` (fake `node:child_process` spawn, installed only when destructured), `tempDir` (auto-removed scratch directory with `path`, `write`, `exists`).
+- `cliTest` — extends `libraryTest`; automatically captures and silences `console` (`logs`), makes `node:timers/promises` sleeps instant, and installs `network` (fake `fetch`). It adds lazy `prompt` (fake `node:readline/promises` interface that records every question and answers with an empty string) and `env` (`set(name, value)` stubs an env var for the test).
+
+## Fakes and helpers
+
+- `createShellFake()` — routes commands (`on(pattern, ...replies)`, later routes win, the last reply repeats; `otherwise(reply)` sets a fallback, unrouted commands throw) and records `calls` (`{ argv, cwd?, env?, program, stdin? }`), `commands` (rendered strings), `commandsMatching(pattern)`.
+- `createConsoleCapture()` — records `logLines`/`warnLines`/`errorLines`.
+- `createFetchFake()` — routes urls (`on(prefixOrRegExp, reply)`, `otherwise(reply)`) and records `requests`; `okResponse()`/`notFoundResponse()` build replies.
+- `createPromptFake()` — records `question()` messages and immediately returns an empty string, simulating Enter without typed input. It lets tests exercise terminal prompts without waiting for keyboard input.
+- `createTempDir()` — `path`, `write(relativePath, content)`, `exists(relativePath)`, `remove()`.
+
+## Matchers
+
+Importing a base registers domain matchers via `expect.extend`:
+
+- `expect(shell).toHaveRun(command)` — the exact rendered command ran.
+- `expect(shell).toHaveRunMatching(pattern)` — some command matches (string = command prefix at a word boundary, same as `on`; RegExp = test); negate with `.not` for "never ran".
+- `expect(logs).toHaveLogged(line?)` / `toHaveWarned(line?)` / `toHaveErrored(line?)` — a captured line equals the string (or matches the RegExp); with no argument, that the channel captured anything, so `.not.toHaveWarned()` asserts silence.
+- `expect(items).toContainExactElementsInAnyOrder(expected)` — nested elements match regardless of order, including duplicate counts.
+- `expect(items).toContainNoDuplicates()` — no two elements are deeply equal.
+- `expect(items).toHaveNumberOfElements(count)` — the collection has exactly that many elements.
+
+## Polling
+
+`pollUntil(condition, { timeout, interval?, grace? })` waits for an asynchronous condition using Vitest's `expect.poll`. The condition receives an abort signal. A grace period requires a second matching observation after that delay. The return is `{ settled, error }`; deadlines also bound pending observations and grace periods.
+
+## Journal reporting
+
+Add the reporter alongside Vitest's normal terminal reporters:
+
+```ts
+import { JournaldReporter } from '@zyplux/spectra/journald-reporter';
+import { configDefaults, defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    reporters: [...configDefaults.reporters, new JournaldReporter({ identifier: 'my-repo' })],
+  },
+});
+```
+
+Named projects record summaries and failure details under `my-repo-<project>`; console messages use `my-repo-<project>-console`. Unnamed projects use `my-repo` and `my-repo-console`. Read them with `journalctl -t my-repo-<project>`. Recording is enabled when the systemd journal socket exists. The `isEnabled` option explicitly controls recording; connection errors are reported to the terminal.
+
+The optional `socketPath` selects a journal stream socket; its default is `/run/systemd/journal/stdout`.

package/dist/fakes/fetch-fake.d.ts

@@ -0,0 +1,10 @@
+export type FetchFake = {
+    install: () => () => void;
+    on: (match: RegExp | string, reply: FetchReply) => void;
+    otherwise: (reply: FetchReply) => void;
+    requests: string[];
+};
+export type FetchReply = (url: string) => Promise<Response> | Response;
+export declare const notFoundResponse: () => Response;
+export declare const okResponse: () => Response;
+export declare const createFetchFake: () => FetchFake;

package/dist/fakes/fetch-fake.js

@@ -0,0 +1,40 @@
+import { vi } from 'vitest';
+const HTTP_NOT_FOUND = 404;
+const HTTP_OK = 200;
+export const notFoundResponse = () => new Response(undefined, { status: HTTP_NOT_FOUND });
+export const okResponse = () => new Response(undefined, { status: HTTP_OK });
+const isUrlMatch = (url, match) => typeof match === 'string' ? url.startsWith(match) : match.test(url);
+const getRequestUrl = (input) => {
+    if (typeof input === 'string')
+        return input;
+    return input instanceof URL ? input.href : input.url;
+};
+export const createFetchFake = () => {
+    const requests = [];
+    const routes = [];
+    let fallback = notFoundResponse;
+    const respond = (url) => {
+        const reply = routes.findLast(candidate => isUrlMatch(url, candidate.match))?.reply ?? fallback;
+        return reply(url);
+    };
+    const fakeFetch = async (input) => {
+        const url = getRequestUrl(input);
+        requests.push(url);
+        return respond(url);
+    };
+    return {
+        install: () => {
+            vi.stubGlobal('fetch', fakeFetch);
+            return () => {
+                vi.unstubAllGlobals();
+            };
+        },
+        on: (match, reply) => {
+            routes.push({ match, reply });
+        },
+        otherwise: reply => {
+            fallback = reply;
+        },
+        requests,
+    };
+};

package/dist/fakes/prompt-fake.d.ts

@@ -0,0 +1,5 @@
+export type PromptFake = {
+    install: () => () => void;
+    messages: string[];
+};
+export declare const createPromptFake: () => PromptFake;

package/dist/fakes/prompt-fake.js

@@ -0,0 +1,29 @@
+import { createInterface, Interface } from 'node:readline/promises';
+import { PassThrough } from 'node:stream';
+import { vi } from 'vitest';
+import { requireMockedModule } from '#require-mocked-module';
+class PromptProbe extends Interface {
+    messages;
+    constructor(messages) {
+        super({ input: new PassThrough() });
+        this.messages = messages;
+    }
+    question(message) {
+        this.messages.push(message);
+        return Promise.resolve('');
+    }
+}
+export const createPromptFake = () => {
+    const messages = [];
+    const createInterfaceMock = vi.mocked(createInterface);
+    return {
+        install: () => {
+            requireMockedModule(createInterface, 'node:readline/promises', 'createInterface');
+            createInterfaceMock.mockImplementation(() => new PromptProbe(messages));
+            return () => {
+                createInterfaceMock.mockReset();
+            };
+        },
+        messages,
+    };
+};

package/dist/fakes/shell-fake.d.ts

@@ -0,0 +1,20 @@
+export type ShellCall = {
+    argv: string[];
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    program: string;
+    stdin?: string;
+};
+export type ShellFake = {
+    calls: ShellCall[];
+    commands: string[];
+    commandsMatching: (pattern: RegExp | string) => string[];
+    install: () => () => void;
+    on: (pattern: RegExp | string, ...replies: [ShellReply, ...ShellReply[]]) => void;
+    otherwise: (...replies: [ShellReply, ...ShellReply[]]) => void;
+};
+export type ShellReply = ((command: string) => string) | string | {
+    exitCode: number;
+    stdout: string;
+};
+export declare const createShellFake: () => ShellFake;

package/dist/fakes/shell-fake.js

@@ -0,0 +1,112 @@
+import { ChildProcess, spawn } from 'node:child_process';
+import { PassThrough, Writable } from 'node:stream';
+import { vi } from 'vitest';
+import { isPatternMatch } from '#pattern-match';
+import { requireMockedModule } from '#require-mocked-module';
+const isCommandMatch = (command, pattern) => typeof pattern === 'string'
+    ? command.startsWith(pattern) && (command.length === pattern.length || command[pattern.length] === ' ')
+    : isPatternMatch(command, pattern);
+const takeReply = ({ replies }) => {
+    const reply = replies.length > 1 ? replies.shift() : replies[0];
+    if (reply === undefined)
+        throw new Error('shell route has no replies left');
+    return reply;
+};
+const envOverlay = (env = {}) => {
+    const overlaid = Object.entries(env).filter(([name, value]) => !Object.hasOwn(process.env, name) || process.env[name] !== value);
+    return overlaid.length === 0 ? undefined : Object.fromEntries(overlaid);
+};
+const createFakeChild = ({ exitCode, stdout: output }, onStdin) => {
+    const stdout = new PassThrough();
+    const stderr = new PassThrough();
+    const written = [];
+    const stdin = new Writable({
+        final: done => {
+            onStdin(Buffer.concat(written).toString());
+            done();
+        },
+        write: (chunk, _encoding, done) => {
+            written.push(Buffer.from(chunk));
+            done();
+        },
+    });
+    const child = Object.assign(new ChildProcess(), { stderr, stdin, stdout });
+    let flowing = 2;
+    const closeWhenDrained = () => {
+        flowing -= 1;
+        if (flowing === 0)
+            child.emit('close', exitCode);
+    };
+    stdout.on('end', closeWhenDrained);
+    stderr.on('end', closeWhenDrained);
+    queueMicrotask(() => {
+        stdout.end(output);
+        stderr.end();
+        stdout.resume();
+        stderr.resume();
+    });
+    return child;
+};
+const silenceStandardStreams = () => {
+    const silenced = [
+        vi.spyOn(process.stdout, 'write').mockReturnValue(true),
+        vi.spyOn(process.stderr, 'write').mockReturnValue(true),
+    ];
+    return () => {
+        for (const stream of silenced)
+            stream.mockRestore();
+    };
+};
+export const createShellFake = () => {
+    const calls = [];
+    const commands = [];
+    const routes = [];
+    let fallback;
+    const resolveReply = (command) => {
+        const route = routes.findLast(candidate => isCommandMatch(command, candidate.pattern)) ?? fallback;
+        if (route === undefined) {
+            const registered = routes.map(known => `  ${String(known.pattern)}`).join('\n');
+            throw new Error(`no shell route matches: ${command}\nregistered routes:\n${registered}`);
+        }
+        const reply = takeReply(route);
+        const resolved = typeof reply === 'function' ? reply(command) : reply;
+        return typeof resolved === 'string' ? { exitCode: 0, stdout: resolved } : resolved;
+    };
+    const spawnFake = (program, args = [], options = {}) => {
+        const argv = [...args];
+        const command = [program, ...argv].join(' ');
+        const overlay = envOverlay(options.env);
+        const call = {
+            argv,
+            program,
+            ...(typeof options.cwd === 'string' && { cwd: options.cwd }),
+            ...(overlay !== undefined && { env: overlay }),
+        };
+        calls.push(call);
+        commands.push(command);
+        return createFakeChild(resolveReply(command), text => {
+            call.stdin = text;
+        });
+    };
+    return {
+        calls,
+        commands,
+        commandsMatching: pattern => commands.filter(command => isCommandMatch(command, pattern)),
+        install: () => {
+            requireMockedModule(spawn, 'node:child_process', 'spawn');
+            const spawnMock = vi.mocked(spawn);
+            spawnMock.mockImplementation(spawnFake);
+            const restoreStreams = silenceStandardStreams();
+            return () => {
+                restoreStreams();
+                spawnMock.mockReset();
+            };
+        },
+        on: (pattern, ...replies) => {
+            routes.push({ pattern, replies: [...replies] });
+        },
+        otherwise: (...replies) => {
+            fallback = { pattern: '', replies: [...replies] };
+        },
+    };
+};

package/dist/helpers/cli-runner.d.ts

@@ -0,0 +1,14 @@
+export type CliIo = {
+    onExit: (exitCode: number) => never;
+    stderr: (line: string) => void;
+    stdout: (line: string) => void;
+};
+export type CliMain = (args: readonly string[], io: CliIo) => Promise<void>;
+export type CliRunner = {
+    run: (...args: string[]) => Promise<void>;
+};
+export declare class CliExitError extends Error {
+    readonly exitCode: number;
+    constructor(exitCode: number);
+}
+export declare const createCliRunner: (main: CliMain) => CliRunner;

package/dist/helpers/cli-runner.js

@@ -0,0 +1,21 @@
+export class CliExitError extends Error {
+    exitCode;
+    constructor(exitCode) {
+        super(`cli exited with code ${exitCode}`);
+        this.name = 'CliExitError';
+        this.exitCode = exitCode;
+    }
+}
+export const createCliRunner = (main) => ({
+    run: (...args) => main(args, {
+        onExit: exitCode => {
+            throw new CliExitError(exitCode);
+        },
+        stderr: line => {
+            console.error(line);
+        },
+        stdout: line => {
+            console.log(line);
+        },
+    }),
+});

package/dist/helpers/pattern-match.d.ts

@@ -0,0 +1 @@
+export declare const isPatternMatch: (input: string, pattern: RegExp) => boolean;

package/dist/helpers/pattern-match.js

@@ -0,0 +1,4 @@
+export const isPatternMatch = (input, pattern) => {
+    pattern.lastIndex = 0;
+    return pattern.test(input);
+};

package/dist/helpers/poll-until.d.ts

@@ -0,0 +1,11 @@
+type PollCondition = (signal: AbortSignal) => boolean | Promise<boolean>;
+type PollOptions = {
+    grace?: number;
+    interval?: number;
+    timeout: number;
+};
+export declare const pollUntil: (isSettled: PollCondition, { grace, interval, timeout }: PollOptions) => Promise<{
+    error: unknown;
+    settled: boolean;
+}>;
+export {};

package/dist/helpers/poll-until.js

@@ -0,0 +1,20 @@
+import { setTimeout } from 'node:timers/promises';
+import { expect } from 'vitest';
+export const pollUntil = async (isSettled, { grace, interval, timeout }) => {
+    try {
+        await expect
+            .poll(async ({ signal }) => {
+            if (!(await isSettled(signal)))
+                return false;
+            if (grace === undefined)
+                return true;
+            await setTimeout(grace, undefined, { signal });
+            return isSettled(signal);
+        }, { ...(interval !== undefined && { interval }), timeout })
+            .toBe(true);
+        return { error: undefined, settled: true };
+    }
+    catch (error) {
+        return { error, settled: false };
+    }
+};

package/dist/helpers/require-mocked-module.d.ts

@@ -0,0 +1 @@
+export declare const requireMockedModule: (subject: unknown, moduleId: string, replaced: string) => void;

package/dist/helpers/require-mocked-module.js

@@ -0,0 +1,6 @@
+import { vi } from 'vitest';
+export const requireMockedModule = (subject, moduleId, replaced) => {
+    if (vi.isMockFunction(subject))
+        return;
+    throw new Error(`${moduleId} is not mocked — this project's vitest setupFiles must vi.mock('${moduleId}', …) with ${replaced} wrapped in vi.fn (see @zyplux/spectra README)`);
+};

package/dist/helpers/temp-directory.d.ts

@@ -0,0 +1,7 @@
+export type TempDir = {
+    exists: (relativePath: string) => boolean;
+    path: string;
+    remove: () => Promise<void>;
+    write: (relativePath: string, content: string) => Promise<string>;
+};
+export declare const createTempDir: (prefix?: string) => Promise<TempDir>;

package/dist/helpers/temp-directory.js

@@ -0,0 +1,18 @@
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+export const createTempDir = async (prefix = 'zyplux-test-') => {
+    const dir = await mkdtemp(path.join(tmpdir(), prefix));
+    return {
+        exists: relativePath => existsSync(path.join(dir, relativePath)),
+        path: dir,
+        remove: () => rm(dir, { force: true, recursive: true }),
+        write: async (relativePath, content) => {
+            const filePath = path.join(dir, relativePath);
+            await mkdir(path.dirname(filePath), { recursive: true });
+            await writeFile(filePath, content, 'utf8');
+            return filePath;
+        },
+    };
+};

package/dist/library-test-api.d.ts

@@ -0,0 +1,34 @@
+import type { FetchFake } from './fakes/fetch-fake.ts';
+import type { PromptFake } from './fakes/prompt-fake.ts';
+import type { ShellFake } from './fakes/shell-fake.ts';
+import type { TempDir } from './helpers/temp-directory.ts';
+import './test-matchers.ts';
+import type { ConsoleCapture } from './reporters/console-capture.ts';
+export type EnvStub = {
+    set: (name: string, value: string) => void;
+};
+export declare const makeFixture: <Subject>(subject: Subject) => ({}: object, use: (subject: Subject) => Promise<void>) => Promise<void>;
+export type LibraryFixtures = {
+    shell: ShellFake;
+    tempDir: TempDir;
+};
+export declare const libraryTest: import("vitest").TestAPI<{
+    shell: ShellFake;
+    tempDir: TempDir;
+}>;
+export type CliFixtures = {
+    env: EnvStub;
+    instantSleep: undefined;
+    logs: ConsoleCapture;
+    network: FetchFake;
+    prompt: PromptFake;
+};
+export declare const cliTest: import("vitest").TestAPI<{
+    prompt: PromptFake;
+    shell: ShellFake;
+    tempDir: TempDir;
+    env: EnvStub;
+    instantSleep: undefined;
+    logs: ConsoleCapture;
+    network: FetchFake;
+}>;

package/dist/library-test-api.js

@@ -0,0 +1,96 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { test as base, vi } from 'vitest';
+import { requireMockedModule } from '#require-mocked-module';
+import "./test-matchers.js";
+import { createFetchFake } from "./fakes/fetch-fake.js";
+import { createPromptFake } from "./fakes/prompt-fake.js";
+import { createShellFake } from "./fakes/shell-fake.js";
+import { createTempDir } from "./helpers/temp-directory.js";
+import { createConsoleCapture } from "./reporters/console-capture.js";
+export const makeFixture = (subject) => async ({}, use) => {
+    await use(subject);
+};
+export const libraryTest = base.extend({
+    shell: async ({}, use) => {
+        const shell = createShellFake();
+        const restore = shell.install();
+        try {
+            await use(shell);
+        }
+        finally {
+            restore();
+        }
+    },
+    tempDir: async ({}, use) => {
+        const tempDir = await createTempDir();
+        try {
+            await use(tempDir);
+        }
+        finally {
+            await tempDir.remove();
+        }
+    },
+});
+export const cliTest = libraryTest.extend({
+    env: async ({}, use) => {
+        try {
+            await use({
+                set: (name, value) => {
+                    vi.stubEnv(name, value);
+                },
+            });
+        }
+        finally {
+            vi.unstubAllEnvs();
+        }
+    },
+    instantSleep: [
+        async ({}, use) => {
+            requireMockedModule(sleep, 'node:timers/promises', 'setTimeout');
+            vi.mocked(sleep).mockResolvedValue(undefined);
+            try {
+                await use(undefined);
+            }
+            finally {
+                vi.mocked(sleep).mockReset();
+            }
+        },
+        { auto: true },
+    ],
+    logs: [
+        async ({}, use) => {
+            const logs = createConsoleCapture();
+            const restore = logs.install();
+            try {
+                await use(logs);
+            }
+            finally {
+                restore();
+            }
+        },
+        { auto: true },
+    ],
+    network: [
+        async ({}, use) => {
+            const network = createFetchFake();
+            const restore = network.install();
+            try {
+                await use(network);
+            }
+            finally {
+                restore();
+            }
+        },
+        { auto: true },
+    ],
+    prompt: async ({}, use) => {
+        const prompt = createPromptFake();
+        const restore = prompt.install();
+        try {
+            await use(prompt);
+        }
+        finally {
+            restore();
+        }
+    },
+});

package/dist/reporters/console-capture.d.ts

@@ -0,0 +1,7 @@
+export type ConsoleCapture = {
+    errorLines: string[];
+    install: () => () => void;
+    logLines: string[];
+    warnLines: string[];
+};
+export declare const createConsoleCapture: () => ConsoleCapture;

package/dist/reporters/console-capture.js

@@ -0,0 +1,28 @@
+const renderLine = (parts) => parts.map(String).join(' ');
+export const createConsoleCapture = () => {
+    const errorLines = [];
+    const logLines = [];
+    const warnLines = [];
+    return {
+        errorLines,
+        install: () => {
+            const original = { error: console.error, log: console.log, warn: console.warn };
+            console.error = (...parts) => {
+                errorLines.push(renderLine(parts));
+            };
+            console.log = (...parts) => {
+                logLines.push(renderLine(parts));
+            };
+            console.warn = (...parts) => {
+                warnLines.push(renderLine(parts));
+            };
+            return () => {
+                console.error = original.error;
+                console.log = original.log;
+                console.warn = original.warn;
+            };
+        },
+        logLines,
+        warnLines,
+    };
+};

package/dist/reporters/journal-writer.d.ts

@@ -0,0 +1,4 @@
+export declare const openJournalWriter: (identifier: string, socketPath: string) => {
+    close: () => Promise<void>;
+    write: (lines: readonly string[]) => void;
+};

package/dist/reporters/journal-writer.js

@@ -0,0 +1,27 @@
+import { createConnection } from 'node:net';
+export const openJournalWriter = (identifier, socketPath) => {
+    const writer = createConnection(socketPath);
+    let failure;
+    const closed = new Promise(resolve => {
+        writer.on('error', error => {
+            failure ??= error;
+        });
+        writer.on('close', () => {
+            resolve();
+        });
+    });
+    // sd_journal_stream_fd header: identifier, unit, priority, level prefixes, and three forwarding flags.
+    writer.write(`${identifier}\n\n6\n1\n0\n0\n0\n`);
+    return {
+        close: async () => {
+            writer.end();
+            await closed;
+            if (failure)
+                console.error(`recording ${identifier} to the journal failed`, failure);
+        },
+        write: (lines) => {
+            if (lines.length > 0 && !writer.destroyed)
+                writer.write(`${lines.join('\n')}\n`);
+        },
+    };
+};

package/dist/reporters/journald-reporter.d.ts

@@ -0,0 +1,16 @@
+import type { UserConsoleLog } from 'vitest';
+import type { Reporter, SerializedError, TestModule, TestRunEndReason, Vitest } from 'vitest/node';
+type JournaldReporterOptions = {
+    identifier?: string;
+    isEnabled?: boolean;
+    socketPath?: string;
+};
+export declare class JournaldReporter implements Reporter {
+    #private;
+    constructor({ identifier, socketPath, isEnabled, }?: JournaldReporterOptions);
+    onInit(context: Vitest): void;
+    onTestRunEnd(modules: readonly TestModule[], errors: readonly SerializedError[], reason: TestRunEndReason): Promise<void>;
+    onTestRunStart(): void;
+    onUserConsoleLog({ content, taskId, type }: UserConsoleLog): void;
+}
+export {};

package/dist/reporters/journald-reporter.js

@@ -0,0 +1,91 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+const INFO_PREFIX = '<6>';
+const WARNING_PREFIX = '<4>';
+const ERROR_PREFIX = '<3>';
+import { openJournalWriter } from "./journal-writer.js";
+const formatErrors = (errors) => errors.flatMap(error => {
+    const stack = error.stack ?? '';
+    const message = error.message;
+    const text = stack.includes(message) ? stack : `${message}\n${stack}`;
+    return text
+        .trimEnd()
+        .split('\n')
+        .map(line => `${ERROR_PREFIX}  ${line}`);
+});
+const formatFailures = (module) => {
+    const modulePath = path.relative(process.cwd(), module.moduleId);
+    return [
+        ...[module, ...module.children.allSuites()].flatMap(suite => suite.errors().length === 0
+            ? []
+            : [
+                `${ERROR_PREFIX}FAIL ${modulePath}${suite.type === 'module' ? '' : ` > ${suite.fullName}`}`,
+                ...formatErrors(suite.errors()),
+            ]),
+        ...[...module.children.allTests('failed')].flatMap(test => [
+            `${ERROR_PREFIX}FAIL ${modulePath} > ${test.fullName}`,
+            ...formatErrors(test.result().errors ?? []),
+        ]),
+    ];
+};
+export class JournaldReporter {
+    #context;
+    #identifier;
+    #isEnabled;
+    #socketPath;
+    #startedAt = '';
+    #writers = new Map();
+    constructor({ identifier = 'spectra', socketPath = '/run/systemd/journal/stdout', isEnabled = existsSync(socketPath), } = {}) {
+        this.#identifier = identifier;
+        this.#isEnabled = isEnabled;
+        this.#socketPath = socketPath;
+    }
+    onInit(context) {
+        this.#context = context;
+    }
+    async onTestRunEnd(modules, errors, reason) {
+        const projects = Map.groupBy(modules, module => module.project.name);
+        for (const [project, projectModules] of projects) {
+            const tests = projectModules.flatMap(module => [...module.children.allTests()]);
+            const passed = tests.filter(test => test.result().state === 'passed').length;
+            const failed = tests.filter(test => test.result().state === 'failed').length;
+            const pending = tests.length - passed - failed;
+            const hasFailed = projectModules.some(module => !module.ok()) || errors.length > 0 || reason === 'interrupted';
+            this.#write(project ? `${this.#identifier}-${project}` : this.#identifier, [
+                `${INFO_PREFIX}run start ${this.#startedAt}`,
+                ...projectModules.flatMap(module => formatFailures(module)),
+                `${hasFailed ? ERROR_PREFIX : INFO_PREFIX}${hasFailed ? 'FAIL' : 'pass'} — ${tests.length} tests: ${passed} passed, ${failed} failed, ${pending} pending`,
+            ]);
+        }
+        if (errors.length > 0)
+            this.#write(this.#identifier, formatErrors(errors));
+        for (const writer of this.#writers.values())
+            await writer.close();
+        this.#writers.clear();
+    }
+    onTestRunStart() {
+        this.#startedAt = new Date().toISOString();
+    }
+    onUserConsoleLog({ content, taskId, type }) {
+        const trimmed = content.trimEnd();
+        if (!trimmed)
+            return;
+        const entity = taskId ? this.#context?.state.getReportedEntityById(taskId) : undefined;
+        const module = entity?.type === 'module' ? entity : entity?.module;
+        const identifier = module?.project.name ? `${this.#identifier}-${module.project.name}` : this.#identifier;
+        const modulePath = module ? path.relative(process.cwd(), module.moduleId) : '<no test>';
+        const source = entity && entity.type !== 'module' ? `${modulePath} > ${entity.fullName}` : modulePath;
+        const prefix = type === 'stdout' ? INFO_PREFIX : WARNING_PREFIX;
+        this.#write(`${identifier}-console`, trimmed.split('\n').map(line => `${prefix}${source} ${line}`));
+    }
+    #write(identifier, lines) {
+        if (!this.#isEnabled)
+            return;
+        let writer = this.#writers.get(identifier);
+        if (!writer) {
+            writer = openJournalWriter(identifier, this.#socketPath);
+            this.#writers.set(identifier, writer);
+        }
+        writer.write(lines);
+    }
+}

package/dist/test-matchers.d.ts

@@ -0,0 +1,51 @@
+import { expect } from 'vitest';
+import type { ShellFake } from './fakes/shell-fake.ts';
+import type { ConsoleCapture } from './reporters/console-capture.ts';
+export type LineMatch = RegExp | string;
+export declare const registerMatchers: <Registered extends Parameters<typeof expect.extend>[0]>(matchers: Registered) => Registered;
+export declare const testMatchers: {
+    toContainExactElementsInAnyOrder: (received: readonly unknown[], expected: readonly unknown[]) => {
+        message: () => string;
+        pass: boolean;
+    };
+    toContainNoDuplicates: (received: readonly unknown[]) => {
+        message: () => string;
+        pass: boolean;
+    };
+    toHaveErrored: ({ errorLines }: ConsoleCapture, line?: LineMatch) => {
+        message: () => string;
+        pass: boolean;
+    };
+    toHaveLogged: ({ logLines }: ConsoleCapture, line?: LineMatch) => {
+        message: () => string;
+        pass: boolean;
+    };
+    toHaveNumberOfElements: (received: readonly unknown[], expected: number) => {
+        message: () => string;
+        pass: boolean;
+    };
+    toHaveRun: ({ commands }: ShellFake, command: string) => {
+        message: () => string;
+        pass: boolean;
+    };
+    toHaveRunMatching: (shell: ShellFake, pattern: RegExp | string) => {
+        message: () => string;
+        pass: boolean;
+    };
+    toHaveWarned: ({ warnLines }: ConsoleCapture, line?: LineMatch) => {
+        message: () => string;
+        pass: boolean;
+    };
+};
+declare module 'vitest' {
+    interface Matchers<R, T> {
+        toContainExactElementsInAnyOrder: (expected: readonly unknown[]) => R;
+        toContainNoDuplicates: () => R;
+        toHaveErrored: (line?: LineMatch) => R;
+        toHaveLogged: (line?: LineMatch) => R;
+        toHaveNumberOfElements: T extends readonly unknown[] ? (expected: number) => R : never;
+        toHaveRun: (command: string) => R;
+        toHaveRunMatching: (pattern: RegExp | string) => R;
+        toHaveWarned: (line?: LineMatch) => R;
+    }
+}

package/dist/test-matchers.js

@@ -0,0 +1,62 @@
+import { isDeepStrictEqual } from 'node:util';
+import { expect } from 'vitest';
+import { isPatternMatch } from '#pattern-match';
+export const registerMatchers = (matchers) => {
+    expect.extend(matchers);
+    return matchers;
+};
+const isLineMatch = (line, expected) => typeof expected === 'string' ? line === expected : isPatternMatch(line, expected);
+const renderLines = (label, lines) => lines.length === 0 ? `${label}: (none)` : `${label}:\n${lines.map(line => `  ${line}`).join('\n')}`;
+const lineListResult = (lines, label, expected) => {
+    const isPass = expected === undefined ? lines.length > 0 : lines.some(line => isLineMatch(line, expected));
+    const observation = expected === undefined
+        ? `${label} were ${isPass ? 'captured' : 'empty'}`
+        : `${label} ${isPass ? 'include' : 'do not include'} ${String(expected)}`;
+    return { message: () => `${observation}\n${renderLines(label, lines)}`, pass: isPass };
+};
+const unmatchedElements = (received, expected) => {
+    const remaining = [...expected];
+    return received.filter(item => {
+        const index = remaining.findIndex(candidate => isDeepStrictEqual(candidate, item));
+        if (index === -1)
+            return true;
+        remaining.splice(index, 1);
+        return false;
+    });
+};
+export const testMatchers = registerMatchers({
+    toContainExactElementsInAnyOrder: (received, expected) => {
+        const extra = unmatchedElements(received, expected);
+        const missing = unmatchedElements(expected, received);
+        return {
+            message: () => `expected [${received.join(', ')}] to contain exactly [${expected.join(', ')}] in any order\n` +
+                `${renderLines('missing', missing.map(String))}\n${renderLines('extra', extra.map(String))}`,
+            pass: extra.length === 0 && missing.length === 0,
+        };
+    },
+    toContainNoDuplicates: (received) => {
+        const duplicates = received.filter((item, index) => received.findIndex(candidate => isDeepStrictEqual(candidate, item)) !== index);
+        return {
+            message: () => `expected [${received.join(', ')}] to contain no duplicates\n${renderLines('duplicates', duplicates.map(String))}`,
+            pass: duplicates.length === 0,
+        };
+    },
+    toHaveErrored: ({ errorLines }, line) => lineListResult(errorLines, 'console.error lines', line),
+    toHaveLogged: ({ logLines }, line) => lineListResult(logLines, 'console.log lines', line),
+    toHaveNumberOfElements: (received, expected) => ({
+        message: () => `expected [${received.join(', ')}] (${received.length} elements) to have ${expected} elements`,
+        pass: received.length === expected,
+    }),
+    toHaveRun: ({ commands }, command) => ({
+        message: () => `the shell ${commands.includes(command) ? 'ran' : 'never ran'} ${command}\n${renderLines('commands', commands)}`,
+        pass: commands.includes(command),
+    }),
+    toHaveRunMatching: (shell, pattern) => {
+        const matched = shell.commandsMatching(pattern);
+        return {
+            message: () => `${matched.length} shell commands matched ${String(pattern)}\n${renderLines('commands', shell.commands)}`,
+            pass: matched.length > 0,
+        };
+    },
+    toHaveWarned: ({ warnLines }, line) => lineListResult(warnLines, 'console.warn lines', line),
+});

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@zyplux/spectra",
+  "version": "0.3.0",
+  "description": "Shared Vitest fixtures, matchers, polling, and journal reporting.",
+  "keywords": [
+    "test",
+    "fixtures",
+    "mock",
+    "shell",
+    "vitest"
+  ],
+  "license": "MIT",
+  "author": "Sergiy Yeskov <sergiy.yeskov@gmail.com>",
+  "homepage": "https://github.com/zyplux/zyplux",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zyplux/zyplux.git",
+    "directory": "packages/spectra"
+  },
+  "type": "module",
+  "exports": {
+    "./fetch-fake": {
+      "types": "./dist/fakes/fetch-fake.d.ts",
+      "default": "./dist/fakes/fetch-fake.js"
+    },
+    "./prompt-fake": {
+      "types": "./dist/fakes/prompt-fake.d.ts",
+      "default": "./dist/fakes/prompt-fake.js"
+    },
+    "./shell-fake": {
+      "types": "./dist/fakes/shell-fake.d.ts",
+      "default": "./dist/fakes/shell-fake.js"
+    },
+    "./cli-runner": {
+      "types": "./dist/helpers/cli-runner.d.ts",
+      "default": "./dist/helpers/cli-runner.js"
+    },
+    "./poll-until": {
+      "types": "./dist/helpers/poll-until.d.ts",
+      "default": "./dist/helpers/poll-until.js"
+    },
+    "./temp-directory": {
+      "types": "./dist/helpers/temp-directory.d.ts",
+      "default": "./dist/helpers/temp-directory.js"
+    },
+    "./library-test-api": {
+      "types": "./dist/library-test-api.d.ts",
+      "default": "./dist/library-test-api.js"
+    },
+    "./console-capture": {
+      "types": "./dist/reporters/console-capture.d.ts",
+      "default": "./dist/reporters/console-capture.js"
+    },
+    "./test-matchers": {
+      "types": "./dist/test-matchers.d.ts",
+      "default": "./dist/test-matchers.js"
+    },
+    "./journald-reporter": {
+      "types": "./dist/reporters/journald-reporter.d.ts",
+      "default": "./dist/reporters/journald-reporter.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "vitest": "^5.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "@zyplux/tsconfig": "0.3.1",
+    "publint": "^0.3.25",
+    "vitest": "^5.0.3"
+  },
+  "imports": {
+    "#pattern-match": "./dist/helpers/pattern-match.js",
+    "#require-mocked-module": "./dist/helpers/require-mocked-module.js"
+  },
+  "sideEffects": [
+    "./dist/library-test-api.js",
+    "./dist/test-matchers.js"
+  ],
+  "scripts": {}
+}