@asrunjs/asrun 0.2.0 → 0.5.2

package/dist/lib/cases.d.ts

@@ -1,18 +1,5 @@
-/** The front matter of a case document that the tools care about. The case document is the single source of truth. */
-export interface CaseMeta {
-    id: string;
-    /** Suites the case belongs to, e.g. `['smoke', 'regression']`. A case runs in every suite it lists. */
-    suites: string[];
-    /**
-     * Environments in which the case may create or change data of the test accounts (and cleans it up), e.g.
-     * `['staging']`. Empty = the case never writes. In any other environment the case is skipped, not failed.
-     */
-    writes: string[];
-    /** What the case writes; required when `writes` is not empty. Shown to the person who confirms a production run. */
-    writesNote: string | null;
-    /** Environments the case may run in; `null` = all. */
-    envs: string[] | null;
-}
+import { type CaseMeta } from './case-doc.js';
+export type { CaseMeta } from './case-doc.js';
 /** Does the case write data at all (in some environment)? */
 export declare const caseWrites: (meta: CaseMeta) => boolean;
 /** May the case write data in this environment? A case that writes elsewhere only is skipped here. */

package/dist/lib/cases.js

@@ -1,93 +1,20 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { parse } from 'yaml';
+import { parseCaseFrontMatter, validateCaseMeta } from './case-doc.js';
 import { listEnvs } from './profiles.js';
-import { NAME_PATTERN } from './case-id.js';
 import { CASES_DIR } from './paths.js';
-const frontMatterOf = (text) => {
-    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
-    if (!match)
-        return null;
-    const value = parse(match[1]);
-    return value && typeof value === 'object' ? value : null;
-};
-function nameList(value, key, label) {
-    if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== 'string' || !NAME_PATTERN.test(item))) {
-        throw new Error(`${label}: "${key}" must be a list of lowercase words (letters, digits, dashes), e.g. "${key}: [smoke, regression]"`);
-    }
-    const duplicate = value.find((item, i) => value.indexOf(item) !== i);
-    if (duplicate)
-        throw new Error(`${label}: "${key}" lists "${duplicate}" twice`);
-    return value;
-}
-/**
- * `writes` is a list of environment names. Omitted, `none` or `[]` mean the case never writes. The old values
- * `test-data` (and `staging` / `production` as a bare word) are refused with the fix, never guessed.
- */
-function parseWrites(value, label) {
-    if (value === undefined || value === null || value === 'none')
-        return [];
-    if (value === 'test-data') {
-        throw new Error(`${label}: "writes: test-data" is the old form. List the environments instead, e.g. "writes: [staging]"`);
-    }
-    if (Array.isArray(value) && value.length === 0)
-        return [];
-    if (!Array.isArray(value)) {
-        throw new Error(`${label}: "writes" must be a list of environments, e.g. "writes: [staging]" (or omit it for read-only)`);
-    }
-    const writes = nameList(value, 'writes', label);
-    const known = listEnvs();
-    const unknown = writes.filter((env) => !known.includes(env));
-    if (unknown.length > 0) {
-        throw new Error(`${label}: unknown environment(s) in "writes": ${unknown.join(', ')}. Known: ${known.join(', ')}`);
-    }
-    return writes;
-}
 /** Does the case write data at all (in some environment)? */
 export const caseWrites = (meta) => meta.writes.length > 0;
 /** May the case write data in this environment? A case that writes elsewhere only is skipped here. */
 export const caseWritesIn = (meta, env) => meta.writes.includes(env);
 /** Parses and validates the front matter. Throws an Error that starts with `label` and says what to fix. */
 export function parseCaseMeta(id, text, label = `cases/${id}.md`) {
-    const front = frontMatterOf(text);
+    const front = parseCaseFrontMatter(text);
     if (!front)
         throw new Error(`${label}: the file must start with a front matter block (--- ... ---)`);
-    if (front.suites !== undefined && front.priority !== undefined) {
-        throw new Error(`${label}: use "suites: [...]" only; "priority" is the old name of the same setting`);
-    }
-    // `priority: smoke` is the old form of `suites: [smoke]`.
-    const suites = front.suites !== undefined
-        ? nameList(front.suites, 'suites', label)
-        : front.priority !== undefined
-            ? nameList([front.priority], 'priority', label)
-            : (() => {
-                throw new Error(`${label}: front matter needs "suites: [<suite>, ...]", e.g. "suites: [smoke, regression]"`);
-            })();
-    const note = front['writes-note'];
-    const writes = parseWrites(front.writes, label);
-    if (writes.length > 0 && (typeof note !== 'string' || note.trim() === '')) {
-        throw new Error(`${label}: "writes: [${writes.join(', ')}]" needs a "writes-note" that says what the case creates or changes`);
-    }
-    let envs = null;
-    if (front.envs !== undefined) {
-        envs = nameList(front.envs, 'envs', label);
-        const known = listEnvs();
-        const unknown = envs.filter((env) => !known.includes(env));
-        if (unknown.length > 0) {
-            throw new Error(`${label}: unknown environment(s) in "envs": ${unknown.join(', ')}. Known: ${known.join(', ')}`);
-        }
-    }
-    const unreachable = writes.filter((env) => envs !== null && !envs.includes(env));
-    if (unreachable.length > 0) {
-        throw new Error(`${label}: "writes" lists ${unreachable.join(', ')}, but "envs" does not run the case there`);
-    }
-    return {
-        id,
-        suites,
-        writes,
-        writesNote: typeof note === 'string' && note.trim() !== '' ? note.trim() : null,
-        envs,
-    };
+    if (front.problem)
+        throw new Error(`${label}: ${front.problem}`);
+    return validateCaseMeta(id, front.data, listEnvs(), label);
 }
 const caseFile = (caseId) => path.join(CASES_DIR, `${caseId}.md`);
 export const hasCaseFile = (caseId) => fs.existsSync(caseFile(caseId));

package/dist/lib/command.d.ts

@@ -0,0 +1,24 @@
+/**
+ * How a command on PATH is started: the executable itself, or, on Windows, a `.cmd`/`.bat` shim that only cmd.exe
+ * can run. A CLI installed globally with npm or pnpm is such a shim (it ends up as `opencode.cmd`), and `spawn`
+ * without a shell can never start it: the bare name is not found (ENOENT) and the shim itself is refused (EINVAL).
+ */
+export interface SpawnTarget {
+    /** The file to spawn. */
+    file: string;
+    args: string[];
+    /** The file that was found on PATH, for messages. */
+    path: string;
+    /** True when `file` is cmd.exe and `args` carry the quoted command line. */
+    throughShell: boolean;
+}
+/**
+ * The file a command starts. A path (absolute or with a separator) is taken as it is; anything else is looked up
+ * on PATH, trying PATHEXT on Windows, so `opencode` finds `opencode.cmd`. Returns null when nothing matches.
+ */
+export declare function findCommand(command: string): string | null;
+/**
+ * What to spawn for a command, or null when the command is not installed. Only a Windows shim goes through a shell;
+ * everything else is spawned directly, as before.
+ */
+export declare function spawnTarget(command: string, args?: string[]): SpawnTarget | null;

package/dist/lib/command.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** The extensions Windows would try when it looks a command up; PATHEXT normally lists them. */
+const WINDOWS_EXTENSIONS = ['.COM', '.EXE', '.BAT', '.CMD'];
+const pathEntries = () => (process.env.PATH ?? process.env.Path ?? '')
+    .split(path.delimiter)
+    .map((entry) => entry.trim().replace(/^"(.*)"$/, '$1'))
+    .filter((entry) => entry !== '');
+const windowsExtensions = () => {
+    const listed = (process.env.PATHEXT ?? '').split(';').filter((entry) => entry !== '');
+    return listed.length > 0 ? listed : WINDOWS_EXTENSIONS;
+};
+/** A file that exists and, off Windows, may be executed. */
+function executable(file) {
+    try {
+        if (!fs.statSync(file).isFile())
+            return false;
+        fs.accessSync(file, process.platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The file a command starts. A path (absolute or with a separator) is taken as it is; anything else is looked up
+ * on PATH, trying PATHEXT on Windows, so `opencode` finds `opencode.cmd`. Returns null when nothing matches.
+ */
+export function findCommand(command) {
+    if (path.isAbsolute(command) || command.includes('/') || command.includes('\\')) {
+        return executable(command) ? command : null;
+    }
+    const given = path.extname(command).toLowerCase();
+    const extensions = process.platform === 'win32'
+        ? windowsExtensions().some((extension) => extension.toLowerCase() === given)
+            ? ['']
+            : windowsExtensions()
+        : [''];
+    for (const dir of pathEntries()) {
+        for (const extension of extensions) {
+            const candidate = path.join(dir, command + extension);
+            if (executable(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/** MSVC quoting of one argument: a backslash is literal unless it comes right before a quote. */
+function quoteWindows(value) {
+    let quoted = '"';
+    let slashes = 0;
+    for (const char of value) {
+        if (char === '\\') {
+            slashes += 1;
+        }
+        else if (char === '"') {
+            quoted += `${'\\'.repeat(slashes * 2 + 1)}"`;
+            slashes = 0;
+        }
+        else {
+            quoted += '\\'.repeat(slashes) + char;
+            slashes = 0;
+        }
+    }
+    return `${quoted}${'\\'.repeat(slashes * 2)}"`;
+}
+/** A `.cmd`/`.bat` shim, started through cmd.exe the way npm's own shims are: one command line, every part quoted. */
+function shimTarget(file, args) {
+    // cmd.exe takes a single line, so a line break inside an argument would end the command.
+    const line = [file, ...args].map((value) => quoteWindows(value.replace(/[\r\n]+/g, ' '))).join(' ');
+    // `/s` strips exactly one pair of outer quotes, so the whole line is wrapped once more.
+    return {
+        file: process.env.ComSpec ?? 'cmd.exe',
+        args: ['/d', '/s', '/c', `"${line}"`],
+        path: file,
+        throughShell: true,
+    };
+}
+/**
+ * What to spawn for a command, or null when the command is not installed. Only a Windows shim goes through a shell;
+ * everything else is spawned directly, as before.
+ */
+export function spawnTarget(command, args = []) {
+    const found = findCommand(command);
+    if (found === null)
+        return null;
+    if (process.platform === 'win32' && /\.(cmd|bat)$/i.test(found))
+        return shimTarget(found, args);
+    return { file: found, args, path: found, throughShell: false };
+}

package/dist/lib/fixtures.js

@@ -5,7 +5,7 @@ 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, isLoginUrl, parseNotLoggedIn, sessionProblemMessage, signinCommand, } from './session.js';
+import { checkSession, isLoggedOutUrl, parseNotLoggedIn, sessionProblemMessage, signinCommand, } from './session.js';
 export const test = base.extend({
     profile: [
         async ({}, use, workerInfo) => {
@@ -125,7 +125,7 @@ export const test = base.extend({
             if (!mustLogin || testInfo.status === testInfo.expectedStatus) {
                 return;
             }
-            if (page.isClosed() || !isLoginUrl(page.url())) {
+            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)}`;

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

@@ -1,6 +1,10 @@
 /**
- * Arguments that run one of the framework's own scripts (for example `login.ts`): the compiled file when the package
- * is built, the TypeScript source in the framework repository.
+ * 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[];
 /**

package/dist/lib/node-cli.js

@@ -2,14 +2,24 @@ 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 compiled file when the package
- * is built, the TypeScript source in the framework repository.
+ * 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 compiled = path.join(FRAMEWORK_ROOT, 'dist', 'scripts', name.replace(/\.ts$/, '.js'));
-    if (fs.existsSync(compiled))
-        return [compiled];
-    return [commandScript('tsx'), path.join(FRAMEWORK_ROOT, 'scripts', 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

package/dist/lib/profiles.d.ts

@@ -1,3 +1,22 @@
+export declare const DEFAULT_SESSION_CHECK_PATH = "/account/";
+/** The page "Visit" opens by default: the site root. */
+export declare const DEFAULT_START_PATH = "";
+/**
+ * How to tell "signed in" from "signed out" on one site. A site can say it in different ways: a redirect to
+ * a login page (server or client side), a 401/403, a login form on the same address, or a "you must sign in"
+ * message. Every profile names the signal it has; the defaults cover the most common one, a redirect to `/login`.
+ */
+export interface SessionCheck {
+    /** The address a visitor without a valid session is sent to: a path on the site, or a full URL (single sign-on). */
+    loggedOutUrl: string;
+    /** A selector that is only on the page while signed in, e.g. the username in the top bar. The most reliable signal. */
+    loggedInSelector: string | null;
+    /** A selector that shows the visitor is not signed in, e.g. the password field of the login form. */
+    loggedOutSelector: string | null;
+    /** How long to wait for one of those signals before closing the page again. */
+    timeoutMs: number;
+}
+export declare const DEFAULT_SESSION_CHECK: SessionCheck;
 export declare const PRODUCTION = "production";
 export declare const STAGING = "staging";
 export declare const PROFILES_FILE: string;
@@ -17,8 +36,12 @@ export interface Profile {
     tags: string[];
     /** Tests may send real email in this environment. Never true in production. */
     email: boolean;
-    /** A page that redirects to /login when the session is missing or expired. */
+    /** The page "Visit" opens after a login, e.g. `/app/home`; empty = the site root. */
+    startPath: string;
+    /** A page that only a signed-in visitor sees; the page "Verify" opens. */
     sessionCheckPath: string;
+    /** How that page shows a missing or expired login (see `SessionCheck`). */
+    sessionCheck: SessionCheck;
 }
 /** The Playwright project name of a profile: its id. */
 export declare const projectName: (profile: {
@@ -28,6 +51,7 @@ export declare const profileLabel: (profile: {
     id: string;
     env: string;
 }) => string;
+export declare function validateSessionCheck(where: string, raw: unknown): SessionCheck;
 export declare function loadProfiles(file?: string): Profile[];
 /** The profiles of one environment (`env` omitted: all of them), production first. */
 export declare const listProfiles: (env?: string, profiles?: Profile[]) => Profile[];

package/dist/lib/profiles.js

@@ -3,7 +3,15 @@ import path from 'node:path';
 import { parse } from 'yaml';
 import { ROOT } from './paths.js';
 const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-const DEFAULT_SESSION_CHECK_PATH = '/account/';
+export const DEFAULT_SESSION_CHECK_PATH = '/account/';
+/** The page "Visit" opens by default: the site root. */
+export const DEFAULT_START_PATH = '';
+export const DEFAULT_SESSION_CHECK = {
+    loggedOutUrl: '/login',
+    loggedInSelector: null,
+    loggedOutSelector: null,
+    timeoutMs: 3000,
+};
 export const PRODUCTION = 'production';
 export const STAGING = 'staging';
 export const PROFILES_FILE = path.join(ROOT, 'profiles.yaml');
@@ -34,6 +42,44 @@ function validateSiteAddress(where, value) {
     }
     return value.replace(/\/$/, '');
 }
+export function validateSessionCheck(where, raw) {
+    if (raw === undefined || raw === null)
+        return DEFAULT_SESSION_CHECK;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`${where}: "sessionCheck" must be a mapping with "loggedOutUrl", "loggedInSelector", "loggedOutSelector" or "timeoutMs"`);
+    }
+    const map = raw;
+    const known = ['loggedOutUrl', 'loggedInSelector', 'loggedOutSelector', 'timeoutMs'];
+    const unknown = Object.keys(map).find((key) => !known.includes(key));
+    if (unknown) {
+        throw new Error(`${where}: "sessionCheck" has an unknown key "${unknown}". Known: ${known.join(', ')}`);
+    }
+    const loggedOutUrl = map.loggedOutUrl ?? DEFAULT_SESSION_CHECK.loggedOutUrl;
+    if (typeof loggedOutUrl !== 'string' ||
+        (!loggedOutUrl.startsWith('/') && !/^https?:\/\//i.test(loggedOutUrl)) ||
+        /\s/.test(loggedOutUrl)) {
+        throw new Error(`${where}: "sessionCheck.loggedOutUrl" must be a path starting with "/" (e.g. /login) or a full http(s) URL`);
+    }
+    const selector = (key) => {
+        const value = map[key];
+        if (value === undefined || value === null || value === '')
+            return null;
+        if (typeof value !== 'string') {
+            throw new Error(`${where}: "sessionCheck.${key}" must be a selector such as "input[name='username']"`);
+        }
+        return value;
+    };
+    const timeoutMs = map.timeoutMs ?? DEFAULT_SESSION_CHECK.timeoutMs;
+    if (typeof timeoutMs !== 'number' || !Number.isInteger(timeoutMs) || timeoutMs < 500 || timeoutMs > 60000) {
+        throw new Error(`${where}: "sessionCheck.timeoutMs" must be a whole number of milliseconds between 500 and 60000`);
+    }
+    return {
+        loggedOutUrl,
+        loggedInSelector: selector('loggedInSelector'),
+        loggedOutSelector: selector('loggedOutSelector'),
+        timeoutMs,
+    };
+}
 function validate(raw, index) {
     const label = `profiles.yaml: profile #${index + 1}`;
     for (const key of ['id', 'name', 'env']) {
@@ -68,6 +114,11 @@ function validate(raw, index) {
     if (typeof sessionCheckPath !== 'string' || !sessionCheckPath.startsWith('/') || /\s/.test(sessionCheckPath)) {
         throw new Error(`${where}: "sessionCheckPath" must start with "/" and contain no spaces`);
     }
+    const startPath = raw.startPath ?? DEFAULT_START_PATH;
+    if (typeof startPath !== 'string' ||
+        (startPath !== '' && (!startPath.startsWith('/') || startPath.startsWith('//') || /\s/.test(startPath)))) {
+        throw new Error(`${where}: "startPath" must be empty (the site root) or a path on the site that starts with a single "/" and has no spaces`);
+    }
     const account = typeof raw.account === 'string' && raw.account.trim() !== '' ? raw.account.trim() : null;
     return {
         id: raw.id,
@@ -77,7 +128,9 @@ function validate(raw, index) {
         account,
         tags: validateTags(where, raw.tags),
         email: raw.email === true,
+        startPath,
         sessionCheckPath,
+        sessionCheck: validateSessionCheck(where, raw.sessionCheck),
     };
 }
 export function loadProfiles(file = PROFILES_FILE) {