@qulib/core 0.4.2 → 0.5.0

package/README.md

@@ -77,6 +77,24 @@ qulib analyze --url https://app.example.com --auth-storage-state ./qulib-storage
 
 The storage state is just a JSON file of cookies and localStorage — keep it private, treat it like a credential.
 
+#### Storage state is validated before crawl
+
+Qulib now validates the provided storage state before doing any work. If the file is missing, unreadable, empty, on the wrong origin, or carries a session that is already expired, Qulib stops with an honest `blocked` result (no fake `releaseConfidence`) and a structured gap explaining how to recover. The validator reports one of these stable reason codes:
+
+| Reason code               | Meaning                                                                 |
+| ------------------------- | ----------------------------------------------------------------------- |
+| `missing-file`            | Path passed to `--auth-storage-state` does not exist.                   |
+| `unreadable-file`         | File exists but the process can't read it (permissions).                |
+| `invalid-json`            | File is present and readable but not valid JSON.                        |
+| `no-auth-cookies`         | File parses, but has zero cookies and zero localStorage entries.        |
+| `wrong-origin`            | Session redirects to a different origin (host/port/scheme mismatch).    |
+| `expired-or-unauthorized` | Loaded session shows the login form again, or the app returns 401/403. |
+| `unknown`                 | Validation could not be completed for an unexpected reason.             |
+
+Origin matching is strict — `https://app.example` and `https://www.app.example` are different origins, as are `http://localhost:3000` and `http://localhost:4000`. Re-run `qulib auth login` against the same origin you plan to `analyze`.
+
+Relatedly, `qulib auth login` will now refuse to save a storage state if the browser ends the flow on a different origin than `--base-url` (a federated/SSO redirect that never returned to the app). This prevents Qulib from quietly persisting an IdP-domain session that would later produce false-confidence scans.
+
 ### Multi-path auth exploration (`explore-auth`)
 
 For unfamiliar apps (especially enterprise SSO with several buttons), run **`qulib explore-auth --url <url>`** before `analyze`. The JSON lists every detected path (built-in OAuth names like Google/Clever, **heuristic** unknown buttons such as tenant-specific SSO labels, password forms, and magic-link copy) plus **`suggestedAgentBehavior`** for the agent.
@@ -194,16 +212,24 @@ TypeScript (strict, NodeNext), Commander, Zod, Playwright, @axe-core/playwright,
 ```text
 src/
   adapters/      # test rendering adapters
-  analyze.ts     # programmatic API (also used by @qulib/mcp)
-  cli/           # CLI entry
-  harness/       # state + decision logging
-  llm/           # LLM contracts
-  phases/        # observe / think / act
-  reporters/     # JSON + Markdown reports
-  schemas/       # Zod schemas
-  tools/         # explorers, auth, gap engine, repo scanner
+  analyze.ts        # programmatic API (also used by @qulib/mcp)
+  cli/              # CLI entry
+  harness/          # state + decision logging
+  llm/              # LLM contracts
+  phases/           # observe / think / act
+  reporters/        # JSON + Markdown reports
+  schemas/          # Zod schemas
+  telemetry/        # event sink + URL redaction
+  tools/
+    auth/           # detection, exploration, validation, providers, gap builders
+    explorers/      # browser launch, Playwright/Cypress crawlers, factory
+    repo/           # repo scanner, framework detection
+    scoring/        # gap engine, automation maturity, public surface
+  __tests__/        # integration and wiring tests live in __tests__/ in each folder
 ```
 
+A contributor map of which folder to touch for each kind of change lives at [`docs/source-map.md`](../../docs/source-map.md).
+
 Repo rules: see [`CLAUDE.md`](../../CLAUDE.md).
 
 ## Configuration
@@ -251,6 +277,107 @@ npm run analyze -- --url https://example.com --ephemeral > report.bundle.json
 npm run clean
 ```
 
+## Minimum config
+
+Smallest legal `qulib.config.ts`:
+
+```ts
+import type { HarnessConfig } from './src/schemas/config.schema.js';
+
+const config: HarnessConfig = {
+  maxPagesToScan: 20,
+  maxDepth: 3,
+  timeoutMs: 30000,
+};
+
+export default config;
+```
+
+All other fields inherit from schema defaults or CLI/runtime defaults.
+
+## Scan walkthroughs (copy-paste)
+
+### 1) Public scan
+
+```bash
+npx @qulib/core analyze --url https://yourapp.com
+```
+
+### 2) Auth-blocked scan (honest blocked mode)
+
+```bash
+npx @qulib/core analyze --url https://yourapp.com/auth
+```
+
+When auth blocks access and no auth config is supplied, Qulib reports `status: "blocked"` (or `partial` if it could still crawl some public pages). This is intentional honesty, not a failure mode.
+
+### 3) Authenticated scan with storage state
+
+```bash
+# Capture once (manual OAuth/SSO-safe flow)
+qulib auth init --base-url https://yourapp.com
+
+# Reuse saved session
+qulib analyze --url https://yourapp.com --auth-storage-state ./qulib-storage-state.json
+```
+
+## Sample report (fixture baseline)
+
+From the local fixture baseline used in v0.5.0 PR 1/2:
+
+```json
+{
+  "status": "complete",
+  "releaseConfidence": 68,
+  "gaps": [
+    "... 4 total gap items ..."
+  ]
+}
+```
+
+Use these as conservative reference numbers:
+- public fixture (`/`): `releaseConfidence: 68/100`, `gaps: 4`
+- auth-wall fixture (`/auth`): `releaseConfidence: 24/100`, `gaps: 2`
+- broken fixture (`/broken`): `releaseConfidence: 0/100`, `gaps: 6`
+
+## MCP tools quick map
+
+| Tool | When to use | Key input |
+|---|---|---|
+| `analyze_app` | Main QA scan for release confidence + gaps | `url`, optional `auth`, optional LLM knobs |
+| `detect_auth` | Fast single-pass auth pattern guess | `url`, optional `timeoutMs` |
+| `explore_auth` | Deeper auth-path discovery on unfamiliar apps | `url`, optional `timeoutMs` |
+| `qulib_score_automation` | Score local repo automation maturity | absolute `repoPath`, optional `includeFullDimensions` |
+
+## Output directories
+
+Qulib writes runtime artifacts to:
+
+- `.scan-state/` — intermediate state (discovered routes, gap analysis snapshots, decision log)
+- `output/` — final `report.json` and `report.md`
+
+Both are gitignored and safe to delete; Qulib recreates them on the next non-ephemeral run.
+
+## ANTHROPIC_API_KEY (LLM scenarios)
+
+For MCP-hosted usage, set `ANTHROPIC_API_KEY` in your host's `env` block:
+
+```json
+{
+  "mcpServers": {
+    "qulib": {
+      "command": "npx",
+      "args": ["@qulib/mcp"],
+      "env": {
+        "ANTHROPIC_API_KEY": "sk-ant-..."
+      }
+    }
+  }
+}
+```
+
+Without this key, Qulib still runs deterministic checks (crawl, a11y, links, console, scoring) and falls back to template scenarios instead of LLM-generated ones.
+
 ## Playwright browsers
 
 ```bash

package/dist/__tests__/cli-smoke-fixture.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli-smoke-fixture.d.ts.map

package/dist/__tests__/cli-smoke-fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-smoke-fixture.d.ts","sourceRoot":"","sources":["../../src/__tests__/cli-smoke-fixture.ts"],"names":[],"mappings":""}

package/dist/__tests__/cli-smoke-fixture.js

@@ -0,0 +1,58 @@
+/**
+ * Offline CLI smoke: spawn `node bin/qulib.js analyze --url <fixture>` against
+ * the local fixture server and assert the CLI exited 0. Runnable script (not a
+ * node:test file) — invoked in CI by `node --import tsx/esm src/__tests__/cli-smoke-fixture.ts`.
+ *
+ * Removes the live `https://example.com` dependency from CI's smoke-test-cli job.
+ *
+ * The fixture server runs in this process; the CLI is spawned as a child. We use
+ * async `spawn` (not `spawnSync`) so the parent event loop stays free to serve
+ * the child's HTTP requests against the fixture.
+ */
+import { spawn } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { startFixtureServer } from './fixture-server.js';
+const __dir = dirname(fileURLToPath(import.meta.url));
+const cliPath = resolve(__dir, '../../bin/qulib.js');
+function runCli(url) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn('node', [cliPath, 'analyze', '--url', url, '--ephemeral'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout.on('data', (chunk) => stdoutChunks.push(chunk));
+        child.stderr.on('data', (chunk) => stderrChunks.push(chunk));
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            rejectPromise(new Error('CLI smoke timed out after 120s'));
+        }, 120_000);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            rejectPromise(err);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolvePromise({
+                exitCode: code ?? -1,
+                stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+                stderr: Buffer.concat(stderrChunks).toString('utf8'),
+            });
+        });
+    });
+}
+function assertCliPassed(result) {
+    if (result.exitCode !== 0) {
+        throw new Error(`CLI exited with code ${result.exitCode}\n--- stdout ---\n${result.stdout}\n--- stderr ---\n${result.stderr}`);
+    }
+}
+const handle = await startFixtureServer();
+try {
+    const result = await runCli(`${handle.baseUrl}/`);
+    assertCliPassed(result);
+    console.log('[cli-smoke] ✔ CLI exited 0 against fixture public surface');
+}
+finally {
+    await handle.close();
+}

package/dist/__tests__/fixture-server.d.ts

@@ -0,0 +1,6 @@
+export interface FixtureServerHandle {
+    baseUrl: string;
+    close: () => Promise<void>;
+}
+export declare function startFixtureServer(): Promise<FixtureServerHandle>;
+//# sourceMappingURL=fixture-server.d.ts.map

package/dist/__tests__/fixture-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture-server.d.ts","sourceRoot":"","sources":["../../src/__tests__/fixture-server.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAyGD,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,mBAAmB,CAAC,CA0CvE"}

package/dist/__tests__/fixture-server.js

@@ -0,0 +1,141 @@
+/**
+ * Deterministic Node.js fixture server for offline Qulib integration tests.
+ *
+ * Serves the static HTML files in `packages/core/fixtures/` over loopback so
+ * the test suite never depends on a live website. Used by
+ * `analyze.fixtures.test.ts` and any future offline integration coverage.
+ *
+ * Never imported by product code. Helpers are private to this module; only
+ * `startFixtureServer` and `FixtureServerHandle` are exported.
+ */
+import { createServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const HTML_CONTENT_TYPE = 'text/html; charset=utf-8';
+const TEXT_CONTENT_TYPE = 'text/plain; charset=utf-8';
+function resolveFixturesDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, '../../fixtures');
+}
+function routeToFile(pathname) {
+    if (pathname.includes('..'))
+        return null;
+    const fixturesDir = resolveFixturesDir();
+    if (pathname === '/' || pathname === '/index.html') {
+        return join(fixturesDir, 'public/index.html');
+    }
+    if (pathname === '/about') {
+        return join(fixturesDir, 'public/about.html');
+    }
+    if (pathname === '/features') {
+        return join(fixturesDir, 'public/features.html');
+    }
+    if (pathname === '/docs') {
+        return join(fixturesDir, 'public/index.html');
+    }
+    if (pathname === '/auth') {
+        return join(fixturesDir, 'auth-wall/index.html');
+    }
+    if (pathname === '/authenticated' || pathname.startsWith('/authenticated/')) {
+        return join(fixturesDir, 'authenticated/index.html');
+    }
+    if (pathname === '/broken') {
+        return join(fixturesDir, 'broken/index.html');
+    }
+    return null;
+}
+async function readFixture(filePath) {
+    return readFile(filePath);
+}
+function respond(res, status, body, contentType) {
+    const buf = typeof body === 'string' ? Buffer.from(body, 'utf8') : body;
+    res.writeHead(status, {
+        'Content-Type': contentType,
+        'Content-Length': buf.length,
+        'Cache-Control': 'no-store',
+    });
+    res.end(buf);
+}
+function respondNotFound(res) {
+    respond(res, 404, 'Not found', TEXT_CONTENT_TYPE);
+}
+function respondServerError(res, message) {
+    respond(res, 500, `Fixture server error: ${message}`, TEXT_CONTENT_TYPE);
+}
+function respondMethodNotAllowed(res) {
+    res.writeHead(405, {
+        Allow: 'GET',
+        'Content-Type': TEXT_CONTENT_TYPE,
+        'Cache-Control': 'no-store',
+    });
+    res.end('Method Not Allowed');
+}
+async function handleRequest(req, res) {
+    try {
+        if (req.method !== 'GET') {
+            respondMethodNotAllowed(res);
+            return;
+        }
+        const rawUrl = req.url ?? '/';
+        let pathname;
+        try {
+            pathname = new URL(rawUrl, 'http://127.0.0.1').pathname;
+        }
+        catch {
+            respondNotFound(res);
+            return;
+        }
+        const filePath = routeToFile(pathname);
+        if (filePath === null) {
+            respondNotFound(res);
+            return;
+        }
+        const body = await readFixture(filePath);
+        respond(res, 200, body, HTML_CONTENT_TYPE);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        respondServerError(res, message);
+    }
+}
+export async function startFixtureServer() {
+    const fixturesDir = resolveFixturesDir();
+    try {
+        const s = await stat(fixturesDir);
+        if (!s.isDirectory()) {
+            throw new Error(`fixtures path is not a directory: ${fixturesDir}`);
+        }
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`Fixture directory not found at ${fixturesDir}: ${detail}`);
+    }
+    const server = createServer((req, res) => {
+        void handleRequest(req, res);
+    });
+    await new Promise((resolvePromise, rejectPromise) => {
+        server.once('error', rejectPromise);
+        server.listen(0, '127.0.0.1', () => {
+            server.off('error', rejectPromise);
+            resolvePromise();
+        });
+    });
+    const address = server.address();
+    if (address === null || typeof address === 'string') {
+        server.close();
+        throw new Error('Fixture server did not return a usable address after listen');
+    }
+    const baseUrl = `http://127.0.0.1:${address.port}`;
+    return {
+        baseUrl,
+        close: () => new Promise((resolvePromise, rejectPromise) => {
+            server.close((err) => {
+                if (err)
+                    rejectPromise(err);
+                else
+                    resolvePromise();
+            });
+        }),
+    };
+}

package/dist/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAChG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAU7F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAGxE,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,0GAA0G;IAC1G,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,sFAAsF;IACtF,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,WAAW,EAAE,WAAW,CAAC;IACzB,8GAA8G;IAC9G,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0HAA0H;IAC1H,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;CACrC;AAcD,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA8JhF"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAChG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAU7F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAGxE,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,0GAA0G;IAC1G,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,sFAAsF;IACtF,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,WAAW,EAAE,WAAW,CAAC;IACzB,8GAA8G;IAC9G,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0HAA0H;IAC1H,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;CACrC;AAcD,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAqQhF"}

package/dist/analyze.js

@@ -4,11 +4,11 @@ import { PublicSurfaceSchema } from './schemas/public-surface.schema.js';
 import { observe } from './phases/observe.js';
 import { think } from './phases/think.js';
 import { act } from './phases/act.js';
-import { detectAuth } from './tools/auth-detector.js';
-import { analyzeGaps, computeCoverageScore, computeQualityScoreFromGaps } from './tools/gap-engine.js';
-import { analyzeAuthSurfaceGaps } from './tools/auth-surface-analyzer.js';
-import { buildPublicSurface } from './tools/public-surface.js';
-import { buildAuthBlockGap } from './tools/auth-block-gap.js';
+import { detectAuth, validateStorageState } from './tools/auth/detect.js';
+import { analyzeGaps, computeCoverageScore, computeQualityScoreFromGaps } from './tools/scoring/gaps.js';
+import { analyzeAuthSurfaceGaps } from './tools/auth/surface.js';
+import { buildPublicSurface } from './tools/scoring/public-surface.js';
+import { buildAuthBlockGap, buildStorageStateInvalidGap } from './tools/auth/gaps.js';
 import { finalizeGapAnalysisFromDraft } from './phases/think-finalize.js';
 import { emitTelemetry, redactUrlForTelemetry } from './telemetry/emit.js';
 function logScanEnd(progress, result) {
@@ -40,6 +40,85 @@ export async function analyzeApp(options) {
         hasAuth: Boolean(options.config.auth),
     });
     progress?.info(`Starting scan → ${options.url} maxPagesToScan=${options.config.maxPagesToScan}`);
+    if (options.config.auth?.type === 'storage-state') {
+        progress?.info('Validating provided storage state before crawl…');
+        const validation = await validateStorageState(options.url, options.config.auth.path, options.config.timeoutMs);
+        let targetOriginForTelemetry;
+        try {
+            targetOriginForTelemetry = new URL(options.url).origin;
+        }
+        catch {
+            targetOriginForTelemetry = '[unparseable-target-url]';
+        }
+        emitTelemetry(options.telemetry, 'auth.storage-state.validated', sessionId, {
+            targetOrigin: targetOriginForTelemetry,
+            valid: validation.valid,
+            reasonCode: validation.reasonCode,
+            storageStateProvided: true,
+        });
+        if (!validation.valid) {
+            progress?.warn(`Storage state rejected (${validation.reasonCode}): ${validation.reason}. Skipping crawl.`);
+            decisionLog.push({
+                timestamp: new Date().toISOString(),
+                phase: 'observe',
+                decision: 'storage-state-invalid',
+                reason: `${validation.reasonCode}: ${validation.reason}`,
+                metadata: {
+                    reasonCode: validation.reasonCode,
+                    targetOrigin: targetOriginForTelemetry,
+                },
+            });
+            const invalidGap = buildStorageStateInvalidGap({
+                url: options.url,
+                reasonCode: validation.reasonCode === 'ok' ? 'unknown' : validation.reasonCode,
+                reason: validation.reason,
+            });
+            const draft = {
+                analyzedAt: new Date().toISOString(),
+                mode: 'auth-required',
+                releaseConfidence: 0,
+                coveragePagesScanned: 0,
+                coverageBudgetExceeded: false,
+                coverageWarning: 'auth-required',
+                gaps: [invalidGap],
+            };
+            const costContext = {
+                mode: 'auth-required',
+                coveragePagesScanned: 0,
+                releaseConfidence: 0,
+                gaps: [invalidGap],
+            };
+            const gapAnalysis = await finalizeGapAnalysisFromDraft(draft, options.config, artifacts, costContext);
+            const emptyAuthRoutes = RouteInventorySchema.parse({
+                scannedAt: new Date().toISOString(),
+                baseUrl: options.url,
+                routes: [],
+                pagesSkipped: 0,
+                budgetExceeded: false,
+            });
+            await act(gapAnalysis, options.config, artifacts);
+            const blockedResult = {
+                status: 'blocked',
+                coverageScore: null,
+                releaseConfidence: 0,
+                gaps: gapAnalysis.gaps,
+                gapAnalysis,
+                routeInventory: emptyAuthRoutes,
+                repoInventory: null,
+                decisionLog,
+                publicSurface: null,
+            };
+            logScanEnd(progress, blockedResult);
+            emitTelemetry(options.telemetry, 'scan.blocked', sessionId, {
+                status: blockedResult.status,
+                coverageScore: blockedResult.coverageScore,
+                releaseConfidence: blockedResult.releaseConfidence,
+                gapCount: blockedResult.gaps.length,
+                reasonCode: validation.reasonCode,
+            });
+            return blockedResult;
+        }
+    }
     let detectedAuth;
     let authWall = false;
     if (!options.config.auth && !options.skipAuthDetection) {

package/dist/cli/auth-login-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-login-run.d.ts","sourceRoot":"","sources":["../../src/cli/auth-login-run.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAqB5D,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAEhE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4GhB"}
+{"version":3,"file":"auth-login-run.d.ts","sourceRoot":"","sources":["../../src/cli/auth-login-run.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAsB5D,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAEhE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoIhB"}

package/dist/cli/auth-login-run.js

@@ -1,4 +1,5 @@
-import { BUILT_IN_OAUTH_PROVIDERS } from '../tools/oauth-providers.js';
+import { BUILT_IN_OAUTH_PROVIDERS } from '../tools/auth/providers.js';
+import { waitForReturnToOrigin } from '../tools/auth/detect.js';
 const builtInOAuthIds = new Set(BUILT_IN_OAUTH_PROVIDERS.map((p) => p.id));
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -109,8 +110,31 @@ export async function runAutomatedAuthLogin(params) {
                 await sleep(250);
             }
         }
+        const originReturn = await waitForReturnToOrigin(page, params.baseUrlHint, params.timeoutMs);
+        if (!originReturn.returned) {
+            let targetOrigin = '<unknown>';
+            let finalOrigin = '<unknown>';
+            try {
+                targetOrigin = new URL(params.baseUrlHint).origin;
+            }
+            catch {
+                /* targetOrigin stays <unknown> */
+            }
+            try {
+                finalOrigin = new URL(originReturn.finalUrl).origin;
+            }
+            catch {
+                /* finalOrigin stays <unknown> */
+            }
+            throw new Error(`Login flow did not return to the app origin (expected ${targetOrigin}, final ${finalOrigin}). ` +
+                `Refusing to save the storage state — it would belong to the wrong domain and produce ` +
+                `false-confidence scans. Retry the login (the federated provider may need a redirect tweak) ` +
+                `or capture the session manually with \`qulib auth init --base-url ${params.baseUrlHint}\`.`);
+        }
         if (!confirmed) {
-            console.error('[qulib] Could not confirm login success. Storage state saved; verify manually before relying on it.');
+            console.error('[qulib] Could not confirm login success heuristically, but the browser ended on the app origin. ' +
+                'Storage state will be saved; verify the session before relying on it (run `qulib analyze` ' +
+                'and check that releaseConfidence is not null).');
         }
         const fs = await import('node:fs/promises');
         const pathMod = await import('node:path');

package/dist/cli/index.js

@@ -8,8 +8,8 @@ const requirePkg = createRequire(import.meta.url);
 const pkg = requirePkg('../../package.json');
 import { HarnessConfigSchema } from '../schemas/config.schema.js';
 import { analyzeApp } from '../analyze.js';
-import { detectAuth } from '../tools/auth-detector.js';
-import { exploreAuth } from '../tools/auth-explorer.js';
+import { detectAuth } from '../tools/auth/detect.js';
+import { exploreAuth } from '../tools/auth/explore.js';
 import { assertExactlyOneCredentialSource, parseCredentialsJsonString, resolveAuthLoginConfig, } from './auth-login-resolve.js';
 import { runAutomatedAuthLogin } from './auth-login-run.js';
 const program = new Command();
@@ -33,11 +33,14 @@ function redactConfigForLog(config) {
         base.auth = {
             ...config.auth,
             credentials: {
-                username: config.auth.credentials.username,
+                username: '***',
                 password: '***',
             },
         };
     }
+    if (config.auth?.type === 'storage-state') {
+        base.auth = { type: 'storage-state', path: '<provided>' };
+    }
     return base;
 }
 function mergeAuthFromCli(config, options) {
@@ -95,6 +98,7 @@ async function runAnalyze(options) {
         repoPath: options.repo,
         config,
         writeArtifacts,
+        skipAuthDetection: options.skipAuthDetection,
     });
     if (ephemeral) {
         console.log(JSON.stringify({
@@ -154,6 +158,7 @@ program
     .option('--config <file>', 'Path to config file (relative to cwd)', 'qulib.config.ts')
     .option('--adapter <type>', 'Override default test adapter (playwright, cypress-e2e, cypress-component, api)', 'playwright')
     .option('--ephemeral', 'Do not write to disk — return full report as JSON on stdout (use for MCP/CI)', false)
+    .option('--skip-auth-detection', 'Crawl the public surface even if auth is detected (useful for sites with sign-in CTAs on public pages)', false)
     .option('--auth-storage-state <path>', 'Path to a storage state JSON file (use after `qulib auth init`)')
     .option('--auth-form-login', 'Use form-login; requires --login-url, credentials, and selectors', false)
     .option('--login-url <url>', 'Form login page URL (required with --auth-form-login)')
@@ -176,6 +181,7 @@ program
         repo: options.repo,
         configFile: options.config,
         ephemeral: options.ephemeral,
+        skipAuthDetection: Boolean(options.skipAuthDetection),
         authStorageState: options.authStorageState,
         authFormLogin,
         loginUrl,
@@ -212,7 +218,7 @@ providersCmd
     .command('list')
     .description('List user-local providers registered on this machine')
     .action(async () => {
-    const { listUserProviders } = await import('../tools/user-providers.js');
+    const { listUserProviders } = await import('../tools/auth/custom-providers.js');
     const providers = listUserProviders();
     console.log(JSON.stringify(providers, null, 2));
 });
@@ -229,7 +235,7 @@ providersCmd
     catch {
         throw new Error(`Invalid regex pattern: ${opts.pattern}`);
     }
-    const { addUserProvider } = await import('../tools/user-providers.js');
+    const { addUserProvider } = await import('../tools/auth/custom-providers.js');
     addUserProvider({ id: opts.id, label: opts.label, pattern: opts.pattern });
     console.log(`[qulib] Added provider "${opts.label}" (id: ${opts.id}) to ~/.qulib/providers.json`);
 });
@@ -238,7 +244,7 @@ providersCmd
     .description('Remove a user-local provider by id')
     .requiredOption('--id <id>', 'Provider id to remove')
     .action(async (opts) => {
-    const { removeUserProvider } = await import('../tools/user-providers.js');
+    const { removeUserProvider } = await import('../tools/auth/custom-providers.js');
     const removed = removeUserProvider(opts.id);
     console.log(removed ? `[qulib] Removed "${opts.id}"` : `[qulib] No provider with id "${opts.id}" found`);
 });

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { analyzeApp } from './analyze.js';
-export { detectAuth } from './tools/auth-detector.js';
-export { exploreAuth } from './tools/auth-explorer.js';
-export { addUserProvider, removeUserProvider, listUserProviders } from './tools/user-providers.js';
-export { scanRepo } from './tools/repo-scanner.js';
-export { computeAutomationMaturity } from './tools/automation-maturity.js';
+export { detectAuth, validateStorageState, evaluateStorageStateValidity, preflightStorageStateFile, waitForReturnToOrigin, } from './tools/auth/detect.js';
+export type { StorageStateInvalidReason, StorageStateValidationResult, } from './tools/auth/detect.js';
+export { exploreAuth } from './tools/auth/explore.js';
+export { addUserProvider, removeUserProvider, listUserProviders } from './tools/auth/custom-providers.js';
+export { scanRepo } from './tools/repo/scan.js';
+export { computeAutomationMaturity } from './tools/scoring/automation-maturity.js';
 export { createProvider } from './llm/provider-registry.js';
 export { resolveMaxOutputTokensPerLlmCall } from './schemas/config.schema.js';
 export { resolveScanStateBaseDir, resolveReportDir } from './harness/state-manager.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnG,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,gCAAgC,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACvF,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACjF,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,YAAY,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC9E,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,YAAY,EACV,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,4BAA4B,EAC5B,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,yBAAyB,EACzB,4BAA4B,GAC7B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAC1G,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,gCAAgC,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACvF,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACjF,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,YAAY,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC9E,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,YAAY,EACV,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC"}