@sdods/core 0.2.1 → 0.3.0

package/dist/analyze/detectors.js

@@ -1,10 +1,54 @@
-import { basename, dirname } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, parse as parsePath } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 const SOURCE_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.vue', '.svelte']);
 const TEMPLATE_EXT = new Set(['.tsx', '.jsx', '.vue', '.svelte', '.html', '.htm', '.ts', '.js']);
 function ev(file, line, snippet) {
     return { file, line, snippet: snippet?.trim().slice(0, 160) };
 }
+const PM_LOCKFILES = [
+    ['bun.lock', 'bun'],
+    ['bun.lockb', 'bun'],
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['package-lock.json', 'npm'],
+];
+/**
+ * Nearest ancestor of `from` that looks like a JS workspace root: it holds a lockfile, or a
+ * package.json declaring `workspaces`, or a pnpm-workspace.yaml.
+ *
+ * Scanning a workspace MEMBER (`analyze apps/sat`) is the normal case on a monorepo, and the
+ * member has none of those files — the root above it does. Without this walk the whole scan
+ * reports `packageManager: unknown` and `monorepo: false` for a repo that is plainly neither.
+ * Returns undefined rather than guessing when nothing is found before the filesystem root.
+ */
+function findWorkspaceRootAbove(from) {
+    const stopAt = parsePath(from).root;
+    let dir = dirname(from);
+    // Bounded so a pathological path cannot spin; 12 is far beyond any real nesting depth.
+    for (let i = 0; i < 12 && dir && dir !== stopAt; i++) {
+        if (PM_LOCKFILES.some(([f]) => existsSync(join(dir, f))))
+            return dir;
+        if (existsSync(join(dir, 'pnpm-workspace.yaml')))
+            return dir;
+        const pkgPath = join(dir, 'package.json');
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                if (pkg.workspaces)
+                    return dir;
+            }
+            catch {
+                /* an unparseable package.json is not a workspace root */
+            }
+        }
+        const next = dirname(dir);
+        if (next === dir)
+            break;
+        dir = next;
+    }
+    return undefined;
+}
 export function detectPackageManager(scan) {
     const evidence = [];
     let name = 'unknown';
@@ -17,13 +61,7 @@ export function detectPackageManager(scan) {
             evidence.push(ev('package.json', undefined, `packageManager: ${pm}`));
         }
     }
-    const lockfiles = [
-        ['bun.lock', 'bun'],
-        ['bun.lockb', 'bun'],
-        ['pnpm-lock.yaml', 'pnpm'],
-        ['yarn.lock', 'yarn'],
-        ['package-lock.json', 'npm'],
-    ];
+    const lockfiles = PM_LOCKFILES;
     for (const [file, pmName] of lockfiles) {
         if (scan.has(file)) {
             if (name === 'unknown')
@@ -65,10 +103,41 @@ export function detectPackageManager(scan) {
         if (scan.has(f))
             evidence.push(ev(f, undefined, 'monorepo tooling'));
     }
-    const monorepo = workspaces.length > 0 ||
+    let monorepo = workspaces.length > 0 ||
         scan.has('lerna.json') ||
         scan.has('nx.json') ||
         scan.has('turbo.json');
+    // A workspace member has no lockfile and no `workspaces` key of its own — those live in the
+    // root above it. Scanning a member directly is the normal monorepo case, so resolve upwards
+    // rather than reporting `unknown` / `monorepo: false` for a repo that is neither.
+    if (name === 'unknown' || !monorepo) {
+        const wsRoot = findWorkspaceRootAbove(scan.root);
+        if (wsRoot) {
+            monorepo = true;
+            if (name === 'unknown') {
+                for (const [file, pmName] of PM_LOCKFILES) {
+                    if (existsSync(join(wsRoot, file))) {
+                        name = pmName;
+                        evidence.push(ev(file, undefined, `workspace root ${wsRoot}`));
+                        break;
+                    }
+                }
+                if (name === 'unknown') {
+                    try {
+                        const pkg = JSON.parse(readFileSync(join(wsRoot, 'package.json'), 'utf8'));
+                        const m = /^(npm|pnpm|yarn|bun)@/.exec(pkg.packageManager ?? '');
+                        if (m) {
+                            name = m[1];
+                            evidence.push(ev('package.json', undefined, `workspace root ${wsRoot}: ${pkg.packageManager}`));
+                        }
+                    }
+                    catch {
+                        /* no readable manifest at the workspace root */
+                    }
+                }
+            }
+        }
+    }
     return { name, monorepo, workspaces: [...new Set(workspaces)], evidence };
 }
 // ── frameworks ────────────────────────────────────────────────────────────────
@@ -202,6 +271,8 @@ export function detectRoutes(scan, frameworks) {
     if (names.has('Next.js') ||
         scan.files.some((f) => /(^|\/)app\/.*page\.(tsx|jsx|ts|js)$/.test(f.rel))) {
         for (const f of scan.files) {
+            if (isNotShippedCode(f.rel))
+                continue;
             const m = /(?:^|\/)(?:src\/)?app\/(.*?)(?:^|\/)?(page|route)\.(tsx|jsx|ts|js)$/.exec(f.rel);
             if (!m)
                 continue;
@@ -237,9 +308,19 @@ export function detectRoutes(scan, frameworks) {
             }
         }
         for (const f of scan.files) {
+            if (isNotShippedCode(f.rel))
+                continue;
             const m = /(?:^|\/)(?:src\/)?pages\/(.+)\.(tsx|jsx|ts|js)$/.exec(f.rel);
             if (!m)
                 continue;
+            // A directory called `pages` is not automatically the Pages Router.
+            // `app/api/intranet/pages/[id]/route.ts` is an App Router ROUTE HANDLER
+            // inside a resource that happens to be named "pages" — and it was being
+            // read as a Pages Router PAGE at `/{id}/route`: wrong kind, wrong source,
+            // and a path that had lost every parent segment. Anything under an `app/`
+            // segment belongs to the App Router loop above, which already handled it.
+            if (/(?:^|\/)(?:src\/)?app\//.test(f.rel))
+                continue;
             const rel = m[1];
             if (/^_app$|^_document$|^_error$|^404$|^500$/.test(rel))
                 continue;
@@ -256,6 +337,15 @@ export function detectRoutes(scan, frameworks) {
             });
         }
     }
+    /**
+     * Colocated tests, stories and type declarations sit next to the code they
+     * cover and match every route filename pattern. `route.test.ts` was being
+     * reported as a route named `id-publish-route-test`, which then became a key in
+     * the generated `routes:` map — an address that resolves to nothing.
+     */
+    function isNotShippedCode(rel) {
+        return /\.(test|spec|stories|story|bench|d)\.(tsx|jsx|ts|js|mts|cts)$/.test(rel);
+    }
     // React Router
     if (names.has('React Router')) {
         for (const f of scan.byExt('.tsx', '.jsx', '.ts', '.js')) {
@@ -664,13 +754,35 @@ export function detectAuth(scan, routes) {
     }
     if (pages.length)
         votes.form += 0.5;
-    let strategyGuess = 'none';
-    let best = 0;
-    for (const [k, v] of Object.entries(votes)) {
-        if (v > best) {
-            best = v;
-            strategyGuess = k;
-        }
+    // Ranked, not object-key order. `if (v > best)` over `Object.entries` resolves a TIE by
+    // whichever key happens to be declared first — so a repo scoring form 1.6 and token 1.6 got
+    // `form` for no reason a reader could see, and adding a library could silently flip it.
+    // Ties are now broken by this explicit precedence and, more importantly, are REPORTED: an
+    // ambiguous guess a human must confirm is not the same result as a confident one.
+    const TIE_ORDER = [
+        'sso',
+        'oauth-client-credentials',
+        'token',
+        'form',
+        'none',
+    ];
+    // Epsilon, not `===`. These scores are sums of decimal weights, so a "tie" is almost never
+    // exact: passport-local + express-session is 0.8 + 0.5 = 1.3000000000000000, while
+    // jsonwebtoken + @nestjs/jwt is 0.6 + 0.7 = 1.2999999999999998. Exact equality would report
+    // those as a clear win for `form` by 2e-16 — which is precisely the invisible, weight-order
+    // -dependent decision this fix exists to remove.
+    const TIE_EPSILON = 1e-9;
+    const ranked = Object.entries(votes).sort((a, b) => (Math.abs(b[1] - a[1]) < TIE_EPSILON ? 0 : b[1] - a[1]) ||
+        TIE_ORDER.indexOf(a[0]) - TIE_ORDER.indexOf(b[0]));
+    const [top, second] = ranked;
+    const best = top?.[1] ?? 0;
+    const strategyGuess = best > 0 ? top[0] : 'none';
+    if (second && best > 0 && Math.abs(second[1] - best) < TIE_EPSILON) {
+        const tied = ranked
+            .filter(([, v]) => Math.abs(v - best) < TIE_EPSILON)
+            .map(([k]) => k)
+            .join(', ');
+        evidence.push(ev('package.json', undefined, `ambiguous auth: ${tied} all scored ${best.toFixed(2)} — picked ${strategyGuess}, confirm before relying on it`));
     }
     return {
         pages: [...new Set(pages)],
@@ -682,30 +794,115 @@ export function detectAuth(scan, routes) {
 }
 // ── envs and base urls ────────────────────────────────────────────────────────
 const URL_VAR = /(BASE_?URL|API_?URL|APP_?URL|PUBLIC_URL|SITE_URL|HOST|ORIGIN|ENDPOINT)/i;
+/** Framework prefixes that expose a variable to the browser but say nothing about its meaning. */
+const PUBLIC_PREFIX = /^(NEXT_PUBLIC_|VITE_|REACT_APP_|NUXT_PUBLIC_|PUBLIC_|GATSBY_|EXPO_PUBLIC_)/;
+const CANONICAL_URL_KEYS = new Set([
+    'API_URL',
+    'API_BASE_URL',
+    'BASE_URL',
+    'APP_URL',
+    'APP_BASE_URL',
+    'SITE_URL',
+    'PUBLIC_URL',
+    'ORIGIN',
+    'HOST',
+]);
+/**
+ * How strongly a variable NAME claims to be *the* base URL of its kind.
+ *
+ * The old rule was `apiBaseUrl ??= raw` — first match in file order wins. On a real repo that
+ * means `SIM_AGENT_API_URL`, declared 39 lines above `NEXT_PUBLIC_API_URL`, becomes the API base
+ * URL for the whole generated project, and every generated API scenario then talks to a service
+ * that is not the application. A vendor- or service-prefixed name is the LEAST likely to be the
+ * app's own base URL, so specificity has to beat position.
+ */
+function urlKeyScore(key) {
+    const bare = key.toUpperCase().replace(PUBLIC_PREFIX, '');
+    if (CANONICAL_URL_KEYS.has(bare))
+        return 3;
+    if (/^[A-Z0-9]+_(API_URL|BASE_URL|APP_URL)$/.test(bare))
+        return 1;
+    return 2;
+}
+/**
+ * A deliberately small `.gitignore` reader, scoped to the `.env` family only.
+ *
+ * Full gitignore semantics (negation, directory-only, nested files, precedence) are not needed
+ * to answer the one question asked here — "is this .env file deliberately untracked?" — and a
+ * partial implementation of the full spec would be worse than an honest narrow one. Patterns
+ * that do not concern `.env*` are ignored outright.
+ */
+function gitIgnoredEnvMatcher(scan) {
+    const patterns = [];
+    for (const candidate of ['.gitignore', '.git/info/exclude']) {
+        const text = scan.read(candidate);
+        if (!text)
+            continue;
+        for (const raw of text.split(/\r?\n/)) {
+            const line = raw.trim();
+            if (!line || line.startsWith('#') || line.startsWith('!'))
+                continue;
+            const body = line.replace(/^\/+/, '').replace(/\/+$/, '');
+            if (!body.includes('.env'))
+                continue;
+            patterns.push(new RegExp(`^${body
+                .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+                .replace(/\*/g, '[^/]*')
+                .replace(/\?/g, '[^/]')}$`));
+        }
+    }
+    if (!patterns.length)
+        return () => false;
+    return (rel) => {
+        const base = basename(rel);
+        return patterns.some((re) => re.test(base) || re.test(rel));
+    };
+}
 export function detectEnvs(scan) {
     const envs = [];
     const evidence = [];
     let ui;
     let api;
+    const ignored = gitIgnoredEnvMatcher(scan);
     for (const f of scan.files) {
         const name = basename(f.rel);
         if (!name.startsWith('.env'))
             continue;
         if (f.rel.split('/').length > 2)
             continue;
+        // A gitignored .env holds real credentials and real internal hostnames. Reading it puts
+        // those values into the report, and `analyze --json` / the generated yaml are things people
+        // paste into issues and commit. The file is deliberately not in the repo; the analyzer has
+        // no business republishing it.
+        if (ignored(f.rel)) {
+            evidence.push(ev(f.rel, undefined, 'gitignored — not read'));
+            continue;
+        }
         const envName = name === '.env' ? 'local' : name.replace(/^\.env\.?/, '').replace(/\.local$/, '') || 'local';
         const vars = [];
         let uiBaseUrl;
         let apiBaseUrl;
+        let uiScore = -1;
+        let apiScore = -1;
         for (const hit of scan.grep(f.rel, /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/)) {
             const key = hit.match[1];
             const raw = hit.match[2].trim().replace(/^["']|["']$/g, '');
             vars.push(key);
             if (URL_VAR.test(key) && /^https?:\/\//.test(raw)) {
-                if (/API|ENDPOINT/i.test(key))
-                    apiBaseUrl ??= raw;
-                else
-                    uiBaseUrl ??= raw;
+                const score = urlKeyScore(key);
+                const isApi = /API|ENDPOINT/i.test(key);
+                // Strictly greater: the first key at a given specificity still wins, so a file with two
+                // equally-canonical names keeps its existing, file-order-stable answer.
+                if (isApi ? score > apiScore : score > uiScore) {
+                    if (isApi) {
+                        apiBaseUrl = raw;
+                        apiScore = score;
+                    }
+                    else {
+                        uiBaseUrl = raw;
+                        uiScore = score;
+                    }
+                }
                 evidence.push(ev(f.rel, hit.line, `${key}=${/example|sample/i.test(name) ? raw : '…'}`));
             }
         }
@@ -757,7 +954,12 @@ export function detectEnvs(scan) {
             }
         }
     }
-    for (const e of envs) {
+    // Real environments first, `.env.example` last. `propose` drops `example` from the env list
+    // (it is a template, not an environment) while base URLs were folded in file order — so a repo
+    // whose .env.example sorted first handed its placeholder URLs to every generated env, and the
+    // proposal named environments that had supplied none of its own values.
+    const isTemplate = (n) => n === 'example' || n === 'sample';
+    for (const e of [...envs].sort((a, b) => Number(isTemplate(a.name)) - Number(isTemplate(b.name)))) {
         ui ??= e.uiBaseUrl;
         api ??= e.apiBaseUrl;
     }
@@ -766,9 +968,19 @@ export function detectEnvs(scan) {
         const portHit = scan.files
             .filter((f) => SOURCE_EXT.has(f.ext))
             .flatMap((f) => scan.grep(f.rel, /\.listen\(\s*(?:\{[^}]*port:\s*)?(\d{4,5})/).map((h) => ({ f, h })))[0];
-        api = portHit ? `http://localhost:${portHit.h.match[1]}` : 'http://localhost:3000';
-        if (portHit)
-            evidence.push(ev(portHit.f.rel, portHit.h.line, portHit.h.text));
+        // Only when it names a DIFFERENT origin than the UI. A full-stack app (Next, Nuxt) serves
+        // its API from the same port under /api, and an express dependency there is usually a socket
+        // or worker server — not a second API origin. The old code set `api` unconditionally, which
+        // both invented `http://localhost:3000` out of nothing when no `.listen()` existed AND
+        // suppressed the `api ??= ui + '/api'` fallback below, so every generated API scenario was
+        // pointed at the UI origin with no /api suffix.
+        if (portHit) {
+            const candidate = `http://localhost:${portHit.h.match[1]}`;
+            if (candidate !== ui) {
+                api = candidate;
+                evidence.push(ev(portHit.f.rel, portHit.h.line, portHit.h.text));
+            }
+        }
     }
     api ??= ui ? `${ui}/api` : undefined;
     return { envs, baseUrls: { ui, api, evidence } };

package/dist/analyze/propose.js

@@ -10,19 +10,41 @@ export function slugify(input) {
         .replace(/^-+|-+$/g, '');
     return s || 'app';
 }
+/**
+ * A route key is a feature-file identifier a person has to read, type and grep for — it names
+ * `features/<module>/<key>.feature`. The old version cleaned every segment and joined all of
+ * them, so a deep route produced a long key whose leading segments were pure transport
+ * (`api-v1-…`) and whose parameter segments lost the fact that they were parameters.
+ *
+ * Now: transport prefixes are dropped, parameters read as `by-<param>`, and the key is capped at
+ * the segments that actually distinguish it. Collisions are still resolved by the `-2`, `-3`
+ * suffix loop in the caller, so shortening cannot silently merge two routes.
+ */
+const TRANSPORT_SEGMENTS = new Set(['api', 'rest', 'v1', 'v2', 'v3']);
 function routeName(path) {
     if (path === '/' || path === '')
         return 'home';
-    const segs = path
-        .split('/')
-        .filter(Boolean)
-        .map((s) => s.replace(/[{}*]/g, '').replace(/[^a-zA-Z0-9]+/g, '-'));
-    const name = segs
-        .filter(Boolean)
-        .map((s, i) => (i > 0 && path.includes(`{${s}}`) ? `by-${s}` : s))
-        .join('-')
-        .toLowerCase();
-    return name || 'home';
+    const raw = path.split('/').filter(Boolean);
+    const isParam = (s) => /^[{:*]/.test(s) || /^\[.*\]$/.test(s);
+    const clean = (s) => s
+        .replace(/[{}[\]:*]/g, '')
+        .replace(/^\.\.\./, '')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    const parts = [];
+    for (const [i, seg] of raw.entries()) {
+        const name = clean(seg);
+        if (!name)
+            continue;
+        // Only a LEADING transport segment is dropped: a resource genuinely called `v2` deeper in
+        // the path is part of the identity of the route.
+        if (i === 0 && TRANSPORT_SEGMENTS.has(name.toLowerCase()))
+            continue;
+        parts.push(isParam(seg) ? `by-${name}` : name);
+    }
+    // Keep the head (what it is) and the tail (what it does); the middle rarely distinguishes.
+    const trimmed = parts.length > 4 ? [parts[0], ...parts.slice(-3)] : parts;
+    return trimmed.join('-').toLowerCase() || 'home';
 }
 function moduleOfPath(path) {
     const first = path.split('/').filter(Boolean)[0];

package/dist/analyze/scan.js

@@ -34,6 +34,10 @@ export const IGNORED_DIRS = new Set([
     'bin',
     'obj',
 ]);
+/** A directory that contains `.git` (a dir for a clone, a file for a worktree). */
+function isRepositoryRoot(dir) {
+    return existsSync(join(dir, '.git'));
+}
 export const TEXT_EXTENSIONS = new Set([
     '.ts',
     '.tsx',
@@ -77,7 +81,12 @@ export class Scan {
     byRel = new Map();
     constructor(root, opts = {}) {
         this.root = resolvePath(root);
-        const maxFiles = opts.maxFiles ?? 8000;
+        // 8,000 was below the size of a single real monorepo app: `apps/sat` alone is ~6,400 files,
+        // so the walk truncated before reaching `.github/`, and every absence-based finding
+        // ("no CI", "no OpenAPI", "no test ids") was then reported as fact rather than as
+        // "not seen". Raising the default is half the fix; `--max-files` / `--max-depth` on the CLI
+        // is the other half, because no default is right for every repo.
+        const maxFiles = opts.maxFiles ?? 25000;
         const maxDepth = opts.maxDepth ?? 12;
         let truncated = false;
         const walk = (dir, depth) => {
@@ -96,6 +105,15 @@ export class Scan {
                     return;
                 }
                 const abs = join(dir, name);
+                // A directory holding its own `.git` is a different repository — a
+                // submodule, a vendored checkout, or a git worktree. Descending into
+                // one attributes another project's routes to this one, and a worktree
+                // is usually a STALE copy of this very repo, so every route gets
+                // reported twice with the wrong path. Observed on a real monorepo: all
+                // 157 routes were cited inside `.claude/worktrees/<branch>/`, a path
+                // that repo's own .gitignore excludes.
+                if (dir !== this.root && isRepositoryRoot(dir))
+                    return;
                 let st;
                 try {
                     st = statSync(abs);

package/dist/api/client.js

@@ -53,7 +53,13 @@ export class ApiClient {
         };
         if (opts.body !== undefined && !headers['content-type'] && !opts.form)
             headers['content-type'] = 'application/json';
-        const auth = opts.auth === null ? undefined : (opts.auth ?? this.deps.ctx.auth ?? envAuth(env.auth));
+        // `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}`;

package/dist/auth/capture.js

@@ -111,14 +111,22 @@ export async function captureAuth(opts) {
                 results.push(result);
                 continue;
             }
-            if (!opts.force && cache.isFresh(user)) {
+            // A fresh storageState means the LOGIN can be skipped. It says nothing about
+            // the token: the two are separate artefacts with separate lifetimes, and the
+            // token file is what the API layer reads (steps/data.steps.ts). Skipping the
+            // whole user here left roles with a browser session and no token, so every
+            // `@user:<role>` API scenario fell through to a live mint -- one Firebase
+            // sign-in per scenario, which is how a suite earns QUOTA_EXCEEDED. So the
+            // freshness check now gates the login only, and the token block below still
+            // runs -- and it is not a wasted mint either, because it now mints only when
+            // there is no token file yet, or when --force asked for a fresh one.
+            const loginIsFresh = !opts.force && cache.isFresh(user);
+            const interactive = opts.interactive || strategy.strategy === 'sso';
+            if (loginIsFresh) {
                 result.file = cache.fileFor(user);
                 result.skipped = 'fresh state exists (use force to recapture)';
-                results.push(result);
-                continue;
             }
-            const interactive = opts.interactive || strategy.strategy === 'sso';
-            if (interactive) {
+            else if (interactive) {
                 const file = cache.fileFor(user);
                 const loginUrl = new URL(opts.loginUrl ?? config.project.auth.form?.loginPath ?? '/', config.env.ui.baseUrl).toString();
                 const args = ['playwright', 'codegen', '--save-storage', file];
@@ -144,14 +152,20 @@ export async function captureAuth(opts) {
                 else if (!strategy.token)
                     result.skipped = 'strategy returned no storage state';
             }
-            if (strategy.token) {
+            if (strategy.token && (opts.force || !existsSync(tokenFileFor(config, user)))) {
                 const token = await strategy.token({ config, user });
                 if (token) {
                     const file = tokenFileFor(config, user);
-                    writeFileSync(file, JSON.stringify({ token, capturedAt: new Date().toISOString(), user: user.username, role: user.role }, null, 2));
+                    // Owner-only: this holds a usable API token for the application under test.
+                    writeFileSync(file, JSON.stringify({ token, capturedAt: new Date().toISOString(), user: user.username, role: user.role }, null, 2), { mode: 0o600 });
                     result.tokenFile = file;
                 }
             }
+            else if (strategy.token) {
+                // Reused, not absent. Reporting nothing here reads as "this role has no
+                // token", which is the opposite of the truth.
+                result.tokenFile = tokenFileFor(config, user);
+            }
             results.push(result);
         }
     }

package/dist/auth/index.js

@@ -1,3 +1,6 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { SdodsError } from '../errors.js';
 /**
  * Define the project's auth strategy. `form` uses `auth.form` selectors from the project yaml
  * unless a custom `login` is provided.
@@ -29,7 +32,16 @@ export function defineAuth(def) {
         case 'token':
             return {
                 strategy: 'token',
-                login: async () => undefined,
+                // A `token` project can call the API and has NO browser session. Returning `undefined`
+                // here let a @ui scenario run signed-out and then fail on an assertion about the page,
+                // which reads as a product defect rather than as a misconfigured project. Fail where the
+                // cause is, and say what to do instead.
+                login: async () => {
+                    throw new SdodsError('NOT_SUPPORTED', 'The `token` auth strategy provides an API credential, not a browser session.', {
+                        hint: 'Use `strategy: "custom"` with a `login` that performs the sign-in and returns a storageState, or restrict these scenarios to the @api layer.',
+                        exitCode: 2,
+                    });
+                },
                 token: def.token,
             };
         case 'oauth-client-credentials':
@@ -61,7 +73,18 @@ export function defineAuth(def) {
                 },
             };
         case 'sso':
-            return { strategy: 'sso', login: async () => undefined };
+            return {
+                strategy: 'sso',
+                // `sso` was a stub: it returned no session and threw nothing, so every scenario under it
+                // ran unauthenticated and silently. There is no generic SSO sign-in to implement — the
+                // flow is provider-specific — so the honest behaviour is to refuse and name the seam.
+                login: async () => {
+                    throw new SdodsError('NOT_SUPPORTED', 'The `sso` auth strategy is a placeholder: it performs no sign-in.', {
+                        hint: 'SSO flows are provider-specific. Use `strategy: "custom"` with a `login` that drives your identity provider, or capture a session once with `sdods auth capture --interactive`.',
+                        exitCode: 2,
+                    });
+                },
+            };
         case 'custom':
             return { strategy: 'custom', login: def.login, token: def.token };
     }
@@ -71,16 +94,52 @@ export async function formLogin(page, config, user) {
     if (!form) {
         throw new Error('auth.strategy is "form" but auth.form selectors are missing in sdods.project.yaml.');
     }
-    await page.goto(form.loginPath);
-    await page.locator(form.usernameSelector).fill(user.username);
-    await page.locator(form.passwordSelector).fill(user.password);
-    await page.locator(form.submitSelector).click();
-    if (form.readySelector)
-        await page.locator(form.readySelector).first().waitFor({ state: 'visible' });
-    else if (form.readyUrl)
-        await page.waitForURL(`**${form.readyUrl}*`);
-    else
-        await page.waitForLoadState('domcontentloaded');
+    try {
+        await page.goto(form.loginPath);
+        await page.locator(form.usernameSelector).fill(user.username);
+        await page.locator(form.passwordSelector).fill(user.password);
+        await page.locator(form.submitSelector).click();
+        if (form.readySelector)
+            await page.locator(form.readySelector).first().waitFor({ state: 'visible' });
+        else if (form.readyUrl)
+            await page.waitForURL(`**${form.readyUrl}*`);
+        else
+            await page.waitForLoadState('domcontentloaded');
+    }
+    catch (cause) {
+        throw await describeLoginFailure(page, config, user, cause);
+    }
+}
+/**
+ * The form login runs in its own context (see `defineAuth`), so Playwright's video/trace/screenshot
+ * settings never attach to it — a failure here would otherwise surface as a bare locator timeout
+ * with no artifact. Name the page we actually landed on, and leave a screenshot behind.
+ */
+async function describeLoginFailure(page, config, user, cause) {
+    let where = '';
+    let shot = '';
+    try {
+        const url = page.url();
+        const title = await page.title();
+        where = ` at ${url}${title ? ` (title: ${JSON.stringify(title)})` : ''}`;
+    }
+    catch {
+        // page already closed or crashed — the original error is still worth reporting
+    }
+    try {
+        const dir = join(config.runtime.runDir, 'auth');
+        mkdirSync(dir, { recursive: true });
+        const file = join(dir, `login-failed-${user.role}-${user.username}.png`.replace(/\s+/g, '_'));
+        await page.screenshot({ path: file, fullPage: true });
+        shot = `\nScreenshot: ${file}`;
+    }
+    catch {
+        // screenshotting is best effort
+    }
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    return new Error(`Form login for ${user.username} (${user.role}) failed${where}.\n${reason}` +
+        `\nIs the application under test running at ${config.env.ui.baseUrl}, and does that page ` +
+        `use the auth.form selectors in sdods.project.yaml?${shot}`, { cause });
 }
 export const noopAuth = defineAuth({ strategy: 'none' });
 //# sourceMappingURL=index.js.map

package/dist/config/resolve.d.ts

@@ -50,6 +50,19 @@ export interface ResolvedConfig {
     sources: {
         dotenvFiles: string[];
     };
+    /**
+     * The resolved `${VAR}` scope: the dotenv layer merged under `process.env`.
+     *
+     * Exposed because `loadDotEnvLayer` deliberately does NOT mutate `process.env`
+     * (doing so would silently outrank the process layer), so anything that
+     * interpolates `${VAR}` outside the config tree — dataset rows, most of all —
+     * cannot reach the values in `.env.<env>` unless it is handed this. Without
+     * it, the documented pattern of keeping passwords in `.env.<env>` and
+     * referencing them from `data/**\/users.csv` resolves to the literal string
+     * `${TEST_MEMBER_PASSWORD}`, and the failure surfaces far away as a provider
+     * rejecting the credential.
+     */
+    vars: Record<string, string | undefined>;
 }
 export interface ResolveOptions {
     rootDir: string;

package/dist/config/resolve.js

@@ -162,6 +162,7 @@ export function resolveConfig(opts) {
         runtime: rt,
         provenance: Object.fromEntries(prov.byPath),
         sources: { dotenvFiles: dotenv.files },
+        vars,
     };
 }
 function markAll(obj, prov, layer, prefix) {