@michaelmagan/dnumb 0.1.0

package/dist/playwright.d.cts

@@ -0,0 +1,69 @@
+import { type Bundle } from "./bundle.cjs";
+import type { PageLike } from "./page.cjs";
+import { type CaptureOptions } from "./snapshot/capture.cjs";
+/** Mirrors Playwright's own `.playwright-artifacts` habit: hidden, gitignorable, per-repo. */
+export declare const DEFAULT_OUTPUT_DIR = ".dnumb";
+/**
+ * The part of Playwright's `TestInfo` a capture touches. Optional in the
+ * options because `capture` must work in a bare script with no test runner.
+ */
+export interface TestInfoLike {
+    attach(name: string, options: {
+        body?: string;
+        contentType?: string;
+        path?: string;
+    }): Promise<void>;
+}
+export interface CapturePageOptions {
+    /** Directory the bundle is written to. Relative paths resolve from `cwd`. */
+    outputDir?: string;
+    /** Passed straight through to the collector. */
+    strategy?: CaptureOptions['strategy'];
+    /** A label for the viewport (`desktop`, `iphone-15`), recorded in the bundle. */
+    viewportName?: string;
+    labels?: Record<string, string>;
+    /** When present, the bundle also rides Playwright's report pipeline. */
+    testInfo?: TestInfoLike;
+}
+export interface PageCapture {
+    bundle: Bundle;
+    /** Where the bundle was written. Absolute if `outputDir` was. */
+    path: string;
+}
+/**
+ * A capture name is caller-chosen text that becomes a path segment, so it is
+ * the one untrusted input here. Separators collapse into `-` rather than being
+ * rejected, because `settings/desktop` is a reasonable thing to type and
+ * failing a test over it would be hostile — but a leading run of dots or dashes
+ * is stripped outright, which is what turns `../../etc/passwd` into
+ * `etc-passwd` instead of a traversal.
+ */
+export declare function safeName(name: string): string;
+/** Where `writeBundle` puts a bundle of this name. Exported so a caller can predict it. */
+export declare function bundlePath(dir: string, name: string): string;
+/**
+ * The bundle keeps the caller's name verbatim — it is the state label the
+ * digest header prints — and only the *path* is sanitized. Two names that
+ * differ solely in punctuation therefore land on one file: `settings/desktop`
+ * and `settings-desktop` both write `settings-desktop.json`.
+ *
+ * Re-capturing the same name overwrites, which is what a test re-run should do.
+ * A *different* name landing on an existing file is a collision, and silently
+ * discarding one of two captures a suite meant to keep is the kind of data loss
+ * that gets noticed weeks later, on the run that mattered. So that case throws,
+ * and the message names both captures and the fix.
+ */
+export declare function writeBundle(bundle: Bundle, dir?: string): string;
+/**
+ * Capture `page` as a bundle on disk.
+ *
+ * ```ts
+ * import { capture } from '@michaelmagan/dnumb/playwright';
+ *
+ * test('settings page', async ({ page }, testInfo) => {
+ *   await page.goto('/settings');
+ *   await capture(page, 'settings-desktop', { testInfo });
+ * });
+ * ```
+ */
+export declare function capture(page: PageLike, name: string, options?: CapturePageOptions): Promise<PageCapture>;

package/dist/playwright.d.ts

@@ -0,0 +1,69 @@
+import { type Bundle } from "./bundle.js";
+import type { PageLike } from "./page.js";
+import { type CaptureOptions } from "./snapshot/capture.js";
+/** Mirrors Playwright's own `.playwright-artifacts` habit: hidden, gitignorable, per-repo. */
+export declare const DEFAULT_OUTPUT_DIR = ".dnumb";
+/**
+ * The part of Playwright's `TestInfo` a capture touches. Optional in the
+ * options because `capture` must work in a bare script with no test runner.
+ */
+export interface TestInfoLike {
+    attach(name: string, options: {
+        body?: string;
+        contentType?: string;
+        path?: string;
+    }): Promise<void>;
+}
+export interface CapturePageOptions {
+    /** Directory the bundle is written to. Relative paths resolve from `cwd`. */
+    outputDir?: string;
+    /** Passed straight through to the collector. */
+    strategy?: CaptureOptions['strategy'];
+    /** A label for the viewport (`desktop`, `iphone-15`), recorded in the bundle. */
+    viewportName?: string;
+    labels?: Record<string, string>;
+    /** When present, the bundle also rides Playwright's report pipeline. */
+    testInfo?: TestInfoLike;
+}
+export interface PageCapture {
+    bundle: Bundle;
+    /** Where the bundle was written. Absolute if `outputDir` was. */
+    path: string;
+}
+/**
+ * A capture name is caller-chosen text that becomes a path segment, so it is
+ * the one untrusted input here. Separators collapse into `-` rather than being
+ * rejected, because `settings/desktop` is a reasonable thing to type and
+ * failing a test over it would be hostile — but a leading run of dots or dashes
+ * is stripped outright, which is what turns `../../etc/passwd` into
+ * `etc-passwd` instead of a traversal.
+ */
+export declare function safeName(name: string): string;
+/** Where `writeBundle` puts a bundle of this name. Exported so a caller can predict it. */
+export declare function bundlePath(dir: string, name: string): string;
+/**
+ * The bundle keeps the caller's name verbatim — it is the state label the
+ * digest header prints — and only the *path* is sanitized. Two names that
+ * differ solely in punctuation therefore land on one file: `settings/desktop`
+ * and `settings-desktop` both write `settings-desktop.json`.
+ *
+ * Re-capturing the same name overwrites, which is what a test re-run should do.
+ * A *different* name landing on an existing file is a collision, and silently
+ * discarding one of two captures a suite meant to keep is the kind of data loss
+ * that gets noticed weeks later, on the run that mattered. So that case throws,
+ * and the message names both captures and the fix.
+ */
+export declare function writeBundle(bundle: Bundle, dir?: string): string;
+/**
+ * Capture `page` as a bundle on disk.
+ *
+ * ```ts
+ * import { capture } from '@michaelmagan/dnumb/playwright';
+ *
+ * test('settings page', async ({ page }, testInfo) => {
+ *   await page.goto('/settings');
+ *   await capture(page, 'settings-desktop', { testInfo });
+ * });
+ * ```
+ */
+export declare function capture(page: PageLike, name: string, options?: CapturePageOptions): Promise<PageCapture>;

package/dist/playwright.js

@@ -0,0 +1,131 @@
+/**
+ * `dnumb/playwright` — one import and one call inside a suite that already has
+ * a running app, an authenticated session, and a `page` in scope.
+ *
+ * This is the wedge: the cost of a capture has to be a single line in a test
+ * someone already wrote, or the bundle never gets produced and nothing
+ * downstream of it matters.
+ *
+ * Nothing here imports Playwright, not even as a type. `playwright-core` is an
+ * *optional* peer, so a `import type { Page } from 'playwright-core'` in this
+ * file would break typechecking for a consumer who installed dnumb for the
+ * offline `--from <bundle>` path alone. The interfaces are structural instead,
+ * and a real `Page` / `TestInfo` satisfies them by shape.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { buildBundle, serializeBundle } from "./bundle.js";
+import { capture as captureSnapshot } from "./snapshot/capture.js";
+/** Mirrors Playwright's own `.playwright-artifacts` habit: hidden, gitignorable, per-repo. */
+export const DEFAULT_OUTPUT_DIR = '.dnumb';
+/** Everything a filename can carry without quoting on any of the three platforms. */
+const UNSAFE = /[^a-zA-Z0-9._-]+/g;
+/** ext4 and APFS both cap a name at 255 bytes; leave room for the extension. */
+const MAX_NAME = 120;
+/**
+ * A capture name is caller-chosen text that becomes a path segment, so it is
+ * the one untrusted input here. Separators collapse into `-` rather than being
+ * rejected, because `settings/desktop` is a reasonable thing to type and
+ * failing a test over it would be hostile — but a leading run of dots or dashes
+ * is stripped outright, which is what turns `../../etc/passwd` into
+ * `etc-passwd` instead of a traversal.
+ */
+export function safeName(name) {
+    const flat = name
+        .trim()
+        .replace(UNSAFE, '-')
+        .replace(/^[-.]+/, '')
+        .replace(/[-.]+$/, '');
+    if (!flat) {
+        throw new Error(`dnumb: capture name ${JSON.stringify(name)} has no filesystem-safe characters in it. ` +
+            'Names become filenames; use letters, digits, "." "_" or "-".');
+    }
+    return flat.slice(0, MAX_NAME);
+}
+/** Where `writeBundle` puts a bundle of this name. Exported so a caller can predict it. */
+export function bundlePath(dir, name) {
+    return join(dir, `${safeName(name)}.json`);
+}
+/**
+ * The bundle keeps the caller's name verbatim — it is the state label the
+ * digest header prints — and only the *path* is sanitized. Two names that
+ * differ solely in punctuation therefore land on one file: `settings/desktop`
+ * and `settings-desktop` both write `settings-desktop.json`.
+ *
+ * Re-capturing the same name overwrites, which is what a test re-run should do.
+ * A *different* name landing on an existing file is a collision, and silently
+ * discarding one of two captures a suite meant to keep is the kind of data loss
+ * that gets noticed weeks later, on the run that mattered. So that case throws,
+ * and the message names both captures and the fix.
+ */
+export function writeBundle(bundle, dir = DEFAULT_OUTPUT_DIR) {
+    const path = bundlePath(dir, bundle.name);
+    mkdirSync(dirname(path), { recursive: true });
+    if (existsSync(path)) {
+        const existing = readExistingName(path);
+        if (existing !== null && existing !== bundle.name) {
+            throw new Error(`dnumb: capture ${JSON.stringify(bundle.name)} and capture ${JSON.stringify(existing)} ` +
+                `both write to ${path}, because names become filenames. Rename one of them.`);
+        }
+    }
+    writeFileSync(path, serializeBundle(bundle), 'utf8');
+    return path;
+}
+/**
+ * The `name` of the bundle already at `path`, or `null` if it cannot be read as
+ * one. Unreadable is not a collision — an unrelated file in the output
+ * directory should not stop a capture — so it falls through to the overwrite.
+ */
+function readExistingName(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const name = parsed.name;
+        return typeof name === 'string' ? name : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Capture `page` as a bundle on disk.
+ *
+ * ```ts
+ * import { capture } from '@michaelmagan/dnumb/playwright';
+ *
+ * test('settings page', async ({ page }, testInfo) => {
+ *   await page.goto('/settings');
+ *   await capture(page, 'settings-desktop', { testInfo });
+ * });
+ * ```
+ */
+export async function capture(page, name, options = {}) {
+    const dir = options.outputDir ?? DEFAULT_OUTPUT_DIR;
+    // Fail on an unusable name before spending a capture on it.
+    safeName(name);
+    const result = await captureSnapshot(page, options.strategy ? { strategy: options.strategy } : {});
+    // The URL is read from inside the page rather than taken from the caller for
+    // the same reason the viewport is (`page.viewportSize()` is null over
+    // `connectOverCDP`): the page is the only thing that knows where it ended up
+    // after redirects, and a bundle that names the URL the test *asked* for is a
+    // bundle that lies six months later.
+    const url = await page.evaluate(() => location.href);
+    const bundle = buildBundle(result, {
+        name,
+        url,
+        capturedAt: new Date().toISOString(),
+        ...(options.viewportName ? { viewportName: options.viewportName } : {}),
+        ...(options.labels ? { labels: options.labels } : {}),
+    });
+    const path = writeBundle(bundle, dir);
+    if (options.testInfo) {
+        // `body`, not `path`: the attachment has to survive the output directory
+        // being cleaned between the run and the report being read in CI.
+        await options.testInfo.attach(`${safeName(name)}.dnumb.json`, {
+            body: serializeBundle(bundle),
+            contentType: 'application/json',
+        });
+    }
+    return { bundle, path };
+}