@qulib/core 0.4.2 → 0.4.3

package/dist/tools/auth/surface.d.ts

@@ -0,0 +1,4 @@
+import type { DetectedAuth } from '../../schemas/config.schema.js';
+import type { Gap } from '../../schemas/gap-analysis.schema.js';
+export declare function analyzeAuthSurfaceGaps(url: string, detection: DetectedAuth, timeoutMs: number): Promise<Gap[]>;
+//# sourceMappingURL=surface.d.ts.map

package/dist/tools/auth/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../../../src/tools/auth/surface.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,sCAAsC,CAAC;AAWhE,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,GAAG,EAAE,CAAC,CAwKhB"}

package/dist/tools/auth/surface.js

@@ -0,0 +1,170 @@
+import { randomUUID } from 'node:crypto';
+import { launchBrowser } from '../explorers/browser.js';
+async function waitNetworkIdleBestEffort(page) {
+    try {
+        await page.waitForLoadState('networkidle', { timeout: 5000 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+export async function analyzeAuthSurfaceGaps(url, detection, timeoutMs) {
+    if (!detection.hasAuth) {
+        return [];
+    }
+    const gaps = [];
+    const browser = await launchBrowser();
+    try {
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        const resp = await page.goto(url, { timeout: timeoutMs, waitUntil: 'domcontentloaded' }).catch(() => null);
+        if (!resp || !resp.ok()) {
+            gaps.push({
+                id: randomUUID(),
+                path: new URL(url).pathname || '/',
+                severity: 'critical',
+                category: 'auth-surface',
+                reason: 'Sign-in surface did not load successfully for evaluation.',
+                description: 'The auth entry URL failed to load or returned a non-OK status before DOM checks could run.',
+                recommendation: 'Verify DNS, TLS, and that the URL is reachable from the scan environment.',
+            });
+            return gaps;
+        }
+        await waitNetworkIdleBestEffort(page);
+        const title = await page.title().catch(() => '');
+        if (!title || title.trim().length < 3) {
+            gaps.push({
+                id: randomUUID(),
+                path: '/',
+                severity: 'medium',
+                category: 'auth-surface',
+                reason: 'Missing or trivial document title on the sign-in surface.',
+                description: 'Users and assistive tech rely on a meaningful window title.',
+                recommendation: 'Set a concise, unique <title> for the login experience.',
+            });
+        }
+        const metaDesc = await page.locator('meta[name="description"]').getAttribute('content').catch(() => null);
+        if (!metaDesc || metaDesc.trim().length < 8) {
+            gaps.push({
+                id: randomUUID(),
+                path: '/',
+                severity: 'low',
+                category: 'auth-surface',
+                reason: 'No meta description on the sign-in surface.',
+                description: 'Search and sharing previews benefit from meta description on public entry pages.',
+                recommendation: 'Add <meta name="description" content="..."> with a short summary of the product.',
+            });
+        }
+        const h1Count = await page.locator('h1').count();
+        if (h1Count === 0) {
+            gaps.push({
+                id: randomUUID(),
+                path: '/',
+                severity: 'medium',
+                category: 'auth-surface',
+                reason: 'No visible primary heading (h1) on the sign-in surface.',
+                description: 'A primary heading helps users orient on the login page.',
+                recommendation: 'Add a single descriptive <h1> for the sign-in view.',
+            });
+        }
+        const oauthButtons = page.locator('button, a[href], [role="button"]');
+        const n = await oauthButtons.count();
+        for (let i = 0; i < Math.min(n, 25); i++) {
+            const el = oauthButtons.nth(i);
+            const text = ((await el.textContent()) ?? '').trim();
+            if (!text || text.length > 120)
+                continue;
+            const isOAuthish = /google|microsoft|github|apple|sso|sign in with|log in with|continue with|oauth/i.test(text);
+            if (!isOAuthish)
+                continue;
+            const role = await el.getAttribute('role');
+            const tag = await el.evaluate((node) => node.tagName.toLowerCase());
+            const tabIndex = await el.getAttribute('tabindex');
+            const aria = await el.getAttribute('aria-label');
+            const keyboardable = tag === 'button' || tag === 'a' || role === 'button';
+            const labeled = Boolean(aria && aria.trim().length > 0) || text.length > 0;
+            if (!keyboardable || tabIndex === '-1') {
+                gaps.push({
+                    id: randomUUID(),
+                    path: '/',
+                    severity: 'high',
+                    category: 'auth-surface',
+                    reason: `OAuth control "${text.slice(0, 60)}" may not be keyboard-accessible.`,
+                    description: 'SSO entry points should be real buttons or links with focus support.',
+                    recommendation: 'Use <button> or <a href> with visible label; avoid tabindex=-1 on the only sign-in path.',
+                });
+            }
+            else if (!labeled) {
+                gaps.push({
+                    id: randomUUID(),
+                    path: '/',
+                    severity: 'medium',
+                    category: 'auth-surface',
+                    reason: `OAuth control "${text.slice(0, 60)}" lacks aria-label and has weak visible text.`,
+                    description: 'Assistive technologies need a clear accessible name for IdP buttons.',
+                    recommendation: 'Add aria-label or visible text that names the provider and action.',
+                });
+            }
+        }
+        const hasPassword = (await page.locator('input[type="password"]').count()) > 0;
+        const hasEmailLink = await page.getByText(/magic link|email.*link|passwordless/i).count();
+        const hasOAuthUi = detection.oauthButtons.length > 0 ||
+            (await page.getByText(/sign in with|continue with google|microsoft|github/i).count()) > 0;
+        const formLoginFallbacks = (detection.authOptions ?? []).filter((o) => o.type === 'form-login');
+        const hasFormLoginFallback = formLoginFallbacks.length > 0;
+        if (detection.type === 'oauth' && hasOAuthUi && !hasPassword && !hasEmailLink) {
+            if (hasFormLoginFallback) {
+                const labels = formLoginFallbacks.map((o) => o.label).join(', ');
+                gaps.push({
+                    id: randomUUID(),
+                    path: '/',
+                    severity: 'low',
+                    category: 'auth-surface',
+                    reason: `OAuth-primary login with form-login fallback detected via: ${labels}`,
+                    description: 'A form-based login path exists alongside OAuth. Automate via type="form-login" using the selectors in authOptions.',
+                    recommendation: `Automatable form option(s): ${labels}. Configure type="form-login" with credentials and selectors from detectedAuth.authOptions.`,
+                });
+            }
+            else {
+                gaps.push({
+                    id: randomUUID(),
+                    path: '/',
+                    severity: 'medium',
+                    category: 'auth-surface',
+                    reason: 'OAuth-only entry with no visible password or magic-link fallback.',
+                    description: 'Users who cannot use a social IdP need another path (email/password, help, or support).',
+                    recommendation: 'Add a documented fallback (email/password, help desk link, or alternate IdP).',
+                });
+            }
+        }
+        const errorSelectors = '[role="alert"], [data-testid*="error" i], .error, .alert-danger, [class*="error" i]';
+        const errCount = await page.locator(errorSelectors).count();
+        if (errCount === 0 && hasOAuthUi) {
+            gaps.push({
+                id: randomUUID(),
+                path: '/',
+                severity: 'low',
+                category: 'auth-surface',
+                reason: 'No obvious in-DOM error container found for OAuth sign-in failures.',
+                description: 'IdP failures should surface recoverable feedback in the page.',
+                recommendation: 'Reserve a live region or inline alert for OAuth errors returned from the provider.',
+            });
+        }
+        const help = await page.getByText(/forgot password|need help|contact support|get help/i).count();
+        if (help === 0 && hasOAuthUi) {
+            gaps.push({
+                id: randomUUID(),
+                path: '/',
+                severity: 'low',
+                category: 'auth-surface',
+                reason: 'No visible “forgot password” or help path detected near OAuth controls.',
+                description: 'Users locked out of an IdP need a support or recovery affordance.',
+                recommendation: 'Link to account recovery, IT help, or a support URL near the sign-in actions.',
+            });
+        }
+    }
+    finally {
+        await browser.close();
+    }
+    return gaps;
+}

package/dist/tools/auth/user-providers.d.ts

@@ -0,0 +1,15 @@
+import type { OAuthProvider } from './oauth-providers.js';
+export interface SerializedProvider {
+    id: string;
+    label: string;
+    patterns: string[];
+}
+export declare function loadUserProviders(): OAuthProvider[];
+export declare function addUserProvider(input: {
+    id: string;
+    label: string;
+    pattern: string;
+}): void;
+export declare function removeUserProvider(id: string): boolean;
+export declare function listUserProviders(): SerializedProvider[];
+//# sourceMappingURL=user-providers.d.ts.map

package/dist/tools/auth/user-providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-providers.d.ts","sourceRoot":"","sources":["../../../src/tools/auth/user-providers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAgB,iBAAiB,IAAI,aAAa,EAAE,CAOnD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAc3F;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAStD;AAED,wBAAgB,iBAAiB,IAAI,kBAAkB,EAAE,CAExD"}

package/dist/tools/auth/user-providers.js

@@ -0,0 +1,62 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+const USER_PROVIDERS_PATH = join(homedir(), '.qulib', 'providers.json');
+export function loadUserProviders() {
+    const raw = loadSerialized();
+    return raw.map((p) => ({
+        id: p.id,
+        label: p.label,
+        patterns: p.patterns.map((src) => new RegExp(src, 'i')),
+    }));
+}
+export function addUserProvider(input) {
+    const existing = loadSerialized();
+    const idx = existing.findIndex((p) => p.id === input.id);
+    if (idx >= 0) {
+        const p = existing[idx];
+        if (!p.patterns.includes(input.pattern)) {
+            p.patterns.push(input.pattern);
+        }
+        p.label = input.label;
+    }
+    else {
+        existing.push({ id: input.id, label: input.label, patterns: [input.pattern] });
+    }
+    ensureDir();
+    writeFileSync(USER_PROVIDERS_PATH, JSON.stringify(existing, null, 2), 'utf-8');
+}
+export function removeUserProvider(id) {
+    const existing = loadSerialized();
+    const filtered = existing.filter((p) => p.id !== id);
+    if (filtered.length === existing.length) {
+        return false;
+    }
+    ensureDir();
+    writeFileSync(USER_PROVIDERS_PATH, JSON.stringify(filtered, null, 2), 'utf-8');
+    return true;
+}
+export function listUserProviders() {
+    return loadSerialized();
+}
+function loadSerialized() {
+    if (!existsSync(USER_PROVIDERS_PATH)) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(USER_PROVIDERS_PATH, 'utf-8'));
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        return parsed;
+    }
+    catch {
+        return [];
+    }
+}
+function ensureDir() {
+    const dir = dirname(USER_PROVIDERS_PATH);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}

package/dist/tools/auth-block-gap.d.ts

@@ -1,3 +1,9 @@
 import type { Gap } from '../schemas/gap-analysis.schema.js';
+import type { StorageStateInvalidReason } from './auth-detector.js';
 export declare function buildAuthBlockGap(url: string): Gap;
+export declare function buildStorageStateInvalidGap(input: {
+    url: string;
+    reasonCode: StorageStateInvalidReason;
+    reason: string;
+}): Gap;
 //# sourceMappingURL=auth-block-gap.d.ts.map

package/dist/tools/auth-block-gap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-block-gap.d.ts","sourceRoot":"","sources":["../../src/tools/auth-block-gap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mCAAmC,CAAC;AAE7D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAiBlD"}
+{"version":3,"file":"auth-block-gap.d.ts","sourceRoot":"","sources":["../../src/tools/auth-block-gap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mCAAmC,CAAC;AAC7D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAmBpE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAYlD;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,yBAAyB,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,GAAG,CAqBN"}

package/dist/tools/auth-block-gap.js

@@ -1,12 +1,23 @@
+function safeOriginAndPath(url) {
+    try {
+        const u = new URL(url);
+        return `${u.origin}${u.pathname}`;
+    }
+    catch {
+        return url;
+    }
+}
+function safeHost(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return url;
+    }
+}
 export function buildAuthBlockGap(url) {
-    const host = (() => {
-        try {
-            return new URL(url).hostname;
-        }
-        catch {
-            return url;
-        }
-    })();
+    const host = safeHost(url);
+    const safeUrl = safeOriginAndPath(url);
     return {
         id: 'auth-block',
         path: '/',
@@ -14,6 +25,28 @@ export function buildAuthBlockGap(url) {
         category: 'coverage',
         reason: `Scan blocked by authentication. No authenticated pages were evaluated for ${host}.`,
         description: 'Scan blocked by authentication. 0 authenticated pages were evaluated.',
-        recommendation: `Run \`qulib auth init --base-url ${url}\` to capture a storage state, then re-run with --auth storage-state.`,
+        recommendation: `Run \`qulib auth init --base-url ${safeUrl}\` to capture a storage state, then re-run with --auth storage-state.`,
+    };
+}
+export function buildStorageStateInvalidGap(input) {
+    const host = safeHost(input.url);
+    const safeUrl = safeOriginAndPath(input.url);
+    const recoveryByCode = {
+        'missing-file': `Storage state file was not found. Run \`qulib auth login --base-url ${safeUrl} --out <path>\` (or \`qulib auth init\`) to capture a fresh state, then re-run \`qulib analyze --url ${safeUrl} --auth-storage-state <path>\`.`,
+        'unreadable-file': `Storage state file exists but could not be read. Check file permissions, then re-run \`qulib auth login\` if needed.`,
+        'invalid-json': `Storage state file is not valid JSON. Run \`qulib auth login --base-url ${safeUrl} --out <path>\` again to regenerate it.`,
+        'wrong-origin': `Storage state belongs to a different origin than ${host}. Re-run \`qulib auth login --base-url ${safeUrl}\` against this target and pass the new file to \`qulib analyze\`.`,
+        'expired-or-unauthorized': `The session in the storage state has expired or is unauthorized. Run \`qulib auth login --base-url ${safeUrl}\` to capture a fresh state, then re-run \`qulib analyze --url ${safeUrl} --auth-storage-state <path>\`.`,
+        'no-auth-cookies': `Storage state file contains no cookies or localStorage entries — it is effectively empty. Run \`qulib auth login --base-url ${safeUrl}\` to capture a real session.`,
+        unknown: `Storage state could not be validated. Try \`qulib auth login --base-url ${safeUrl}\` again, and verify the file was saved on the same origin.`,
+    };
+    return {
+        id: 'storage-state-invalid',
+        path: '/',
+        severity: 'critical',
+        category: 'coverage',
+        reason: `Authenticated scan could not continue because the provided storage state is invalid for ${host}. Reason: ${input.reasonCode} — ${input.reason}.`,
+        description: `Storage state validation failed before crawling. The session was checked against ${host} and rejected with reason code "${input.reasonCode}".`,
+        recommendation: recoveryByCode[input.reasonCode],
     };
 }

package/dist/tools/auth-detector.d.ts

@@ -1,22 +1,23 @@
 import type { Page } from '@playwright/test';
 import type { DetectedAuth } from '../schemas/config.schema.js';
 import type { AnalyzeProgressSink } from '../harness/progress-log.js';
+export type StorageStateInvalidReason = 'missing-file' | 'unreadable-file' | 'invalid-json' | 'wrong-origin' | 'expired-or-unauthorized' | 'no-auth-cookies' | 'unknown';
+export interface StorageStateValidationResult {
+    valid: boolean;
+    reasonCode: StorageStateInvalidReason | 'ok';
+    reason: string;
+}
 export declare function evaluateStorageStateValidity(signals: {
     expectedOrigin: string;
     finalUrl: string;
     visiblePasswordCount: number;
     hadUnauthorizedHttp: boolean;
-}): {
-    valid: boolean;
-    reason: string;
-};
+}): StorageStateValidationResult;
+export declare function preflightStorageStateFile(storagePath: string): Promise<StorageStateValidationResult | null>;
 export declare function waitForReturnToOrigin(page: Page, baseUrl: string, timeoutMs?: number): Promise<{
     returned: boolean;
     finalUrl: string;
 }>;
-export declare function validateStorageState(url: string, storagePath: string, timeoutMs?: number): Promise<{
-    valid: boolean;
-    reason: string;
-}>;
+export declare function validateStorageState(url: string, storagePath: string, timeoutMs?: number): Promise<StorageStateValidationResult>;
 export declare function detectAuth(url: string, timeoutMs?: number, progress?: AnalyzeProgressSink): Promise<DetectedAuth>;
 //# sourceMappingURL=auth-detector.d.ts.map

package/dist/tools/auth-detector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-detector.d.ts","sourceRoot":"","sources":["../../src/tools/auth-detector.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAwQtE,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;CAC9B,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAWrC;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,SAAS,SAAQ,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAelD;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,SAAS,SAAQ,GAChB,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA+B7C;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAqJvB"}
+{"version":3,"file":"auth-detector.d.ts","sourceRoot":"","sources":["../../src/tools/auth-detector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAItE,MAAM,MAAM,yBAAyB,GACjC,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,cAAc,GACd,yBAAyB,GACzB,iBAAiB,GACjB,SAAS,CAAC;AAEd,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAsQD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;CAC9B,GAAG,4BAA4B,CA6B/B;AAOD,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC,CAgD9C;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,SAAS,SAAQ,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAelD;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,SAAS,SAAQ,GAChB,OAAO,CAAC,4BAA4B,CAAC,CAyDvC;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAqJvB"}

package/dist/tools/auth-detector.js

@@ -1,4 +1,5 @@
 import { resolve } from 'node:path';
+import { readFile, stat } from 'node:fs/promises';
 import { launchBrowser } from './browser.js';
 import { BUILT_IN_OAUTH_PROVIDERS } from './oauth-providers.js';
 async function waitNetworkIdleBestEffort(page) {
@@ -235,16 +236,87 @@ async function probeClickToRevealForms(page, loginUrl, alreadyMatchedTexts, time
     return out;
 }
 export function evaluateStorageStateValidity(signals) {
-    if (new URL(signals.finalUrl).origin !== signals.expectedOrigin) {
-        return { valid: false, reason: 'session redirected to external IdP' };
+    let finalOrigin = null;
+    try {
+        finalOrigin = new URL(signals.finalUrl).origin;
+    }
+    catch {
+        finalOrigin = null;
+    }
+    if (finalOrigin === null || finalOrigin !== signals.expectedOrigin) {
+        return {
+            valid: false,
+            reasonCode: 'wrong-origin',
+            reason: 'session redirected to a different origin than the target app',
+        };
     }
     if (signals.visiblePasswordCount > 0) {
-        return { valid: false, reason: 'login form still visible after loading storage state' };
+        return {
+            valid: false,
+            reasonCode: 'expired-or-unauthorized',
+            reason: 'login form still visible after loading storage state (session likely expired)',
+        };
     }
     if (signals.hadUnauthorizedHttp) {
-        return { valid: false, reason: 'HTTP 401/403 on authenticated request' };
+        return {
+            valid: false,
+            reasonCode: 'expired-or-unauthorized',
+            reason: 'HTTP 401/403 on authenticated request (session likely expired or invalid)',
+        };
     }
-    return { valid: true, reason: 'session appears active' };
+    return { valid: true, reasonCode: 'ok', reason: 'session appears active' };
+}
+export async function preflightStorageStateFile(storagePath) {
+    let exists = false;
+    try {
+        const s = await stat(storagePath);
+        exists = s.isFile();
+    }
+    catch {
+        exists = false;
+    }
+    if (!exists) {
+        return {
+            valid: false,
+            reasonCode: 'missing-file',
+            reason: 'storage state file does not exist',
+        };
+    }
+    let raw;
+    try {
+        raw = await readFile(storagePath, 'utf8');
+    }
+    catch {
+        return {
+            valid: false,
+            reasonCode: 'unreadable-file',
+            reason: 'storage state file is not readable',
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            valid: false,
+            reasonCode: 'invalid-json',
+            reason: 'storage state file is not valid JSON',
+        };
+    }
+    const cookieCount = Array.isArray(parsed?.cookies) ? parsed.cookies.length : 0;
+    const originEntries = Array.isArray(parsed?.origins) ? parsed.origins : [];
+    const localStorageEntryCount = originEntries.reduce((sum, entry) => {
+        return sum + (Array.isArray(entry?.localStorage) ? entry.localStorage.length : 0);
+    }, 0);
+    if (cookieCount === 0 && localStorageEntryCount === 0) {
+        return {
+            valid: false,
+            reasonCode: 'no-auth-cookies',
+            reason: 'storage state file contains no cookies and no localStorage entries',
+        };
+    }
+    return null;
 }
 export async function waitForReturnToOrigin(page, baseUrl, timeoutMs = 15000) {
     const targetOrigin = new URL(baseUrl).origin;
@@ -264,8 +336,22 @@ export async function waitForReturnToOrigin(page, baseUrl, timeoutMs = 15000) {
     return { returned: false, finalUrl: page.url() };
 }
 export async function validateStorageState(url, storagePath, timeoutMs = 10000) {
+    let expectedOrigin;
+    try {
+        expectedOrigin = new URL(url).origin;
+    }
+    catch {
+        return {
+            valid: false,
+            reasonCode: 'unknown',
+            reason: 'target URL could not be parsed for origin matching',
+        };
+    }
     const storageAbs = resolve(process.cwd(), storagePath);
-    const expectedOrigin = new URL(url).origin;
+    const preflight = await preflightStorageStateFile(storageAbs);
+    if (preflight !== null) {
+        return preflight;
+    }
     let hadUnauthorizedHttp = false;
     const browser = await launchBrowser();
     try {
@@ -277,10 +363,22 @@ export async function validateStorageState(url, storagePath, timeoutMs = 10000)
                 hadUnauthorizedHttp = true;
             }
         });
-        await page.goto(url, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+        try {
+            await page.goto(url, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+        }
+        catch {
+            return {
+                valid: false,
+                reasonCode: 'unknown',
+                reason: 'navigation to target URL failed while validating storage state',
+            };
+        }
         await waitNetworkIdleBestEffort(page);
         const finalUrl = page.url();
-        const visiblePasswordCount = await page.locator('input[type="password"]:visible').count();
+        const visiblePasswordCount = await page
+            .locator('input[type="password"]:visible')
+            .count()
+            .catch(() => 0);
         return evaluateStorageStateValidity({
             expectedOrigin,
             finalUrl,

package/dist/tools/explorers/browser.d.ts

@@ -0,0 +1,3 @@
+import { type Browser } from '@playwright/test';
+export declare function launchBrowser(): Promise<Browser>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/tools/explorers/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE1D,wBAAsB,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAYtD"}

package/dist/tools/explorers/browser.js

@@ -0,0 +1,13 @@
+import { chromium } from '@playwright/test';
+export async function launchBrowser() {
+    try {
+        return await chromium.launch({ headless: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("Executable doesn't exist") || message.includes('chromium')) {
+            throw new Error(`Playwright Chromium browser is not installed. Run:\n\n  npx playwright install chromium\n\nThen retry your qulib command. This is a one-time setup step.`);
+        }
+        throw err;
+    }
+}

package/dist/tools/explorers/cypress-explorer.d.ts

@@ -0,0 +1,8 @@
+import type { AppExplorer } from './explorer.interface.js';
+import type { HarnessConfig } from '../../schemas/config.schema.js';
+import type { RouteInventory } from '../../schemas/route-inventory.schema.js';
+import type { RunArtifactsOptions } from '../../harness/run-options.js';
+export declare class CypressExplorer implements AppExplorer {
+    explore(_baseUrl: string, _config: HarnessConfig, _artifacts?: RunArtifactsOptions): Promise<RouteInventory>;
+}
+//# sourceMappingURL=cypress-explorer.d.ts.map

package/dist/tools/explorers/cypress-explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cypress-explorer.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/cypress-explorer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,qBAAa,eAAgB,YAAW,WAAW;IAC3C,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,UAAU,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;CAGnH"}

package/dist/tools/explorers/cypress-explorer.js

@@ -0,0 +1,5 @@
+export class CypressExplorer {
+    async explore(_baseUrl, _config, _artifacts) {
+        throw new Error('Not implemented');
+    }
+}

package/dist/tools/explorers/cypress.d.ts

@@ -0,0 +1,8 @@
+import type { AppExplorer } from './types.js';
+import type { HarnessConfig } from '../../schemas/config.schema.js';
+import type { RouteInventory } from '../../schemas/route-inventory.schema.js';
+import type { RunArtifactsOptions } from '../../harness/run-options.js';
+export declare class CypressExplorer implements AppExplorer {
+    explore(_baseUrl: string, _config: HarnessConfig, _artifacts?: RunArtifactsOptions): Promise<RouteInventory>;
+}
+//# sourceMappingURL=cypress.d.ts.map

package/dist/tools/explorers/cypress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cypress.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/cypress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,qBAAa,eAAgB,YAAW,WAAW;IAC3C,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,UAAU,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;CAGnH"}

package/dist/tools/explorers/cypress.js

@@ -0,0 +1,5 @@
+export class CypressExplorer {
+    async explore(_baseUrl, _config, _artifacts) {
+        throw new Error('Not implemented');
+    }
+}

package/dist/tools/explorers/explorer.interface.d.ts

@@ -0,0 +1,7 @@
+import type { HarnessConfig } from '../../schemas/config.schema.js';
+import type { RouteInventory } from '../../schemas/route-inventory.schema.js';
+import type { RunArtifactsOptions } from '../../harness/run-options.js';
+export interface AppExplorer {
+    explore(baseUrl: string, config: HarnessConfig, artifacts?: RunArtifactsOptions): Promise<RouteInventory>;
+}
+//# sourceMappingURL=explorer.interface.d.ts.map

package/dist/tools/explorers/explorer.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explorer.interface.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/explorer.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC3G"}

package/dist/tools/explorers/explorer.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/explorers/factory.d.ts

@@ -0,0 +1,4 @@
+import type { ExplorerType } from '../../schemas/config.schema.js';
+import type { AppExplorer } from './types.js';
+export declare function createExplorer(type: ExplorerType): AppExplorer;
+//# sourceMappingURL=factory.d.ts.map

package/dist/tools/explorers/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,CAS9D"}

package/dist/tools/explorers/factory.js

@@ -0,0 +1,12 @@
+import { PlaywrightExplorer } from './playwright.js';
+import { CypressExplorer } from './cypress.js';
+export function createExplorer(type) {
+    switch (type) {
+        case 'playwright':
+            return new PlaywrightExplorer();
+        case 'cypress':
+            return new CypressExplorer();
+        default:
+            throw new Error(`Unknown explorer type: ${type}`);
+    }
+}

package/dist/tools/explorers/playwright-explorer.d.ts

@@ -0,0 +1,8 @@
+import type { AppExplorer } from './explorer.interface.js';
+import { type RouteInventory } from '../../schemas/route-inventory.schema.js';
+import type { HarnessConfig } from '../../schemas/config.schema.js';
+import type { RunArtifactsOptions } from '../../harness/run-options.js';
+export declare class PlaywrightExplorer implements AppExplorer {
+    explore(baseUrl: string, config: HarnessConfig, artifacts?: RunArtifactsOptions): Promise<RouteInventory>;
+}
+//# sourceMappingURL=playwright-explorer.d.ts.map

package/dist/tools/explorers/playwright-explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-explorer.d.ts","sourceRoot":"","sources":["../../../src/tools/explorers/playwright-explorer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAwB,KAAK,cAAc,EAAc,MAAM,yCAAyC,CAAC;AAChH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAoBxE,qBAAa,kBAAmB,YAAW,WAAW;IAC9C,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;CAsKhH"}