playwright-logbook 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KRISHNAPOLLU
+
+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,134 @@
+# Playwright Logbook
+
+## A better local report for Playwright
+
+Playwright Logbook turns every test run into a searchable, self-contained report with failure details, retry history, flaky-test tracking, project views, and CI-friendly summaries.
+
+It works with the Playwright setup you already have. There is no hosted service, database, or account to configure.
+
+![Playwright Logbook dark report](docs/img/report-dark.png)
+
+## Why teams use it
+
+- Find the failed test, its attempts, error, code frame, steps, and artifacts in one place.
+- See flaky tests and recent run history instead of investigating one run at a time.
+- Review results across projects and CI shards in a single HTML report.
+- Get copyable rerun commands and bounded, redacted debug context for AI-assisted investigation.
+- Keep reports local and offline. Logbook does not change Playwright's exit code or send data anywhere.
+
+![Playwright Logbook light report](docs/img/report-light.png)
+
+## Install
+
+```sh
+npm install --save-dev playwright-logbook
+```
+
+Logbook supports Node.js 20+ and Playwright 1.42+.
+
+## Add it to Playwright
+
+Add Logbook to your existing reporter list:
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  reporter: [['list'], ['playwright-logbook']],
+});
+```
+
+Run Playwright normally:
+
+```sh
+npx playwright test
+```
+
+Then open `.logbook/report/index.html`. The report is a single local HTML file and works without a server.
+
+## Use it in CI
+
+Each shard writes its own record. Give all shards the same run ID and upload their shard files as CI artifacts:
+
+```sh
+LOGBOOK_RUN_ID=ci-123 npx playwright test --shard=1/4
+```
+
+In a follow-up job, download the shard artifacts and merge them:
+
+```sh
+npx playwright-logbook merge \
+  --run-id ci-123 \
+  --from all-shards \
+  --fail-on-incomplete
+
+npx playwright-logbook summary --run ci-123 --format markdown
+```
+
+The merge creates `.logbook/report/index.html` and updates local history. Persist `.logbook/runs/` and `.logbook/index.jsonl` between CI runs to keep trends and flaky-test history.
+
+See [CI recipes](docs/CI.md) for GitHub Actions, Azure DevOps, artifact retention, and Playwright blob-report workflows.
+
+## Review runs from the terminal
+
+```sh
+npx playwright-logbook history
+npx playwright-logbook flaky
+npx playwright-logbook summary --format markdown
+npx playwright-logbook report --run latest
+npx playwright-logbook debug --run latest --test <testId> --format markdown
+```
+
+Use `--root <dir>` when running the CLI outside your Playwright project. See the [CLI reference](docs/CLI.md) for all commands and exit codes.
+
+## Reporter options
+
+```ts
+reporter: [['playwright-logbook', {
+  outputDir: '.logbook',
+  historyLimit: 30,
+  captureDetails: true,
+}]],
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `outputDir` | `.logbook` | Output directory, relative to the project root |
+| `runId` | Detected | Explicit run ID; `LOGBOOK_RUN_ID` can also set it |
+| `title` | None | Label shown in the report |
+| `redact` | `[]` | Strings or regular expressions to remove from diagnostics |
+| `autoMerge` | `true` | Merge automatically when the run is not sharded |
+| `autoReport` | `true` | Generate HTML after an automatic merge |
+| `historyLimit` | `30` | Number of runs used for trends and flaky analysis |
+| `maxTextLength` | `4000` | Maximum stored diagnostic text length |
+| `quiet` | `false` | Suppress the final Logbook terminal line |
+| `captureDetails` | `false` | Capture steps, output, and failed-test screenshots |
+
+## Attachments and privacy
+
+Logbook stores outcomes, attempts, errors, tags, case IDs, project metadata, and relative artifact references. It does not copy trace, video, or screenshot files into run records.
+
+Configure traces in Playwright, for example:
+
+```ts
+use: { trace: 'on-first-retry' }
+```
+
+If you enable `captureDetails`, Logbook can store sanitized steps, output tails, and bounded PNG/JPEG images from failed or flaky tests. Screenshots can contain sensitive information; text redaction cannot remove secrets visible in pixels. Review reports and debug packets before sharing them.
+
+## What happens to your data?
+
+Everything stays in your project under `.logbook/`. This release makes no network requests, has no hosted retention policy, and performs no automatic AI or test-management upload. Remove `.logbook/` when you no longer need the local history.
+
+## Documentation
+
+- [CLI reference](docs/CLI.md)
+- [CI recipes](docs/CI.md)
+- [Record schema](docs/SCHEMA.md)
+- [Adapter guidance](docs/ADAPTERS.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+MIT

package/dist/artifacts.d.ts

@@ -0,0 +1,7 @@
+import fs from 'node:fs/promises';
+import type { RunRecord } from './schema.js';
+export type ArtifactAvailability = Record<string, 'present' | 'missing' | 'unknown'>;
+type ArtifactFiles = Pick<typeof fs, 'realpath' | 'stat'>;
+/** Verify references without reading or copying opaque attachment bytes. */
+export declare function resolveArtifactAvailability(run: RunRecord, root: string, files?: ArtifactFiles): Promise<ArtifactAvailability>;
+export {};

package/dist/artifacts.js

@@ -0,0 +1,35 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+/** Verify references without reading or copying opaque attachment bytes. */
+export async function resolveArtifactAvailability(run, root, files = fs) {
+    const paths = [...new Set(run.tests.flatMap((test) => test.attempts.flatMap((attempt) => attempt.attachments.map((item) => item.path).filter((item) => item !== null))))].sort(compare);
+    const result = {};
+    let realRoot;
+    try {
+        realRoot = await files.realpath(root);
+    }
+    catch {
+        return Object.fromEntries(paths.map((file) => [file, 'unknown']));
+    }
+    for (const file of paths) {
+        if (path.posix.isAbsolute(file) || file.includes('\\') || file.split('/').includes('..') || file.includes(':')) {
+            result[file] = 'missing';
+            continue;
+        }
+        const target = path.resolve(root, file);
+        if (!target.startsWith(`${path.resolve(root)}${path.sep}`)) {
+            result[file] = 'missing';
+            continue;
+        }
+        try {
+            const realTarget = await files.realpath(target);
+            result[file] = realTarget.startsWith(`${realRoot}${path.sep}`) && (await files.stat(realTarget)).isFile() ? 'present' : 'missing';
+        }
+        catch (error) {
+            result[file] = typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT' ? 'missing' : 'unknown';
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAK7B,MAAM,OAAO,GAAG,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE7E,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,GAAc,EAAE,IAAY,EAAE,QAAuB,EAAE;IACvG,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CACnD,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAChC,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,KAAK,IAAI,CAAC,CAC7F,CACF,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAClB,MAAM,MAAM,GAAyB,EAAE,CAAC;IACxC,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QAAC,QAAQ,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAAC,CAAC;IAC9C,MAAM,CAAC;QAAC,OAAO,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAAC,CAAC;IAC5E,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/G,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;YACzB,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;YAAC,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;YAAC,SAAS;QAAC,CAAC;QACnG,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAChD,MAAM,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QACpI,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QACnI,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/caseids.d.ts

@@ -0,0 +1,12 @@
+export interface CaseAnnotation {
+    type: string;
+    description?: string | null;
+}
+export interface CaseIdInput {
+    tags?: string[];
+    annotations?: CaseAnnotation[];
+    title: string;
+}
+export declare const DEFAULT_CASE_ID_PATTERN = "\\b[A-Z][A-Z0-9]{1,9}-\\d+\\b";
+/** Extract sorted, unique test-management case identifiers from a test. */
+export declare function extractCaseIds(input: CaseIdInput, patterns?: string[]): string[];

package/dist/caseids.js

@@ -0,0 +1,24 @@
+export const DEFAULT_CASE_ID_PATTERN = '\\b[A-Z][A-Z0-9]{1,9}-\\d+\\b';
+/** Extract sorted, unique test-management case identifiers from a test. */
+export function extractCaseIds(input, patterns) {
+    const values = new Set();
+    const expressions = (patterns ?? [DEFAULT_CASE_ID_PATTERN]).map((source) => new RegExp(source, 'g'));
+    const collect = (source) => {
+        for (const expression of expressions) {
+            expression.lastIndex = 0;
+            for (const match of source.matchAll(expression))
+                values.add(match[0]);
+        }
+    };
+    for (const tag of input.tags ?? [])
+        if (tag.startsWith('@'))
+            collect(tag.slice(1));
+    const allowed = /^(testcase|test_case|case|jira|issue|xray|zephyr|tms)$/i;
+    for (const annotation of input.annotations ?? [])
+        if (allowed.test(annotation.type) && annotation.description)
+            collect(annotation.description);
+    for (const match of input.title.matchAll(/\[([^\]]+)\]/g))
+        collect(match[1] ?? '');
+    return [...values].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+}
+//# sourceMappingURL=caseids.js.map

package/dist/caseids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caseids.js","sourceRoot":"","sources":["../src/caseids.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,uBAAuB,GAAG,+BAA+B,CAAC;AAEvE,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAAC,KAAkB,EAAE,QAAmB;IACpE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,MAAM,WAAW,GAAG,CAAC,QAAQ,IAAI,CAAC,uBAAuB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IACrG,MAAM,OAAO,GAAG,CAAC,MAAc,EAAQ,EAAE;QACvC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;YACrC,UAAU,CAAC,SAAS,GAAG,CAAC,CAAC;YACzB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC;gBAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxE,CAAC;IACH,CAAC,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,IAAI,EAAE;QAAE,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACnF,MAAM,OAAO,GAAG,yDAAyD,CAAC;IAC1E,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,WAAW,IAAI,EAAE;QAAE,IAAI,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,WAAW;YAAE,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IAC/I,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC;QAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACnF,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC"}

package/dist/cli/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** Launch the CLI from both direct and npm bin invocations. */
+export declare function main(): Promise<void>;

package/dist/cli/bin.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from './program.js';
+/** Launch the CLI from both direct and npm bin invocations. */
+export async function main() { process.exitCode = await runCli(process.argv.slice(2)); }
+void main();
+//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,+DAA+D;AAC/D,MAAM,CAAC,KAAK,UAAU,IAAI,KAAoB,OAAO,CAAC,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvG,KAAK,IAAI,EAAE,CAAC"}

package/dist/cli/commands/debug.d.ts

@@ -0,0 +1,7 @@
+import type { CliContext } from '../format.js';
+export interface DebugOptions {
+    run?: string;
+    test: string;
+    format: 'json' | 'markdown';
+}
+export declare function debugCommand(context: CliContext, options: DebugOptions): Promise<number>;

package/dist/cli/commands/debug.js

@@ -0,0 +1,14 @@
+import { FileHistoryStore } from '../../store.js';
+import { buildDebugPacket, debugPacketMarkdown } from '../../debugpacket.js';
+import { LogbookError } from '../../errors.js';
+import { modelForRun } from '../format.js';
+export async function debugCommand(context, options) {
+    const run = await new FileHistoryStore(context.outputDir).loadRun(options.run ?? 'latest');
+    const model = await modelForRun(context, run, 30, true);
+    if (!run.tests.some((test) => test.testId === options.test))
+        throw new LogbookError('TEST_NOT_FOUND', `test ${options.test} not found in run ${run.runId}`);
+    const packet = buildDebugPacket(model.run, options.test, model.recent[options.test] ?? '', model.attachmentAvailability);
+    context.stdout(options.format === 'json' ? `${JSON.stringify(packet, null, 2)}\n` : debugPacketMarkdown(packet));
+    return 0;
+}
+//# sourceMappingURL=debug.js.map

package/dist/cli/commands/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../../src/cli/commands/debug.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAK3C,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAmB,EAAE,OAAqB;IAC3E,MAAM,GAAG,GAAG,MAAM,IAAI,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC,CAAC;IAC3F,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;IACxD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,gBAAgB,EAAE,QAAQ,OAAO,CAAC,IAAI,qBAAqB,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;IAC5J,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,KAAK,CAAC,sBAAsB,CAAC,CAAC;IACzH,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;IACjH,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/cli/commands/flaky.d.ts

@@ -0,0 +1,8 @@
+import type { CliContext } from '../format.js';
+export interface FlakyOptions {
+    last?: string;
+    minRuns?: string;
+    json?: boolean;
+}
+/** Show recurrent flaky tests over recent stored runs. */
+export declare function flakyCommand(context: CliContext, options: FlakyOptions): Promise<number>;

package/dist/cli/commands/flaky.js

@@ -0,0 +1,27 @@
+import { LogbookError } from '../../errors.js';
+import { computeFlaky } from '../../history.js';
+import { FileHistoryStore } from '../../store.js';
+import { positiveInteger } from '../format.js';
+/** Show recurrent flaky tests over recent stored runs. */
+export async function flakyCommand(context, options) {
+    const last = options.last ? positiveInteger(options.last, '--last') : 20;
+    const minRuns = options.minRuns ? positiveInteger(options.minRuns, '--min-runs') : 3;
+    const store = new FileHistoryStore(context.outputDir);
+    const summaries = await store.listSummaries({ limit: last });
+    if (!summaries.length)
+        throw new LogbookError('NO_DATA', 'no runs found');
+    const entries = computeFlaky(await store.loadRuns(summaries.map((item) => item.runId).reverse()), { minRuns });
+    if (options.json) {
+        context.stdout(`${JSON.stringify(entries, null, 2)}\n`);
+        return 0;
+    }
+    if (!entries.length) {
+        context.stdout(`logbook: no flaky tests in the last ${last} runs\n`);
+        return 0;
+    }
+    context.stdout('SCORE  RUNS  FLAKY  FAILS  TEST\n');
+    for (const item of entries)
+        context.stdout(`${item.score.toFixed(2).padEnd(5)}  ${String(item.runs).padStart(4)}  ${String(item.flakyRuns).padStart(5)}  ${String(item.fails).padStart(5)}  ${item.file} › ${item.title} [${item.project}]\n`);
+    return 0;
+}
+//# sourceMappingURL=flaky.js.map

package/dist/cli/commands/flaky.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flaky.js","sourceRoot":"","sources":["../../../src/cli/commands/flaky.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAI/C,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAmB,EAAE,OAAqB;IAC3E,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrF,MAAM,KAAK,GAAG,IAAI,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,IAAI,CAAC,SAAS,CAAC,MAAM;QAAE,MAAM,IAAI,YAAY,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;IAC1E,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/G,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QAAC,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAAC,OAAO,CAAC,CAAC;IAAC,CAAC;IACxF,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QAAC,OAAO,CAAC,MAAM,CAAC,uCAAuC,IAAI,SAAS,CAAC,CAAC;QAAC,OAAO,CAAC,CAAC;IAAC,CAAC;IACxG,OAAO,CAAC,MAAM,CAAC,mCAAmC,CAAC,CAAC;IACpD,KAAK,MAAM,IAAI,IAAI,OAAO;QAAE,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,OAAO,KAAK,CAAC,CAAC;IAC/O,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/cli/commands/history.d.ts

@@ -0,0 +1,8 @@
+import type { CliContext } from '../format.js';
+export interface HistoryOptions {
+    limit?: string;
+    branch?: string;
+    json?: boolean;
+}
+/** List recent run summaries as text or JSON. */
+export declare function historyCommand(context: CliContext, options: HistoryOptions): Promise<number>;

package/dist/cli/commands/history.js

@@ -0,0 +1,24 @@
+import { LogbookError } from '../../errors.js';
+import { formatDuration } from '../../model.js';
+import { toRel } from '../../paths.js';
+import { FileHistoryStore } from '../../store.js';
+import { positiveInteger } from '../format.js';
+/** List recent run summaries as text or JSON. */
+export async function historyCommand(context, options) {
+    const limit = options.limit ? positiveInteger(options.limit, '--limit') : 20;
+    const rows = await new FileHistoryStore(context.outputDir).listSummaries({ limit, branch: options.branch });
+    if (!rows.length)
+        throw new LogbookError('NO_DATA', `no runs found in ${toRel(context.root, context.outputDir)}`);
+    if (options.json) {
+        context.stdout(`${JSON.stringify(rows, null, 2)}\n`);
+        return 0;
+    }
+    const header = ['RUN ID'.padEnd(23), 'DATE'.padEnd(17), 'BRANCH'.padEnd(9), 'STATUS'.padEnd(9), 'TESTS'.padStart(5), 'FAILED'.padStart(7), 'FLAKY'.padStart(6), 'DURATION'].join('  ');
+    context.stdout(`${header}\n`);
+    for (const row of rows) {
+        const values = [row.runId.padEnd(23), row.startedAt.slice(0, 16).replace('T', ' ').padEnd(17), (row.branch ?? '-').padEnd(9), row.status.padEnd(9), String(row.summary.total).padStart(5), String(row.summary.failed).padStart(7), String(row.summary.flaky).padStart(6), formatDuration(row.durationMs)];
+        context.stdout(`${values.join('  ')}\n`);
+    }
+    return 0;
+}
+//# sourceMappingURL=history.js.map

package/dist/cli/commands/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../../src/cli/commands/history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAI/C,iDAAiD;AACjD,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAmB,EAAE,OAAuB;IAC/E,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7E,MAAM,IAAI,GAAG,MAAM,IAAI,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5G,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,YAAY,CAAC,SAAS,EAAE,oBAAoB,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAClH,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QAAC,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAAC,OAAO,CAAC,CAAC;IAAC,CAAC;IACrF,MAAM,MAAM,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvL,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,CAAC;IAC9B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;QAC1S,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/cli/commands/merge.d.ts

@@ -0,0 +1,12 @@
+import type { CliContext } from '../format.js';
+export interface MergeOptions {
+    runId?: string;
+    from?: string[];
+    force?: boolean;
+    report?: boolean;
+    history?: boolean;
+    timestamp?: boolean;
+    failOnIncomplete?: boolean;
+}
+/** Merge discovered shard files, persist the run, and optionally render its report. */
+export declare function mergeCommand(context: CliContext, options: MergeOptions): Promise<number>;

package/dist/cli/commands/merge.js

@@ -0,0 +1,102 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { LogbookError } from '../../errors.js';
+import { mergeShards } from '../../merge.js';
+import { readShard } from '../../schema.js';
+import { FileHistoryStore } from '../../store.js';
+import { toRel } from '../../paths.js';
+import { modelForRun, writeReport } from '../format.js';
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+async function findFiles(directory) {
+    let entries;
+    try {
+        entries = await fs.readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const files = [];
+    for (const entry of entries.sort((a, b) => compare(a.name, b.name))) {
+        const target = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...await findFiles(target));
+        else if (entry.isFile() && /^shard-.*\.json$/.test(entry.name))
+            files.push(target);
+    }
+    return files;
+}
+async function loadShards(context, options) {
+    const base = path.join(context.outputDir, 'shards');
+    const paths = await findFiles(options.runId ? path.join(base, options.runId) : base);
+    for (const source of options.from ?? [])
+        paths.push(...await findFiles(path.resolve(context.root, source)));
+    const unique = [...new Set(paths)].sort(compare);
+    const shards = [];
+    for (const file of unique) {
+        let text;
+        try {
+            text = await fs.readFile(file, 'utf8');
+        }
+        catch {
+            throw new LogbookError('INVALID_DATA', `${toRel(context.root, file)}: cannot read shard`);
+        }
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            throw new LogbookError('INVALID_DATA', `${toRel(context.root, file)}: invalid JSON`);
+        }
+        const shard = readShard(value, toRel(context.root, file));
+        if (!options.runId || shard.runId === options.runId)
+            shards.push(shard);
+    }
+    return shards;
+}
+function chooseRun(shards, requested) {
+    if (requested)
+        return shards.filter((shard) => shard.runId === requested);
+    const newest = new Map();
+    for (const shard of shards)
+        if (!newest.has(shard.runId) || shard.endedAt > newest.get(shard.runId))
+            newest.set(shard.runId, shard.endedAt);
+    const selected = [...newest].sort(([aId, aEnd], [bId, bEnd]) => compare(bEnd, aEnd) || compare(aId, bId))[0]?.[0];
+    return shards.filter((shard) => shard.runId === selected);
+}
+/** Merge discovered shard files, persist the run, and optionally render its report. */
+export async function mergeCommand(context, options) {
+    const shards = chooseRun(await loadShards(context, options), options.runId);
+    if (!shards.length)
+        throw new LogbookError('NO_DATA', 'no shard files found');
+    const { run, warnings } = mergeShards(shards, { force: options.force, outputDir: toRel(context.root, context.outputDir) });
+    const store = new FileHistoryStore(context.outputDir);
+    if (options.history !== false)
+        await store.saveRun(run, { replace: true });
+    else {
+        const target = path.join(context.outputDir, 'runs', `${run.runId}.json`);
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await fs.writeFile(`${target}.tmp`, `${JSON.stringify(run, null, 2)}\n`, 'utf8');
+        await fs.rename(`${target}.tmp`, target);
+    }
+    for (const warning of warnings)
+        context.stderr(`logbook: ${warning}\n`);
+    const missing = [];
+    for (let index = 1; index <= (run.expectedShards ?? 1); index++)
+        if (!run.receivedShards.includes(index))
+            missing.push(index);
+    const incomplete = run.complete ? '' : ` — INCOMPLETE, missing: ${missing.join(',')}`;
+    context.stdout(`logbook: merged run ${run.runId} (${run.receivedShards.length} of ${run.expectedShards} shards${incomplete}) — ${run.summary.total} tests: ${run.summary.passed} passed, ${run.summary.failed} failed, ${run.summary.flaky} flaky, ${run.summary.skipped} skipped\n`);
+    context.stdout(`run: ${toRel(context.root, path.join(context.outputDir, 'runs', `${run.runId}.json`))}\n`);
+    if (options.report !== false) {
+        const target = await writeReport(context, await modelForRun(context, run, 30, options.timestamp === false));
+        context.stdout(`report: ${target}\n`);
+    }
+    if (options.history !== false) {
+        const summaries = await store.listSummaries({ limit: Number.MAX_SAFE_INTEGER });
+        context.stdout(`history: ${summaries.length} runs (${toRel(context.root, path.join(context.outputDir, 'index.jsonl'))})\n`);
+    }
+    return options.failOnIncomplete && !run.complete ? 5 : 0;
+}
+//# sourceMappingURL=merge.js.map

package/dist/cli/commands/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../../../src/cli/commands/merge.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/report.d.ts

@@ -0,0 +1,9 @@
+import type { CliContext } from '../format.js';
+export interface ReportOptions {
+    run?: string;
+    out?: string;
+    history?: string;
+    timestamp?: boolean;
+}
+/** Regenerate an HTML report from a stored run. */
+export declare function reportCommand(context: CliContext, options: ReportOptions): Promise<number>;

package/dist/cli/commands/report.js

@@ -0,0 +1,13 @@
+import path from 'node:path';
+import { modelForRun, positiveInteger, writeReport } from '../format.js';
+import { FileHistoryStore } from '../../store.js';
+/** Regenerate an HTML report from a stored run. */
+export async function reportCommand(context, options) {
+    const run = await new FileHistoryStore(context.outputDir).loadRun(options.run ?? 'latest');
+    const limit = options.history ? positiveInteger(options.history, '--history') : 30;
+    const target = options.out ? path.resolve(context.root, options.out) : undefined;
+    const relative = await writeReport(context, await modelForRun(context, run, limit, options.timestamp === false), target);
+    context.stdout(`report: ${relative}\n`);
+    return 0;
+}
+//# sourceMappingURL=report.js.map

package/dist/cli/commands/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/cli/commands/report.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIlD,mDAAmD;AACnD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAmB,EAAE,OAAsB;IAC7E,MAAM,GAAG,GAAG,MAAM,IAAI,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC,CAAC;IAC3F,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACnF,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACjF,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,MAAM,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,KAAK,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;IACzH,OAAO,CAAC,MAAM,CAAC,WAAW,QAAQ,IAAI,CAAC,CAAC;IACxC,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/cli/commands/summary.d.ts

@@ -0,0 +1,7 @@
+import type { CliContext } from '../format.js';
+export interface SummaryOptions {
+    run?: string;
+    format?: 'text' | 'markdown' | 'json';
+}
+/** Print a concise run summary for terminals or CI systems. */
+export declare function summaryCommand(context: CliContext, options: SummaryOptions): Promise<number>;

package/dist/cli/commands/summary.js

@@ -0,0 +1,14 @@
+import { buildJsonSummary, renderMarkdownSummary, renderTextSummary } from '../../model.js';
+import { FileHistoryStore } from '../../store.js';
+import { modelForRun } from '../format.js';
+/** Print a concise run summary for terminals or CI systems. */
+export async function summaryCommand(context, options) {
+    const run = await new FileHistoryStore(context.outputDir).loadRun(options.run ?? 'latest');
+    const model = await modelForRun(context, run, 30, true);
+    const output = options.format === 'markdown' ? renderMarkdownSummary(model)
+        : options.format === 'json' ? `${JSON.stringify(buildJsonSummary(model), null, 2)}\n`
+            : renderTextSummary(model);
+    context.stdout(output);
+    return 0;
+}
+//# sourceMappingURL=summary.js.map

package/dist/cli/commands/summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../../src/cli/commands/summary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAI3C,+DAA+D;AAC/D,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAmB,EAAE,OAAuB;IAC/E,MAAM,GAAG,GAAG,MAAM,IAAI,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC,CAAC;IAC3F,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,qBAAqB,CAAC,KAAK,CAAC;QACzE,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI;YACnF,CAAC,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC/B,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACvB,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/cli/format.d.ts

@@ -0,0 +1,18 @@
+import type { ReportModel } from '../model.js';
+import type { RunRecord } from '../schema.js';
+export interface CliContext {
+    root: string;
+    outputDir: string;
+    quiet: boolean;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    clock: () => Date;
+}
+export declare class CliUsageError extends Error {
+}
+/** Build a report model from a run and the available history. */
+export declare function modelForRun(context: CliContext, run: RunRecord, historyLimit?: number, noTimestamp?: boolean): Promise<ReportModel>;
+/** Atomically write a self-contained HTML report and return its relative path. */
+export declare function writeReport(context: CliContext, model: ReportModel, target?: string): Promise<string>;
+/** Validate positive integer CLI options. */
+export declare function positiveInteger(value: string, flag: string): number;

package/dist/cli/format.js

@@ -0,0 +1,41 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { buildReportModel } from '../model.js';
+import { compareRuns, computeFlaky, previousRun } from '../history.js';
+import { FileHistoryStore } from '../store.js';
+import { renderReport } from '../render.js';
+import { toRel } from '../paths.js';
+import { resolveArtifactAvailability } from '../artifacts.js';
+export class CliUsageError extends Error {
+}
+function asSummary(run) {
+    return { schemaVersion: 1, runId: run.runId, title: run.title, startedAt: run.startedAt, durationMs: run.durationMs, status: run.status, complete: run.complete, summary: run.summary, branch: run.env.git.branch, commit: run.env.git.commit, ciProvider: run.env.ci?.provider ?? null, buildUrl: run.env.ci?.buildUrl ?? null };
+}
+/** Build a report model from a run and the available history. */
+export async function modelForRun(context, run, historyLimit = 30, noTimestamp = false) {
+    const store = new FileHistoryStore(context.outputDir);
+    const summaries = await store.listSummaries({ limit: historyLimit });
+    const previous = previousRun(summaries, asSummary(run));
+    const previousRecord = previous ? await store.loadRun(previous.runId) : null;
+    const ordered = await store.loadRuns(summaries.map((item) => item.runId).reverse());
+    const attachmentAvailability = await resolveArtifactAvailability(run, context.root);
+    return buildReportModel({ run, summaries, previous, comparison: compareRuns(run, previousRecord), flaky: computeFlaky(ordered), recentRuns: ordered.filter((item) => item.runId !== run.runId), generatedAt: noTimestamp ? null : context.clock().toISOString(), historyLimit, attachmentAvailability });
+}
+/** Atomically write a self-contained HTML report and return its relative path. */
+export async function writeReport(context, model, target = path.join(context.outputDir, 'report', 'index.html')) {
+    const relative = toRel(context.root, target);
+    const reportDir = path.posix.dirname(relative);
+    const html = renderReport(model, { reportDir });
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(`${target}.tmp`, html, 'utf8');
+    await fs.rename(`${target}.tmp`, target);
+    return relative;
+}
+/** Validate positive integer CLI options. */
+export function positiveInteger(value, flag) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1)
+        throw new CliUsageError(`${flag} requires a positive integer`);
+    return parsed;
+}
+//# sourceMappingURL=format.js.map