@sdods/core 0.3.1 → 0.5.1

package/dist/api/client.d.ts

@@ -1,5 +1,6 @@
-import type { APIRequestContext, TestInfo } from '@playwright/test';
+import type { APIRequest, APIRequestContext, TestInfo } from '@playwright/test';
 import { type ApiSnapshot } from '@sdods/contracts';
+import type { ApiAuthConfig } from '@sdods/contracts';
 import type { ResolvedConfig } from '../config/resolve.js';
 import type { ApiContext } from '../fixtures/api-context.js';
 import type { ScenarioMeta } from '../fixtures/scenario.js';
@@ -18,6 +19,11 @@ export interface ApiRequestOptions {
 }
 export interface ApiClientDeps {
     request: APIRequestContext;
+    /**
+     * A request context with no cookie jar, used while `ctx.isolated` is set. The `api` fixture
+     * creates it lazily (see {@link isolatedRequestFactory}) and disposes it at teardown.
+     */
+    isolatedRequest?: () => Promise<APIRequestContext>;
     config: ResolvedConfig;
     ctx: ApiContext;
     testInfo?: TestInfo;
@@ -46,8 +52,63 @@ export declare class ApiClient {
     patch(path: string, opts?: ApiRequestOptions): Promise<ApiSnapshot>;
     delete(path: string, opts?: ApiRequestOptions): Promise<ApiSnapshot>;
     resolveUrl(path: string, query?: Record<string, string | number | boolean>): string;
+    /**
+     * The request context this scenario's calls go through.
+     *
+     * The shared `request` fixture is seeded from the test's context options, which on @ui/@hybrid
+     * include the leased role's storageState — so every call also carries that session cookie, and
+     * whatever cookies earlier responses set. `ctx.isolated` swaps in a context with an empty jar.
+     */
+    requestContext(): Promise<APIRequestContext>;
     private buildHeaders;
     send(method: HttpMethod, path: string, opts?: ApiRequestOptions): Promise<ApiSnapshot>;
     private recordAndAttach;
 }
+/**
+ * The bytes to send.
+ *
+ * A string goes out as a Buffer, never as Playwright's `data: string`: when the content-type is
+ * exactly `application/json`, Playwright runs `JSON.stringify` over any string that does not parse,
+ * so `{ this is not json` arrived as the valid JSON string `"{ this is not json"` and a server's
+ * malformed-body branch could never be reached. Objects are serialised here, once.
+ */
+export declare function encodeBody(body: unknown): Buffer | undefined;
+/**
+ * Which credential a request carries. `null` at either level means "send this unauthenticated";
+ * only `undefined` falls through to the next layer, so a scenario can opt out of the environment
+ * credential without the environment having to know.
+ */
+export declare function resolveAuth(optsAuth: ApiContext['auth'] | undefined, ctxAuth: ApiContext['auth'], env: ApiAuthConfig): Promise<ApiContext['auth']>;
+export declare function applyAuth(headers: Record<string, string>, auth: ApiContext['auth']): void;
+/**
+ * The environment credential. Every type the schema accepts is either implemented or refused:
+ * returning `undefined` for an unhandled type sent every request anonymous with no warning, and
+ * an authorization scenario against an endpoint that answers anonymous reads passed while
+ * proving nothing.
+ */
+export declare function envAuth(auth: ApiAuthConfig): Promise<ApiContext['auth']>;
+type ClientCredentialsAuth = Extract<ApiAuthConfig, {
+    type: 'oauth-client-credentials';
+}>;
+/**
+ * OAuth 2.0 client-credentials grant (RFC 6749 §4.4), cached per worker process until shortly
+ * before `expires_in`. A response without `expires_in` is cached for the life of the worker.
+ * Concurrent callers share one in-flight request.
+ */
+export declare function clientCredentialsToken(auth: ClientCredentialsAuth): Promise<string>;
+/** Test/teardown hook: forget cached client-credentials tokens. */
+export declare function clearClientCredentialsTokens(): void;
+/**
+ * A lazily created request context with an EMPTY cookie jar, for `I use an isolated API client`.
+ *
+ * The options are explicit rather than omitted: inside the test runner Playwright fills in any
+ * context option whose key is absent from the test's `use` (storageState — the role's session —
+ * httpCredentials, extraHTTPHeaders), so an omitted storageState would quietly bring the jar back.
+ * Transport settings (baseURL, proxy, ignoreHTTPSErrors, client certificates) still apply.
+ */
+export declare function isolatedRequestFactory(playwrightRequest: Pick<APIRequest, 'newContext'>): {
+    get: () => Promise<APIRequestContext>;
+    dispose: () => Promise<void>;
+};
+export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/api/client.js

@@ -1,5 +1,6 @@
 import { writeFileSync } from 'node:fs';
 import { attachmentNames, scenarioFiles } from '@sdods/contracts';
+import { SdodsError } from '../errors.js';
 import { Logger, redact } from '../logger.js';
 const REDACT_HEADERS = /^(authorization|cookie|set-cookie|x-api-key|proxy-authorization)$/i;
 /**
@@ -43,6 +44,23 @@ export class ApiClient {
                 url.searchParams.set(k, String(v));
         return url.toString();
     }
+    /**
+     * The request context this scenario's calls go through.
+     *
+     * The shared `request` fixture is seeded from the test's context options, which on @ui/@hybrid
+     * include the leased role's storageState — so every call also carries that session cookie, and
+     * whatever cookies earlier responses set. `ctx.isolated` swaps in a context with an empty jar.
+     */
+    async requestContext() {
+        if (!this.deps.ctx.isolated)
+            return this.deps.request;
+        if (!this.deps.isolatedRequest) {
+            throw new SdodsError('NOT_SUPPORTED', 'This API client was built without an isolated request context, so it cannot honour `I use an isolated API client`.', {
+                hint: 'Use the `api` fixture from @sdods/core, or pass `isolatedRequest` when constructing ApiClient yourself.',
+            });
+        }
+        return this.deps.isolatedRequest();
+    }
     buildHeaders(opts) {
         const env = this.deps.config.env.api;
         const headers = {
@@ -53,21 +71,6 @@ export class ApiClient {
         };
         if (opts.body !== undefined && !headers['content-type'] && !opts.form)
             headers['content-type'] = 'application/json';
-        // `null` at either level means "send this unauthenticated". Only `undefined`
-        // falls through to the next layer, so a scenario can opt out of the
-        // environment credential without the environment having to know.
-        const ctxAuth = this.deps.ctx.auth;
-        const auth = opts.auth === null
-            ? undefined
-            : (opts.auth ?? (ctxAuth === null ? undefined : (ctxAuth ?? envAuth(env.auth))));
-        if (auth) {
-            if (auth.type === 'bearer')
-                headers.authorization = `Bearer ${auth.token}`;
-            else if (auth.type === 'basic')
-                headers.authorization = `Basic ${Buffer.from(`${auth.username}:${auth.password}`).toString('base64')}`;
-            else if (auth.type === 'header')
-                headers[auth.name.toLowerCase()] = auth.value;
-        }
         return headers;
     }
     async send(method, path, opts = {}) {
@@ -81,10 +84,11 @@ export class ApiClient {
             method,
             url,
             headers: redactHeaders(headers),
-            body: opts.form ?? opts.body,
+            body: opts.form ?? (Buffer.isBuffer(opts.body) ? opts.body.toString('utf8') : opts.body),
             query: opts.query
                 ? Object.fromEntries(Object.entries(opts.query).map(([k, v]) => [k, String(v)]))
                 : undefined,
+            ...(this.deps.ctx.isolated ? { isolated: true } : {}),
         };
         // HAR replay (API layer playback)
         if (this.deps.har?.replay) {
@@ -103,21 +107,26 @@ export class ApiClient {
             if (this.deps.har.strict)
                 throw new Error(`HAR strict mode: no recorded entry for ${method} ${url}`);
         }
+        // Resolved after HAR replay (a replayed call sends nothing, so an offline replay must not need
+        // to mint a token) and before the attempt loop: a credential that cannot be obtained is a
+        // configuration failure, not a transient one to retry, and the request must not go out
+        // without it.
+        const auth = await resolveAuth(opts.auth, this.deps.ctx.auth, this.deps.config.env.api.auth);
+        applyAuth(headers, auth);
+        requestSnap.headers = redactHeaders(headers);
+        // Which credential class went out, never its value — so a report shows at a glance whether a
+        // scenario sent a bearer, a key header, or nothing.
+        requestSnap.auth = describeAuth(auth);
+        const request = await this.requestContext();
         let lastError;
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
             const t0 = Date.now();
             try {
-                this.log.step(`→ ${method} ${url}`, opts.body !== undefined ? { body: opts.body } : undefined);
-                const res = await this.deps.request.fetch(url, {
+                this.log.step(`→ ${method} ${url}`, opts.body !== undefined ? { body: requestSnap.body } : undefined);
+                const res = await request.fetch(url, {
                     method,
                     headers,
-                    data: opts.form
-                        ? undefined
-                        : opts.body === undefined
-                            ? undefined
-                            : typeof opts.body === 'string'
-                                ? opts.body
-                                : JSON.stringify(opts.body),
+                    data: opts.form ? undefined : encodeBody(opts.body),
                     form: opts.form,
                     timeout,
                     failOnStatusCode: false,
@@ -191,16 +200,169 @@ function lower(h) {
 function redactHeaders(h) {
     return Object.fromEntries(Object.entries(h).map(([k, v]) => [k, REDACT_HEADERS.test(k) ? '***' : v]));
 }
-function envAuth(auth) {
+/**
+ * The bytes to send.
+ *
+ * A string goes out as a Buffer, never as Playwright's `data: string`: when the content-type is
+ * exactly `application/json`, Playwright runs `JSON.stringify` over any string that does not parse,
+ * so `{ this is not json` arrived as the valid JSON string `"{ this is not json"` and a server's
+ * malformed-body branch could never be reached. Objects are serialised here, once.
+ */
+export function encodeBody(body) {
+    if (body === undefined)
+        return undefined;
+    if (Buffer.isBuffer(body))
+        return body;
+    return Buffer.from(typeof body === 'string' ? body : JSON.stringify(body), 'utf8');
+}
+/**
+ * Which credential a request carries. `null` at either level means "send this unauthenticated";
+ * only `undefined` falls through to the next layer, so a scenario can opt out of the environment
+ * credential without the environment having to know.
+ */
+export async function resolveAuth(optsAuth, ctxAuth, env) {
+    if (optsAuth === null)
+        return undefined;
+    if (optsAuth)
+        return optsAuth;
+    if (ctxAuth === null)
+        return undefined;
+    return ctxAuth ?? envAuth(env);
+}
+export function applyAuth(headers, auth) {
+    if (!auth)
+        return;
+    if (auth.type === 'bearer')
+        headers.authorization = `Bearer ${auth.token}`;
+    else if (auth.type === 'basic')
+        headers.authorization = `Basic ${Buffer.from(`${auth.username}:${auth.password}`).toString('base64')}`;
+    else if (auth.type === 'header')
+        headers[auth.name.toLowerCase()] = auth.value;
+}
+function describeAuth(auth) {
+    if (!auth)
+        return 'none';
+    return auth.type === 'header' ? `header:${auth.name.toLowerCase()}` : auth.type;
+}
+/**
+ * The environment credential. Every type the schema accepts is either implemented or refused:
+ * returning `undefined` for an unhandled type sent every request anonymous with no warning, and
+ * an authorization scenario against an endpoint that answers anonymous reads passed while
+ * proving nothing.
+ */
+export async function envAuth(auth) {
     switch (auth.type) {
+        case 'none':
+            return undefined;
         case 'bearer':
             return { type: 'bearer', token: auth.token };
         case 'basic':
             return { type: 'basic', username: auth.username, password: auth.password };
         case 'header':
             return { type: 'header', name: auth.name, value: auth.value };
+        case 'oauth-client-credentials':
+            return { type: 'bearer', token: await clientCredentialsToken(auth) };
         default:
-            return undefined;
+            throw new SdodsError('NOT_SUPPORTED', `env.api.auth type "${auth.type}" is not supported by the API client.`, {
+                hint: 'Use one of none, bearer, basic, header or oauth-client-credentials, or set the credential per scenario with `I authenticate with bearer token from "<VAR>"`.',
+                exitCode: 2,
+            });
+    }
+}
+/** Tokens are refreshed this long before they expire, so a request never races the expiry. */
+const TOKEN_EXPIRY_SKEW_MS = 30_000;
+const tokenCache = new Map();
+/**
+ * OAuth 2.0 client-credentials grant (RFC 6749 §4.4), cached per worker process until shortly
+ * before `expires_in`. A response without `expires_in` is cached for the life of the worker.
+ * Concurrent callers share one in-flight request.
+ */
+export async function clientCredentialsToken(auth) {
+    const key = [auth.tokenUrl, auth.clientId, auth.scope ?? '', auth.audience ?? ''].join('\n');
+    const cached = tokenCache.get(key);
+    if (cached) {
+        const hit = await cached.catch(() => undefined);
+        if (hit && hit.expiresAt > Date.now())
+            return hit.token;
+        if (tokenCache.get(key) === cached)
+            tokenCache.delete(key);
+    }
+    const pending = mintClientCredentialsToken(auth);
+    tokenCache.set(key, pending);
+    try {
+        return (await pending).token;
+    }
+    catch (e) {
+        if (tokenCache.get(key) === pending)
+            tokenCache.delete(key);
+        throw e;
+    }
+}
+async function mintClientCredentialsToken(auth) {
+    const body = new URLSearchParams({
+        grant_type: 'client_credentials',
+        client_id: auth.clientId,
+        client_secret: auth.clientSecret,
+    });
+    if (auth.scope)
+        body.set('scope', auth.scope);
+    if (auth.audience)
+        body.set('audience', auth.audience);
+    const hint = `Check tokenUrl, clientId and clientSecret in env.api.auth (secrets as \${VAR}).`;
+    let res;
+    try {
+        res = await fetch(auth.tokenUrl, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+                accept: 'application/json',
+            },
+            body,
+        });
+    }
+    catch (cause) {
+        throw new SdodsError('AUTH_FAILED', `OAuth token request to ${auth.tokenUrl} failed: ${cause.message}`, { hint, cause });
+    }
+    if (!res.ok) {
+        throw new SdodsError('AUTH_FAILED', `OAuth token request to ${auth.tokenUrl} was refused: ${res.status} ${res.statusText}`, { hint });
+    }
+    const json = (await res.json().catch(() => ({})));
+    if (typeof json.access_token !== 'string' || !json.access_token) {
+        throw new SdodsError('AUTH_FAILED', `OAuth token response from ${auth.tokenUrl} has no access_token.`, { hint });
     }
+    const expiresIn = Number(json.expires_in);
+    const expiresAt = Number.isFinite(expiresIn)
+        ? Date.now() + expiresIn * 1000 - TOKEN_EXPIRY_SKEW_MS
+        : Number.POSITIVE_INFINITY;
+    return { token: json.access_token, expiresAt };
+}
+/** Test/teardown hook: forget cached client-credentials tokens. */
+export function clearClientCredentialsTokens() {
+    tokenCache.clear();
+}
+/**
+ * A lazily created request context with an EMPTY cookie jar, for `I use an isolated API client`.
+ *
+ * The options are explicit rather than omitted: inside the test runner Playwright fills in any
+ * context option whose key is absent from the test's `use` (storageState — the role's session —
+ * httpCredentials, extraHTTPHeaders), so an omitted storageState would quietly bring the jar back.
+ * Transport settings (baseURL, proxy, ignoreHTTPSErrors, client certificates) still apply.
+ */
+export function isolatedRequestFactory(playwrightRequest) {
+    let pending;
+    return {
+        get: () => (pending ??= playwrightRequest.newContext({
+            storageState: { cookies: [], origins: [] },
+            httpCredentials: undefined,
+            extraHTTPHeaders: undefined,
+        })),
+        dispose: async () => {
+            if (!pending)
+                return;
+            const ctx = await pending.catch(() => undefined);
+            pending = undefined;
+            await ctx?.dispose();
+        },
+    };
 }
 //# sourceMappingURL=client.js.map

package/dist/api/template.d.ts

@@ -1,9 +1,22 @@
+type Scopes = Array<Record<string, unknown> | undefined>;
 /**
  * Render `{{name}}` / `{{obj.path}}` placeholders. Values are looked up in order over the given
  * scopes (first wins). `${VAR}` env references are left untouched (config already resolved them).
+ * A placeholder with no value is left as the literal `{{name}}`; use `renderStrict` wherever that
+ * literal could be matched instead of failing.
  */
-export declare function render(template: string, ...scopes: Array<Record<string, unknown> | undefined>): string;
+export declare function render(template: string, ...scopes: Scopes): string;
+/**
+ * `render`, but a placeholder that resolves to nothing throws `no such variable: <name>` instead
+ * of surviving as the literal `{{name}}`. Every built-in step renders its string arguments through
+ * this: a literal placeholder can never appear in a URL, a title or a response, so a positive
+ * assertion on it fails for the wrong reason and a negative one ("should not contain") passes
+ * without testing anything. Only the template's own placeholders are checked, so a variable whose
+ * value happens to contain `{{…}}` is not mistaken for a miss.
+ */
+export declare function renderStrict(template: string, ...scopes: Scopes): string;
 export declare function hasTemplate(s: string): boolean;
 /** Render a JSON doc string, keeping types for whole-value placeholders (`"id": {{postId}}`). */
-export declare function renderJson(template: string, ...scopes: Array<Record<string, unknown> | undefined>): unknown;
+export declare function renderJson(template: string, ...scopes: Scopes): unknown;
+export {};
 //# sourceMappingURL=template.d.ts.map

package/dist/api/template.js

@@ -1,9 +1,38 @@
+import { SdodsError } from '../errors.js';
 const TPL_RE = /\{\{\s*([A-Za-z_][\w.]*)\s*\}\}/g;
 /**
  * Render `{{name}}` / `{{obj.path}}` placeholders. Values are looked up in order over the given
  * scopes (first wins). `${VAR}` env references are left untouched (config already resolved them).
+ * A placeholder with no value is left as the literal `{{name}}`; use `renderStrict` wherever that
+ * literal could be matched instead of failing.
  */
 export function render(template, ...scopes) {
+    return substitute(template, scopes, []);
+}
+/**
+ * `render`, but a placeholder that resolves to nothing throws `no such variable: <name>` instead
+ * of surviving as the literal `{{name}}`. Every built-in step renders its string arguments through
+ * this: a literal placeholder can never appear in a URL, a title or a response, so a positive
+ * assertion on it fails for the wrong reason and a negative one ("should not contain") passes
+ * without testing anything. Only the template's own placeholders are checked, so a variable whose
+ * value happens to contain `{{…}}` is not mistaken for a miss.
+ */
+export function renderStrict(template, ...scopes) {
+    const missing = [];
+    const out = substitute(template, scopes, missing);
+    if (missing.length > 0) {
+        const names = [...new Set(missing)];
+        throw new SdodsError('CONFIG_UNRESOLVED_VAR', `no such variable: ${names.join(', ')} (in "${template}").`, {
+            hint: 'No scenario variable or env var of that name exists yet. Save it first (for example with "I save the response JSON path ... as ..."), or fix the spelling. The step refuses to match the literal placeholder, which would fail for the wrong reason or, in a negative assertion, pass without testing anything.',
+            details: { missing: names, template },
+        });
+    }
+    return out;
+}
+export function hasTemplate(s) {
+    return TPL_RE.test(s) && ((TPL_RE.lastIndex = 0), true);
+}
+function substitute(template, scopes, missing) {
     return template.replace(TPL_RE, (_m, name) => {
         for (const scope of scopes) {
             if (!scope)
@@ -12,12 +41,10 @@ export function render(template, ...scopes) {
             if (v !== undefined)
                 return typeof v === 'string' ? v : JSON.stringify(v);
         }
+        missing.push(name);
         return `{{${name}}}`;
     });
 }
-export function hasTemplate(s) {
-    return TPL_RE.test(s) && ((TPL_RE.lastIndex = 0), true);
-}
 function lookup(scope, name) {
     if (name in scope)
         return scope[name];
@@ -27,16 +54,7 @@ function lookup(scope, name) {
 }
 /** Render a JSON doc string, keeping types for whole-value placeholders (`"id": {{postId}}`). */
 export function renderJson(template, ...scopes) {
-    const text = template.replace(TPL_RE, (_m, name) => {
-        for (const scope of scopes) {
-            if (!scope)
-                continue;
-            const v = lookup(scope, name);
-            if (v !== undefined)
-                return typeof v === 'string' ? v : JSON.stringify(v);
-        }
-        return `{{${name}}}`;
-    });
+    const text = substitute(template, scopes, []);
     try {
         return JSON.parse(text);
     }

package/dist/auth/capture.js

@@ -1,8 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { pathToFileURL } from 'node:url';
 import { join } from 'node:path';
 import { execa } from 'execa';
 import { SdodsError } from '../errors.js';
+import { importProjectModule, namedExport } from '../load-module.js';
 import { Logger } from '../logger.js';
 import { CompositeDataProvider } from '../data/provider.js';
 import { AuthStateCache } from '../fixtures/auth.js';
@@ -52,8 +52,9 @@ export async function loadProjectAuth(config) {
     for (const file of candidates) {
         if (!existsSync(file))
             continue;
-        const mod = (await import(pathToFileURL(file).href));
-        const strategy = mod.auth ?? mod.default;
+        // Same module resolution as `sdods run` (#86): `import './helper.js'` must find helper.ts.
+        const mod = await importProjectModule(file);
+        const strategy = namedExport(mod, 'auth') ?? mod.default;
         if (strategy && typeof strategy.login === 'function')
             return strategy;
     }

package/dist/auth/index.js

@@ -1,5 +1,6 @@
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { clientCredentialsToken } from '../api/client.js';
 import { SdodsError } from '../errors.js';
 /**
  * Define the project's auth strategy. `form` uses `auth.form` selectors from the project yaml
@@ -48,28 +49,12 @@ export function defineAuth(def) {
             return {
                 strategy: 'oauth-client-credentials',
                 login: async () => undefined,
+                // One implementation (and one cache) shared with ApiClient's `env.api.auth`.
                 token: async ({ config }) => {
                     const auth = config.env.api.auth;
                     if (auth.type !== 'oauth-client-credentials')
                         return undefined;
-                    const body = new URLSearchParams({
-                        grant_type: 'client_credentials',
-                        client_id: auth.clientId,
-                        client_secret: auth.clientSecret,
-                    });
-                    if (auth.scope)
-                        body.set('scope', auth.scope);
-                    if (auth.audience)
-                        body.set('audience', auth.audience);
-                    const res = await fetch(auth.tokenUrl, {
-                        method: 'POST',
-                        headers: { 'content-type': 'application/x-www-form-urlencoded' },
-                        body,
-                    });
-                    if (!res.ok)
-                        throw new Error(`OAuth token request failed: ${res.status} ${res.statusText}`);
-                    const json = (await res.json());
-                    return json.access_token;
+                    return clientCredentialsToken(auth);
                 },
             };
         case 'sso':

package/dist/config/defaults.js

@@ -31,6 +31,8 @@ export const ENV_TO_CONFIG_PATH = {
     SDODS_SHOT_POLICY: 'project.screenshots.policy.default',
     SDODS_SHOTS_ONLY_ON_FAILURE: 'project.screenshots.onlyOnFailure',
     SDODS_HEAL: 'project.heal.enabled',
+    SDODS_TRACE: 'project.evidence.trace',
+    SDODS_VIDEO: 'project.evidence.video',
     SDODS_HAR_MODE: 'runtime.harMode',
     SDODS_OFFLINE: 'runtime.offline',
     SDODS_UPDATE_SNAPSHOTS: 'runtime.updateSnapshots',

package/dist/config/resolve.d.ts

@@ -1,5 +1,5 @@
 import { ZodError } from 'zod';
-import { type EnvConfig, type ProjectConfig } from '@sdods/contracts';
+import { type EnvConfig, type EvidenceConfig, type ProjectConfig } from '@sdods/contracts';
 import { SdodsConfigError } from '../errors.js';
 import { type LayerName } from './merge.js';
 export type HarMode = 'off' | 'update' | 'replay';
@@ -37,6 +37,10 @@ export interface CliOverrides {
     shotPolicy?: string;
     shotsOnlyOnFailure?: boolean;
     heal?: boolean;
+    /** Playwright trace mode (`evidence.trace`), e.g. `on` to get a trace without a retry. */
+    trace?: EvidenceConfig['trace'];
+    /** Playwright video mode (`evidence.video`). */
+    video?: EvidenceConfig['video'];
 }
 export interface ResolvedConfig {
     project: ProjectConfig & {

package/dist/config/resolve.js

@@ -93,7 +93,7 @@ export function resolveConfig(opts) {
     markAll(envYaml, prov, 'envYaml', 'env');
     // env-level overrides of project sections
     let projectMerged = project;
-    for (const section of ['screenshots', 'heal', 'timeouts', 'perf']) {
+    for (const section of ['screenshots', 'heal', 'timeouts', 'perf', 'evidence']) {
         const patch = envYaml[section];
         if (patch) {
             projectMerged = {
@@ -154,8 +154,19 @@ export function resolveConfig(opts) {
     rt.offline = Boolean(rt.offline);
     rt.updateSnapshots = Boolean(rt.updateSnapshots);
     // final validation (env may have been overridden by process/cli)
-    const envFinal = EnvConfigSchema.parse(interpolated.env);
-    const projectFinal = ProjectConfigSchema.parse(interpolated.project);
+    let envFinal;
+    let projectFinal;
+    try {
+        envFinal = EnvConfigSchema.parse(interpolated.env);
+        projectFinal = ProjectConfigSchema.parse(interpolated.project);
+    }
+    catch (e) {
+        // ${VAR} values, SDODS_* variables and CLI flags land after the file validation
+        // (SDODS_TRACE=sometimes); name the path instead of throwing a raw ZodError.
+        if (e instanceof ZodError)
+            throw zodToConfigError(e, `${opts.projectRoot} after \${VAR}, SDODS_* and CLI overrides`);
+        throw e;
+    }
     return {
         project: { ...projectFinal, root: resolvePath(opts.projectRoot) },
         env: envFinal,
@@ -197,6 +208,8 @@ function applyCli(tree, cli, prov) {
     set('project.screenshots.policy.default', cli.shotPolicy);
     set('project.screenshots.onlyOnFailure', cli.shotsOnlyOnFailure);
     set('project.heal.enabled', cli.heal);
+    set('project.evidence.trace', cli.trace);
+    set('project.evidence.video', cli.video);
 }
 /** Config paths that are booleans: `SDODS_X=1|true|yes|on` → true, `0|false|no|off` → false. */
 const BOOLEAN_PATHS = new Set([

package/dist/config/runner.d.ts

@@ -1,5 +1,5 @@
 import { type PlaywrightTestConfig } from '@playwright/test';
-import { type BrowserName, type Layer } from '@sdods/contracts';
+import { type BrowserName, type Layer, type ProcessConfig, type ProjectConfig, type SetupConfig } from '@sdods/contracts';
 import type { ProjectRegistry } from './registry.js';
 export interface RunnerSelection {
     project?: string;
@@ -12,7 +12,10 @@ export interface RunnerSelection {
     allure?: boolean;
     reporters?: string[];
     reporterMode?: 'default' | 'server' | 'quiet';
+    /** Named process (`--process`): its `fullyParallel` and `setup` override the project's. */
+    process?: string;
 }
+type RunnerProject = NonNullable<PlaywrightTestConfig['projects']>[number];
 export interface SdodsUseOption {
     project: string;
     layer: Layer;
@@ -34,8 +37,30 @@ export declare function listGeneratedProjects(registry: ProjectRegistry, sel: Ru
  * One `defineBddConfig` per project × layer; browsers reuse the generated testDir.
  */
 export declare function buildRunnerConfig(registry: ProjectRegistry, sel?: RunnerSelection): PlaywrightTestConfig;
+/**
+ * `retries.byTag` as runner projects.
+ *
+ * Retries are fixed when a test is collected: Playwright takes them from the enclosing
+ * `test.describe.configure` or the project, and offers no runtime setter; bddgen has no hook to
+ * add `@retries:N` to a scenario it did not read from the feature file. What Playwright does
+ * offer is project-level `grep`, matched against the title AND the tags. So each byTag entry
+ * becomes a sibling of the project — same name, so `--project <name>`, reports and dashboards are
+ * unchanged — that greps for the tag and carries its retries, and the base project inverts every
+ * byTag grep. Entries are ordered by retries, highest first, and each sibling also inverts the
+ * ones before it, so a scenario with two such tags runs exactly once, with the larger count.
+ *
+ * Explicit `--retries` on the CLI still overrides every project, these included. A scenario's own
+ * `@retries:N` tag (playwright-bdd) wins over all of it.
+ */
+export declare function withRetriesByTag(project: RunnerProject, byTag: Record<string, number>): RunnerProject[];
+/**
+ * The setup tier a run uses: the process's `setup` (`false` turns it off), else the project's.
+ * Tags are normalised like `--tags`, so `setup: { tags: setup }` means `@setup`.
+ */
+export declare function setupTierOf(project: Pick<ProjectConfig, 'setup'>, proc?: Pick<ProcessConfig, 'setup'>): SetupConfig | undefined;
 /** @deprecated Use {@link buildRunnerConfig}. Removed in the next minor. */
 export declare const buildPlaywrightConfig: typeof buildRunnerConfig;
 /** @deprecated Use {@link RunnerSelection}. Removed in the next minor. */
 export type PlaywrightSelection = RunnerSelection;
+export {};
 //# sourceMappingURL=runner.d.ts.map