@asrunjs/asrun 0.0.0-stage → 0.5.2

package/dist/lib/fixtures.js

@@ -0,0 +1,149 @@
+import { expect, test as base } from '@playwright/test';
+import { getProfile } from './profiles.js';
+import { caseWrites, caseWritesIn, hasCaseFile, readCaseMeta } from './cases.js';
+import { acquireAccountLock } from './account-lock.js';
+import { ledgerFile, TEST_DATA_PREFIX, writeLedger } from './records.js';
+import { caseIdFromFile } from './run-summary.js';
+import { ALLOW_WRITES_ENV, isProtectedEnv } from './write-gate.js';
+import { checkSession, isLoggedOutUrl, parseNotLoggedIn, sessionProblemMessage, signinCommand, } from './session.js';
+export const test = base.extend({
+    profile: [
+        async ({}, use, workerInfo) => {
+            await use(getProfile(workerInfo.project.name));
+        },
+        { scope: 'worker' },
+    ],
+    mustLogin: [true, { scope: 'worker', option: true }],
+    // Login is not something we test: a profile without a valid session fails right away with an
+    // actionable message instead of a confusing login-page failure.
+    sessionGuard: [
+        async ({ browser, profile, mustLogin }, use) => {
+            if (mustLogin) {
+                // `pnpm asrun` already checked every profile before the run; reuse its result.
+                const status = parseNotLoggedIn().get(profile.id) ?? (await checkSession(browser, profile));
+                if (status !== 'ok') {
+                    throw new Error(sessionProblemMessage(profile, status));
+                }
+            }
+            await use();
+        },
+        { scope: 'worker', auto: true },
+    ],
+    // Enforced here, not only in `pnpm asrun`, so that running `playwright test` directly cannot bypass it:
+    // a case may be limited to some environments (`envs`), a case that writes data only runs in the environments
+    // it lists under `writes` (elsewhere it is skipped), and writing in any environment except staging needs a
+    // human's confirmation.
+    caseGate: [
+        async ({ profile }, use, testInfo) => {
+            const caseId = caseIdFromFile(testInfo.file);
+            if (hasCaseFile(caseId)) {
+                const meta = readCaseMeta(caseId);
+                testInfo.skip(meta.envs !== null && !meta.envs.includes(profile.env), `This case is limited to: ${meta.envs?.join(', ')}`);
+                testInfo.skip(caseWrites(meta) && !caseWritesIn(meta, profile.env), `This case writes data and has no permission to write in ${profile.env.toUpperCase()} (it lists: ${meta.writes.join(', ')}).`);
+                if (caseWritesIn(meta, profile.env) && isProtectedEnv(profile.env) && process.env[ALLOW_WRITES_ENV] !== profile.env) {
+                    throw new Error(`This case writes data and has no permission to run in ${profile.env.toUpperCase()}. ` +
+                        `Start it with "pnpm asrun --env ${profile.env}" and confirm, or run it in staging.`);
+                }
+            }
+            await use();
+        },
+        { scope: 'test', auto: true },
+    ],
+    // Cases that write to an account run one at a time per profile, whatever the worker count.
+    accountLock: [
+        async ({ profile, caseGate: _gate }, use, testInfo) => {
+            const caseId = caseIdFromFile(testInfo.file);
+            if (!hasCaseFile(caseId) || !caseWrites(readCaseMeta(caseId))) {
+                await use();
+                return;
+            }
+            const release = await acquireAccountLock(profile.id, WRITE_CASE_TIMEOUT_MS);
+            try {
+                await use();
+            }
+            finally {
+                release();
+            }
+        },
+        { scope: 'test', auto: true },
+    ],
+    // Tracks test data and removes it again, newest first. See `Records.track`.
+    records: async ({ profile, page: _page }, use, testInfo) => {
+        const caseId = caseIdFromFile(testInfo.file);
+        const runId = process.env.ASRUN_RUN_ID ?? 'adhoc';
+        const file = ledgerFile(runId, testInfo.testId);
+        const entries = [];
+        const save = () => writeLedger(file, entries.map((item) => item.entry));
+        await use({
+            async track(data, remove) {
+                if (!data.name.startsWith(TEST_DATA_PREFIX)) {
+                    throw new Error(`Test data must be named with the prefix "${TEST_DATA_PREFIX}" (got "${data.name}"). ` +
+                        `Only data that is clearly a test's own may be created and removed.`);
+                }
+                entries.push({
+                    entry: {
+                        id: `${entries.length + 1}`,
+                        runId,
+                        env: profile.env,
+                        profile: profile.id,
+                        caseId,
+                        kind: data.kind,
+                        name: data.name,
+                        where: data.where ?? null,
+                        status: 'open',
+                        error: null,
+                        createdAt: new Date().toISOString(),
+                    },
+                    remove,
+                });
+                // Written at once: if the process dies, the ledger still says what was left behind.
+                save();
+            },
+        });
+        const failures = [];
+        for (const item of [...entries].reverse()) {
+            try {
+                await item.remove();
+                item.entry.status = 'cleaned';
+            }
+            catch (error) {
+                item.entry.status = 'leftover';
+                item.entry.error = error.message.split('\n')[0];
+                failures.push(`${item.entry.kind} "${item.entry.name}"${item.entry.where ? ` (look in ${item.entry.where})` : ''}`);
+            }
+            save();
+        }
+        if (failures.length > 0) {
+            testInfo.annotations.push({ type: 'leftover-data', description: failures.join('; ') });
+            throw new Error(`Test data was not removed and must be deleted by hand: ${failures.join('; ')}`);
+        }
+    },
+    // The session can also expire in the middle of a run; say so when a failed test ends on /login.
+    sessionExpiryHint: [
+        async ({ page, profile, mustLogin }, use, testInfo) => {
+            await use();
+            if (!mustLogin || testInfo.status === testInfo.expectedStatus) {
+                return;
+            }
+            if (page.isClosed() || !isLoggedOutUrl(page.url(), profile.sessionCheck)) {
+                return;
+            }
+            const description = `The session of profile "${profile.id}" in ${profile.env} expired during the run. Log in again: ${signinCommand(profile)}`;
+            testInfo.annotations.push({ type: 'session-expired', description });
+            console.error(`\n${description}\n`);
+        },
+        { scope: 'test', auto: true },
+    ],
+});
+/** Longest a write case may take, and how long it waits for another case that uses the same account. */
+const WRITE_CASE_TIMEOUT_MS = 180_000;
+/**
+ * Call at the top of the `test.describe` of every spec (`configureCase('<id>')`). Cases that write data are
+ * never retried (a retry would create the data a second time) and get more time than a read-only case.
+ */
+export function configureCase(caseId) {
+    if (hasCaseFile(caseId) && caseWrites(readCaseMeta(caseId))) {
+        test.describe.configure({ retries: 0, timeout: WRITE_CASE_TIMEOUT_MS });
+    }
+}
+export { expect };

package/dist/lib/login-card.d.ts

@@ -0,0 +1,22 @@
+import type { BrowserContext, Page } from '@playwright/test';
+/**
+ * The card the person sees in the sign-in window: it tells them what to do and saves the session when they press Done,
+ * so nobody has to switch back to the UI and press the button on the job.
+ *
+ * The card is painted by an init script, so it is there again after every navigation the login makes (and in a popup
+ * the site opens). It is the small variant of the attended handoff card
+ * (`<framework>/.claude/skills/exploring-cases/references/handoff-card.js`): no copy chips, no finish condition, and
+ * it lives in its own shadow root so the site's CSS cannot change it. Styles go through a constructed stylesheet,
+ * because a site with a strict CSP blocks an inline `<style>` element.
+ */
+/** How the wait for the person ended. */
+export type LoginCardOutcome = 'done' | 'cancel' | 'closed' | 'stopped';
+/** Adds the card to every page of the context, now and on every navigation after this call. */
+export declare function showLoginCard(context: BrowserContext, message: string): void;
+/** What the card says once the session is saved, before the window closes. */
+export declare function showLoginCardSaved(context: BrowserContext, text: string): Promise<void>;
+/**
+ * Waits until the person presses Done or Cancel on the card, or closes the window. `signal` lets the caller stop the
+ * wait when something else finished it first (the Enter key on the command line, or the button in the UI).
+ */
+export declare function waitForLoginCard(context: BrowserContext, page: Page, signal?: AbortSignal): Promise<LoginCardOutcome>;

package/dist/lib/login-card.js

@@ -0,0 +1,183 @@
+const FLAG = '__asrunLoginCard';
+const FINISH = '__asrunLoginCardFinish';
+/** Adds the card to every page of the context, now and on every navigation after this call. */
+export function showLoginCard(context, message) {
+    void context.addInitScript({ content: loginCardSource(message) }).catch(() => { });
+}
+/** What the card says once the session is saved, before the window closes. */
+export async function showLoginCardSaved(context, text) {
+    const call = `window.${FINISH} && window.${FINISH}(${JSON.stringify(text)})`;
+    await Promise.all(context.pages().map((page) => page.evaluate(call).catch(() => null)));
+}
+/**
+ * Waits until the person presses Done or Cancel on the card, or closes the window. `signal` lets the caller stop the
+ * wait when something else finished it first (the Enter key on the command line, or the button in the UI).
+ */
+export async function waitForLoginCard(context, page, signal) {
+    const read = `window.${FLAG} ?? null`;
+    for (;;) {
+        for (const open of context.pages()) {
+            const flag = await open.evaluate(read).catch(() => null);
+            if (flag === 'done' || flag === 'cancel')
+                return flag;
+        }
+        if (signal?.aborted)
+            return 'stopped';
+        if (page.isClosed() || context.pages().length === 0)
+            return 'closed';
+        await new Promise((resolve) => setTimeout(resolve, 400));
+    }
+}
+/** The whole card as one script, with the message baked in: an init script cannot close over anything. */
+function loginCardSource(message) {
+    return `(() => {
+  const MESSAGE = ${JSON.stringify(message)};
+  const FLAG = '${FLAG}';
+  const CLICK_KEY = '__ASRUN_login_card_click';
+  const POS_KEY = '__ASRUN_login_card_pos';
+  const ID = '__ASRUN_login_card';
+  try {
+    const early = sessionStorage.getItem(CLICK_KEY);
+    if (early) window[FLAG] = early;
+  } catch (error) {}
+
+  const paint = () => {
+    // One card, in the page the person logs in on: never in an iframe of the site.
+    if (window.top !== window.self) return true;
+    if (!document.body) return false;
+    if (document.getElementById(ID)) return true;
+
+    const state = {minimized: false, left: null, top: null};
+    try { Object.assign(state, JSON.parse(sessionStorage.getItem(POS_KEY) || '{}')); } catch (error) {}
+    const save = () => { try { sessionStorage.setItem(POS_KEY, JSON.stringify(state)); } catch (error) {} };
+
+    const svg = (body) =>
+      '<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" ' +
+      'stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' + body + '</svg>';
+    const ICON = {
+      move: svg('<polyline points="5 9 2 12 5 15"/><polyline points="9 5 12 2 15 5"/><polyline points="15 19 12 22 9 19"/>' +
+        '<polyline points="19 9 22 12 19 15"/><line x1="2" y1="12" x2="22" y2="12"/><line x1="12" y1="2" x2="12" y2="22"/>'),
+      up: svg('<polyline points="18 15 12 9 6 15"/>'),
+      down: svg('<polyline points="6 9 12 15 18 9"/>'),
+    };
+    const css = [
+      '.card{width:300px;max-width:calc(100vw - 32px);background:#1e3340;color:#fff;font:13px/1.4 system-ui,sans-serif;' +
+        'border-radius:8px;box-shadow:0 6px 20px rgba(0,0,0,.35);overflow:hidden}',
+      '.card.min{width:auto}.card.ok{background:#15803d}',
+      '.card.ok .body,.card.ok .mini-done{display:none}',
+      '.bar{display:flex;align-items:center;gap:8px;padding:7px 8px 7px 12px;background:#b45309;cursor:grab;' +
+        'user-select:none;touch-action:none}',
+      '.ok .bar{background:#166534;align-items:flex-start;padding-top:9px}',
+      '.bar b{flex:1;min-width:0;font-size:12px;letter-spacing:.04em;white-space:nowrap}',
+      '.ok .bar b{white-space:normal;line-height:1.35}',
+      '.grip{display:inline-flex;opacity:.8}',
+      'button{all:unset;box-sizing:border-box;cursor:pointer;display:inline-flex;align-items:center;' +
+        'justify-content:center;gap:4px;padding:3px 8px;border-radius:4px;background:rgba(255,255,255,.18);' +
+        'color:#fff;font:600 12px system-ui,sans-serif}',
+      'button:hover{background:rgba(255,255,255,.3)}',
+      '.body{padding:10px 12px 12px;display:flex;flex-direction:column;gap:8px}.min .body{display:none}',
+      '.mini-done{display:none}.min .mini-done{display:inline-flex}',
+      '.row{display:flex;gap:8px}.row .primary{background:#15803d}.row .primary:hover{background:#16a34a}',
+      '.row .primary{flex:1}',
+    ].join('');
+
+    const host = document.createElement('div');
+    host.id = ID;
+    host.style.cssText = 'all:initial;position:fixed;z-index:2147483647;left:16px;bottom:16px';
+    const root = host.attachShadow({mode: 'open'});
+    // A constructed stylesheet is not an inline style, so a site with a strict CSP cannot block it.
+    try {
+      const sheet = new CSSStyleSheet();
+      sheet.replaceSync(css);
+      root.adoptedStyleSheets = [sheet];
+    } catch (error) {
+      const style = document.createElement('style');
+      style.textContent = css;
+      root.appendChild(style);
+    }
+    const holder = document.createElement('div');
+    holder.innerHTML =
+      '<div class="card" id="card"><div class="bar" id="bar" title="Drag to move">' +
+      '<span class="grip">' + ICON.move + '</span><b id="title">YOUR TURN: log in</b>' +
+      '<button class="mini-done" data-a="done">Done</button>' +
+      '<button id="toggle" title="Minimize or expand" aria-label="Minimize or expand"></button></div>' +
+      '<div class="body"><div id="msg"></div><div class="row">' +
+      '<button class="primary" data-a="done">Done, save the session</button>' +
+      '<button data-a="cancel">Cancel</button></div></div></div>';
+
+    const card = holder.firstElementChild;
+    const bar = card.querySelector('#bar');
+    const toggle = card.querySelector('#toggle');
+    const message = card.querySelector('#msg');
+    message.textContent = MESSAGE;
+    root.appendChild(card);
+
+    const apply = () => {
+      card.classList.toggle('min', state.minimized);
+      toggle.innerHTML = state.minimized ? ICON.up : ICON.down;
+    };
+    const place = () => {
+      if (state.left === null) return;
+      const box = host.getBoundingClientRect();
+      const left = Math.max(0, Math.min(innerWidth - Math.min(box.width, 80), state.left));
+      const top = Math.max(0, Math.min(innerHeight - 36, state.top));
+      host.style.left = left + 'px';
+      host.style.top = top + 'px';
+      host.style.bottom = 'auto';
+    };
+
+    // The card must never take the keyboard focus away from the site's login form.
+    root.addEventListener('mousedown', (event) => {
+      if (event.target.closest('button')) event.preventDefault();
+    });
+    root.addEventListener('click', (event) => {
+      const button = event.target.closest('[data-a]');
+      if (!button) return;
+      const value = button.dataset.a;
+      window[FLAG] = value;
+      try { sessionStorage.setItem(CLICK_KEY, value); } catch (error) {}
+    });
+    toggle.addEventListener('click', () => {
+      state.minimized = !state.minimized;
+      save();
+      apply();
+      place();
+    });
+
+    let drag = null;
+    bar.addEventListener('pointerdown', (event) => {
+      if (event.target.closest('button')) return;
+      const box = host.getBoundingClientRect();
+      drag = {dx: event.clientX - box.left, dy: event.clientY - box.top};
+      bar.setPointerCapture(event.pointerId);
+      bar.style.cursor = 'grabbing';
+    });
+    bar.addEventListener('pointermove', (event) => {
+      if (!drag) return;
+      state.left = event.clientX - drag.dx;
+      state.top = event.clientY - drag.dy;
+      place();
+    });
+    bar.addEventListener('pointerup', () => {
+      drag = null;
+      bar.style.cursor = 'grab';
+      save();
+    });
+
+    window[${JSON.stringify(FINISH)}] = (text) => {
+      card.classList.remove('min');
+      card.classList.add('ok');
+      toggle.style.display = 'none';
+      bar.querySelector('b').textContent = text;
+      message.textContent = '';
+    };
+
+    apply();
+    document.documentElement.appendChild(host);
+    place();
+    return true;
+  };
+
+  if (!paint()) document.addEventListener('DOMContentLoaded', paint, {once: true});
+})();`;
+}

package/dist/lib/node-cli.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Arguments that run one of the framework's own scripts (for example `login.ts`): the TypeScript source in the
+ * framework repository (tsx is installed there), the compiled file in a workspace, which only ships `dist/`.
+ *
+ * The source is tried first on purpose. A `dist/` left over from an earlier `pnpm build` must never win over a
+ * source file that was edited since: `pnpm asrun` runs `scripts/run.ts` through tsx, so the jobs the web UI starts
+ * have to run the same code, not the previous build.
+ */
+export declare function scriptArgs(name: string): string[];
+/**
+ * The JavaScript entry point of a package's command-line tool. The shims in `node_modules/.bin` are POSIX shell
+ * scripts on Windows and cannot be spawned there, so tools are always started with the current Node instead.
+ * The path comes from the package manifest, so a dependency upgrade cannot silently break it.
+ */
+export declare function commandScript(packageName: string, command?: string): string;

package/dist/lib/node-cli.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { FRAMEWORK_ROOT, packageDir } from './paths.js';
+/**
+ * Arguments that run one of the framework's own scripts (for example `login.ts`): the TypeScript source in the
+ * framework repository (tsx is installed there), the compiled file in a workspace, which only ships `dist/`.
+ *
+ * The source is tried first on purpose. A `dist/` left over from an earlier `pnpm build` must never win over a
+ * source file that was edited since: `pnpm asrun` runs `scripts/run.ts` through tsx, so the jobs the web UI starts
+ * have to run the same code, not the previous build.
+ */
+export function scriptArgs(name) {
+    const source = path.join(FRAMEWORK_ROOT, 'scripts', name);
+    if (fs.existsSync(source)) {
+        try {
+            return [commandScript('tsx'), source];
+        }
+        catch {
+            // No tsx: an installed package ships `dist/` only, so the compiled file below is the one to run.
+        }
+    }
+    return [path.join(FRAMEWORK_ROOT, 'dist', 'scripts', name.replace(/\.ts$/, '.js'))];
+}
+/**
+ * The JavaScript entry point of a package's command-line tool. The shims in `node_modules/.bin` are POSIX shell
+ * scripts on Windows and cannot be spawned there, so tools are always started with the current Node instead.
+ * The path comes from the package manifest, so a dependency upgrade cannot silently break it.
+ */
+export function commandScript(packageName, command = packageName) {
+    const dir = packageDir(packageName);
+    const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const script = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.[command];
+    if (!script)
+        throw new Error(`${packageName} has no command-line entry point "${command}".`);
+    return path.join(dir, script);
+}

package/dist/lib/paths.d.ts

@@ -0,0 +1,25 @@
+export declare const FRAMEWORK_ROOT: string;
+/**
+ * The workspace root: the project that uses the framework. Everything the framework reads or writes for a project
+ * (`profiles.yaml`, `cases/`, `tests/`, `.auth/`, `reports/`, `.tmp/`) is relative to it.
+ *
+ * `ASRUN_ROOT` chooses it explicitly. Otherwise it is the nearest folder at or above the current working
+ * directory that holds `profiles.yaml` or `.asrun.json`; without one the framework's own folder is used, which is
+ * how the framework runs against `examples/`.
+ */
+export declare const ROOT: string;
+/** True when `ROOT` is the framework folder itself, i.e. no workspace was found. */
+export declare const isFrameworkRoot: () => boolean;
+/** One saved login per profile: `.auth/<profile-id>.json`. */
+export declare const authFile: (profileId: string) => string;
+export declare const CASES_DIR: string;
+export declare const TESTS_DIR: string;
+export declare const REPORTS_DIR: string;
+export declare const TMP_DIR: string;
+export declare const TEMPLATES_DIR: string;
+export declare const SKILLS_DIR: string;
+/**
+ * The `node_modules/<package>` folder of the framework's own install, or the workspace's (a hoisted or linked
+ * install). Tools that need a package folder rather than a module (vite's config, pdfjs assets) use this.
+ */
+export declare function packageDir(packageName: string): string;

package/dist/lib/paths.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Where the framework's own code and assets live: the package folder (`node_modules/@asrunjs/asrun`). The compiled files sit in
+ * `dist/lib`, so one level up from there is the package root again.
+ */
+const MODULE_DIR = import.meta.dirname;
+export const FRAMEWORK_ROOT = path.basename(path.dirname(MODULE_DIR)) === 'dist' ? path.resolve(MODULE_DIR, '..', '..') : path.resolve(MODULE_DIR, '..');
+/**
+ * Reads a `.env` file into `process.env`. A variable that already exists (a real environment variable, or one from an
+ * earlier file) is never overridden. `ASRUN_ROOT` is resolved against the folder of the file, so `.` in
+ * `<workspace>/.env` means the workspace and `examples/demo` in the framework's `.env` means that folder.
+ */
+function loadEnvFile(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return;
+    }
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const [, key, rawValue] = match;
+        if (process.env[key] !== undefined)
+            continue;
+        const value = rawValue.trim().replace(/^(['"])(.*)\1$/, '$2');
+        process.env[key] = key === 'ASRUN_ROOT' ? path.resolve(path.dirname(file), value) : value;
+    }
+}
+// The workspace can be chosen per machine without exporting anything: the `.env` next to the command, or the
+// framework's own `.env` (that is how the framework itself develops against examples/).
+loadEnvFile(path.join(process.cwd(), '.env'));
+if (process.env.ASRUN_ROOT === undefined)
+    loadEnvFile(path.join(FRAMEWORK_ROOT, '.env'));
+/** Files that mark the root of a workspace: the project that owns `profiles.yaml`, `cases/` and `tests/`. */
+const WORKSPACE_MARKERS = ['.asrun.json', 'profiles.yaml'];
+function findWorkspace(from) {
+    let dir = path.resolve(from);
+    for (;;) {
+        if (WORKSPACE_MARKERS.some((marker) => fs.existsSync(path.join(dir, marker))))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * The workspace root: the project that uses the framework. Everything the framework reads or writes for a project
+ * (`profiles.yaml`, `cases/`, `tests/`, `.auth/`, `reports/`, `.tmp/`) is relative to it.
+ *
+ * `ASRUN_ROOT` chooses it explicitly. Otherwise it is the nearest folder at or above the current working
+ * directory that holds `profiles.yaml` or `.asrun.json`; without one the framework's own folder is used, which is
+ * how the framework runs against `examples/`.
+ */
+export const ROOT = process.env.ASRUN_ROOT ? path.resolve(process.env.ASRUN_ROOT) : (findWorkspace(process.cwd()) ?? FRAMEWORK_ROOT);
+// Children (Playwright, the web UI jobs) inherit the resolved absolute path: a relative ASRUN_ROOT would point
+// somewhere else once the working directory changes.
+process.env.ASRUN_ROOT = ROOT;
+/** True when `ROOT` is the framework folder itself, i.e. no workspace was found. */
+export const isFrameworkRoot = () => path.resolve(ROOT) === path.resolve(FRAMEWORK_ROOT);
+/** One saved login per profile: `.auth/<profile-id>.json`. */
+export const authFile = (profileId) => path.join(ROOT, '.auth', `${profileId}.json`);
+export const CASES_DIR = path.join(ROOT, 'cases');
+export const TESTS_DIR = path.join(ROOT, 'tests');
+export const REPORTS_DIR = path.join(ROOT, 'reports');
+export const TMP_DIR = path.join(ROOT, '.tmp');
+export const TEMPLATES_DIR = path.join(FRAMEWORK_ROOT, 'templates');
+export const SKILLS_DIR = path.join(FRAMEWORK_ROOT, '.claude', 'skills');
+/**
+ * The `node_modules/<package>` folder of the framework's own install, or the workspace's (a hoisted or linked
+ * install). Tools that need a package folder rather than a module (vite's config, pdfjs assets) use this.
+ */
+export function packageDir(packageName) {
+    // The package's own install, the pnpm virtual store that holds its dependencies, or a hoisted install in the workspace.
+    for (const base of [FRAMEWORK_ROOT, path.dirname(path.dirname(FRAMEWORK_ROOT)), ROOT]) {
+        const dir = path.join(base, 'node_modules', packageName);
+        if (fs.existsSync(dir))
+            return dir;
+    }
+    throw new Error(`Package "${packageName}" is not installed. Run "pnpm install" in the workspace root.`);
+}

package/dist/lib/pdf.d.ts

@@ -0,0 +1,71 @@
+type PdfJs = typeof import('pdfjs-dist/legacy/build/pdf.mjs');
+type PdfTask = ReturnType<PdfJs['getDocument']>;
+type PdfDoc = Awaited<PdfTask['promise']>;
+/** Which pages a check covers: all of them, the first, the last, or the listed 1-based page numbers. */
+export type PageSelection = 'all' | 'first' | 'last' | number[];
+/** A rectangle of the page in fractions (0 to 1) of its width and height, from the top-left corner. */
+export interface Region {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type Corner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/** A corner of the page. Defaults: 30% of the width and 12% of the height, enough for a logo and nothing else. */
+export declare function corner(name: Corner, size?: {
+    width?: number;
+    height?: number;
+}): Region;
+export declare function selectPages(selection: PageSelection, pageCount: number): number[];
+export interface RenderedRegion {
+    png: Buffer;
+    width: number;
+    height: number;
+    /** Share of pixels that are not (almost) white: 0 is a blank region. */
+    inkRatio: number;
+}
+export declare class PdfFile {
+    private readonly doc;
+    private readonly task;
+    readonly pageCount: number;
+    /** The text of each page, in reading order. */
+    readonly texts: string[];
+    constructor(doc: PdfDoc, task: PdfTask, pageCount: number, 
+    /** The text of each page, in reading order. */
+    texts: string[]);
+    /** Renders one page (or a region of it) to a PNG. Scale 2 is about 150 dpi. */
+    render(pageNumber: number, region?: Region, scale?: number): Promise<RenderedRegion>;
+    close(): Promise<void>;
+}
+export declare function openPdf(bytes: Buffer): Promise<PdfFile>;
+export interface PdfRegionCheck {
+    /** Short name of the check, used in messages and in the baseline file name (`<name>-p<page>.png`). Lower case words and dashes. */
+    name: string;
+    pages: PageSelection;
+    region: Region;
+    /** The region must show something (not blank). Default true. */
+    notBlank?: boolean;
+    /** Compare the region with the baseline image of the profile (2% tolerance). Default true. */
+    baseline?: boolean;
+}
+export interface PdfChecks {
+    regions?: PdfRegionCheck[];
+    /** Texts that must appear somewhere in the PDF (case-insensitive). */
+    textContains?: string[];
+    /** Texts that must not appear on any page (for example the names that belong to another profile). */
+    textNotContains?: string[];
+    /** At least this many pages. */
+    minPages?: number;
+    scale?: number;
+}
+/**
+ * The one way a spec checks the content of a downloaded PDF. For every region check it renders each selected page,
+ * fails when the region is blank, and compares the region with the profile's baseline image (the first run with
+ * `--update-snapshots` creates it; a person must look at it). Then it checks the extracted text.
+ * Every failure names the page and the check. Pair every call with `// target: T<n>` in the spec.
+ *
+ *   const pdf = await openPdf(file.bytes);
+ *   await expectPdf(pdf, {regions: [{name: 'logo', pages: 'first', region: corner('top-left')}], textNotContains: otherProfileNames});
+ */
+export declare function expectPdf(pdf: PdfFile, checks: PdfChecks): Promise<void>;
+export {};