@qulib/core 0.4.1 → 0.4.3

package/README.md

@@ -47,6 +47,28 @@ qulib auth init --base-url https://app.example.com
 
 This opens a real browser. Log in normally (OAuth, magic link, password manager, whatever). Press ENTER in the terminal when you reach a logged-in page. Qulib saves your session to `qulib-storage-state.json`.
 
+### Automated form login (`auth login`)
+
+When **`detect-auth`** shows **`authOptions`** with **`type: "form-login"`** and **`requirements.method: "credentials"`** (including click-to-reveal paths such as Scholastic Sync), you can save a storage state **without** manual clicking:
+
+```bash
+qulib auth login --base-url https://platform.scholastic.com \
+  --auth-path scholastic-sync \
+  --credentials-file ~/.qulib/scholastic-creds.json \
+  --out ~/.qulib/scholastic-state.json
+```
+
+The JSON file must map **field `name`** values from `authOptions` to secrets, e.g. `{"username":"…","password":"…","hidden.datasource":"…"}`. Prefer **`--credentials-file`** over **`--credentials`** so values are not stored in shell history.
+
+Then analyze with the saved session:
+
+```bash
+qulib analyze --url https://platform.scholastic.com \
+  --auth-storage-state ~/.qulib/scholastic-state.json
+```
+
+Use **`--auth-path <id>`** when multiple **`form-login`** paths appear in **`authOptions`**. Use **`--success-url-contains <substring>`** for stricter success detection; otherwise Qulib infers success from URL changes or the password field disappearing (and warns if it cannot confirm).
+
 Then scan with it:
 
 ```bash
@@ -55,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.
@@ -172,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

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,13 +4,13 @@ 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 } from './telemetry/emit.js';
+import { emitTelemetry, redactUrlForTelemetry } from './telemetry/emit.js';
 function logScanEnd(progress, result) {
     const rc = result.releaseConfidence === null ? 'null' : String(result.releaseConfidence);
     const cs = result.coverageScore === null ? 'null' : String(result.coverageScore);
@@ -35,11 +35,90 @@ export async function analyzeApp(options) {
         ...(progress !== undefined && { progressLog: progress }),
     };
     emitTelemetry(options.telemetry, 'scan.started', sessionId, {
-        url: options.url,
+        url: redactUrlForTelemetry(options.url),
         maxPagesToScan: options.config.maxPagesToScan,
         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-resolve.d.ts

@@ -0,0 +1,14 @@
+import type { AuthPath } from '../schemas/config.schema.js';
+export declare function assertExactlyOneCredentialSource(credentials?: string, credentialsFile?: string): void;
+export declare function parseCredentialsJsonString(json: string): Record<string, string>;
+export declare function resolveFormLoginPath(baseUrl: string, authOptions: AuthPath[] | undefined, authPathId?: string): AuthPath;
+export declare function assertCredentialsCoverFields(credentials: Record<string, string>, path: AuthPath): void;
+export declare function resolveAuthLoginConfig(params: {
+    baseUrl: string;
+    authOptions: AuthPath[] | undefined;
+    credentials: Record<string, string>;
+    authPathId?: string;
+}): {
+    path: AuthPath;
+};
+//# sourceMappingURL=auth-login-resolve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth-login-resolve.d.ts","sourceRoot":"","sources":["../../src/cli/auth-login-resolve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5D,wBAAgB,gCAAgC,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CASrG;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkB/E;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,SAAS,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,CAsBxH;AAED,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAatG;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,QAAQ,EAAE,GAAG,SAAS,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAIrB"}

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

@@ -0,0 +1,68 @@
+export function assertExactlyOneCredentialSource(credentials, credentialsFile) {
+    const hasC = Boolean(credentials && String(credentials).trim().length > 0);
+    const hasF = Boolean(credentialsFile && String(credentialsFile).trim().length > 0);
+    if (hasC && hasF) {
+        throw new Error('Provide either --credentials or --credentials-file, not both.');
+    }
+    if (!hasC && !hasF) {
+        throw new Error('One of --credentials or --credentials-file is required.');
+    }
+}
+export function parseCredentialsJsonString(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new Error('Invalid JSON in --credentials');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('--credentials must be a JSON object mapping field name → value.');
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        if (v === undefined || v === null) {
+            throw new Error(`Credential value for "${k}" cannot be null or undefined.`);
+        }
+        out[k] = String(v);
+    }
+    return out;
+}
+export function resolveFormLoginPath(baseUrl, authOptions, authPathId) {
+    const formPaths = (authOptions ?? []).filter((o) => o.type === 'form-login' && o.requirements.method === 'credentials');
+    if (formPaths.length === 0) {
+        throw new Error(`No automatable form-login path detected on ${baseUrl}. Use \`qulib auth init\` for manual login.`);
+    }
+    if (formPaths.length === 1) {
+        return formPaths[0];
+    }
+    if (!authPathId || !authPathId.trim()) {
+        const ids = formPaths.map((p) => p.id).join(', ');
+        throw new Error(`Multiple form-login options found: ${ids}. Re-run with --auth-path <id>.`);
+    }
+    const found = formPaths.find((p) => p.id === authPathId.trim());
+    if (!found) {
+        const ids = formPaths.map((p) => p.id).join(', ');
+        throw new Error(`No form-login authOption with id "${authPathId}". Available: ${ids}.`);
+    }
+    return found;
+}
+export function assertCredentialsCoverFields(credentials, path) {
+    if (path.requirements.method !== 'credentials') {
+        throw new Error('Internal error: expected credentials requirements on form-login path.');
+    }
+    const missing = [];
+    for (const f of path.requirements.fields) {
+        if (!(f.name in credentials) || credentials[f.name] === '') {
+            missing.push(f.name);
+        }
+    }
+    if (missing.length > 0) {
+        throw new Error(`Missing credential value(s) for field name(s): ${missing.join(', ')}`);
+    }
+}
+export function resolveAuthLoginConfig(params) {
+    const path = resolveFormLoginPath(params.baseUrl, params.authOptions, params.authPathId);
+    assertCredentialsCoverFields(params.credentials, path);
+    return { path };
+}

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

@@ -0,0 +1,13 @@
+import type { AuthPath } from '../schemas/config.schema.js';
+export declare function authPathNeedsClickReveal(path: AuthPath): boolean;
+export declare function runAutomatedAuthLogin(params: {
+    loginUrl: string;
+    path: AuthPath;
+    credentials: Record<string, string>;
+    outPath: string;
+    headed: boolean;
+    timeoutMs: number;
+    successUrlContains?: string;
+    baseUrlHint: string;
+}): Promise<void>;
+//# sourceMappingURL=auth-login-run.d.ts.map

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

@@ -0,0 +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;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

@@ -0,0 +1,152 @@
+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, '\\$&');
+}
+async function waitNetworkIdleBestEffort(page) {
+    try {
+        await page.waitForLoadState('networkidle', { timeout: 5000 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export function authPathNeedsClickReveal(path) {
+    return path.type === 'form-login' && path.source === 'heuristic' && !builtInOAuthIds.has(path.id);
+}
+export async function runAutomatedAuthLogin(params) {
+    const { chromium } = await import('@playwright/test');
+    const browser = await chromium.launch({ headless: !params.headed });
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    let confirmed = false;
+    try {
+        await page.goto(params.loginUrl, { waitUntil: 'domcontentloaded', timeout: params.timeoutMs });
+        await waitNetworkIdleBestEffort(page);
+        if (authPathNeedsClickReveal(params.path)) {
+            try {
+                await page.getByRole('button', { name: params.path.label, exact: true }).first().click({ timeout: 2000 });
+            }
+            catch {
+                await page
+                    .locator('button')
+                    .filter({ hasText: new RegExp(`^\\s*${escapeRegExp(params.path.label)}\\s*$`, 'i') })
+                    .first()
+                    .click({ timeout: 2000 });
+            }
+            await page.locator('input[type="password"]').first().waitFor({ state: 'visible', timeout: 2000 });
+        }
+        if (params.path.requirements.method !== 'credentials') {
+            throw new Error('Internal error: expected credentials method on form-login path.');
+        }
+        for (const field of params.path.requirements.fields) {
+            const val = params.credentials[field.name];
+            const nameJson = JSON.stringify(field.name);
+            const inputByName = `input[name=${nameJson}]`;
+            const selectByName = `select[name=${nameJson}]`;
+            try {
+                if (field.type === 'select') {
+                    const sel = page.locator(selectByName).first();
+                    try {
+                        await sel.selectOption(val, { timeout: 8000 });
+                    }
+                    catch {
+                        await sel.selectOption({ label: val }, { timeout: 8000 });
+                    }
+                }
+                else if (field.type === 'checkbox') {
+                    const loc = page.locator(`input[type="checkbox"][name=${nameJson}]`).first();
+                    if (val === 'true' || val === '1' || val === 'on' || val === 'yes') {
+                        await loc.check({ timeout: 8000 });
+                    }
+                    else {
+                        await loc.uncheck({ timeout: 8000 });
+                    }
+                }
+                else {
+                    await page.locator(inputByName).first().fill(val, { timeout: 8000 });
+                }
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                throw new Error(`Failed to fill field "${field.name}" (${field.label}): ${msg}`);
+            }
+        }
+        const preSubmit = page.url();
+        try {
+            await page.locator('button[type="submit"]').first().click({ timeout: 8000 });
+        }
+        catch {
+            await page.locator('input[type="password"]').first().press('Enter');
+        }
+        if (params.successUrlContains && params.successUrlContains.trim().length > 0) {
+            const frag = params.successUrlContains.trim();
+            try {
+                await page.waitForURL((u) => u.toString().includes(frag), { timeout: params.timeoutMs });
+                confirmed = true;
+            }
+            catch {
+                confirmed = false;
+            }
+        }
+        else {
+            const t0 = Date.now();
+            while (Date.now() - t0 < params.timeoutMs) {
+                if (page.url() !== preSubmit) {
+                    confirmed = true;
+                    break;
+                }
+                if (Date.now() - t0 >= 5000) {
+                    const vis = await page.locator('input[type="password"]:visible').count();
+                    if (vis === 0) {
+                        confirmed = true;
+                        break;
+                    }
+                }
+                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 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');
+        const outAbs = pathMod.resolve(params.outPath);
+        await fs.mkdir(pathMod.dirname(outAbs), { recursive: true });
+        await context.storageState({ path: outAbs });
+        console.log(`\n[qulib] Saved storage state to ${outAbs}`);
+        console.log('[qulib] To use it, pass to qulib like:');
+        console.log(`        qulib analyze --url ${params.baseUrlHint} --auth-storage-state ${outAbs}`);
+        console.log(`[qulib] Or in MCP, pass auth: { type: 'storage-state', path: '${outAbs}' }`);
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/cli/index.js

@@ -1,12 +1,17 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
+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();
 const AnalyzeUrlSchema = z.string().url();
 const FormLoginCliSchema = z.object({
@@ -28,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) {
@@ -109,7 +117,7 @@ async function runAnalyze(options) {
 program
     .name('qulib')
     .description('Qulib — QA harness')
-    .version('0.1.0');
+    .version(pkg.version);
 program
     .command('clean')
     .description('Remove all generated reports and scan state')
@@ -207,7 +215,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));
 });
@@ -224,7 +232,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`);
 });
@@ -233,7 +241,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`);
 });
@@ -265,6 +273,7 @@ authCmd
     const fs = await import('node:fs/promises');
     const pathMod = await import('node:path');
     const outPath = pathMod.resolve(options.out);
+    await fs.mkdir(pathMod.dirname(outPath), { recursive: true });
     await context.storageState({ path: outPath });
     console.log(`\n[qulib] Saved storage state to ${outPath}`);
     console.log('[qulib] To use it, pass to qulib like:');
@@ -273,6 +282,50 @@ authCmd
     await browser.close();
     process.exit(0);
 });
+authCmd
+    .command('login')
+    .description('Detect form-login on the URL, fill credentials, and save the storage state automatically (uses selectors from detect-auth)')
+    .requiredOption('--base-url <url>', 'The base URL of the app to log into')
+    .option('--auth-path <id>', 'Specific authOption id to use (e.g. "scholastic-sync") when multiple form-login paths exist')
+    .option('--credentials <json>', 'JSON object mapping field name → value, e.g. \'{"username":"a","password":"b","hidden.datasource":"NYC"}\'')
+    .option('--credentials-file <path>', 'Path to a JSON file with the credentials object (keeps secrets out of shell history)')
+    .option('--out <path>', 'Output file path for the storage state JSON', './qulib-storage-state.json')
+    .option('--success-url-contains <substring>', 'Substring that must appear in the URL after login (stronger success detection). If omitted, success is inferred from navigation or hidden password fields.')
+    .option('--timeout <ms>', 'Max time in ms to wait for navigation / success heuristics', '30000')
+    .option('--headed', 'Run Chromium headed for debugging', false)
+    .action(async (options) => {
+    assertExactlyOneCredentialSource(options.credentials, options.credentialsFile);
+    const fs = await import('node:fs/promises');
+    let credentials;
+    if (options.credentialsFile && options.credentialsFile.trim()) {
+        const p = resolve(options.credentialsFile.trim());
+        const raw = await fs.readFile(p, 'utf8');
+        credentials = parseCredentialsJsonString(raw);
+    }
+    else {
+        credentials = parseCredentialsJsonString(options.credentials.trim());
+    }
+    const timeoutMs = parseInt(options.timeout, 10);
+    const detection = await detectAuth(options.baseUrl, timeoutMs);
+    const { path } = resolveAuthLoginConfig({
+        baseUrl: options.baseUrl,
+        authOptions: detection.authOptions,
+        credentials,
+        authPathId: options.authPath,
+    });
+    const loginUrl = detection.loginUrl ?? options.baseUrl;
+    await runAutomatedAuthLogin({
+        loginUrl,
+        path,
+        credentials,
+        outPath: options.out,
+        headed: Boolean(options.headed),
+        timeoutMs,
+        successUrlContains: options.successUrlContains,
+        baseUrlHint: options.baseUrl,
+    });
+    process.exit(0);
+});
 program.parseAsync().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
     console.error('[qulib] Failed:', message);

package/dist/harness/state-manager.d.ts

@@ -1,5 +1,15 @@
 import type { ZodSchema } from 'zod';
 export declare function resolveScanStateBaseDir(outputDir?: string): string;
+/**
+ * Where qulib writes `report.json` and `report.md` for non-ephemeral runs.
+ *
+ * When `outputDir` is set in HarnessConfig, both scan state and reports share that
+ * directory (state files and report files have non-overlapping names). When unset,
+ * reports default to `<cwd>/output` (the legacy default) while state defaults to
+ * `<cwd>/.scan-state` — separate so a casual `git add output/` doesn't accidentally
+ * commit scan state.
+ */
+export declare function resolveReportDir(outputDir?: string): string;
 export declare class StateManager {
     private readonly stateDir;
     constructor(scanStateBaseDir?: string);

package/dist/harness/state-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-manager.d.ts","sourceRoot":"","sources":["../../src/harness/state-manager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAErC,wBAAgB,uBAAuB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAKlE;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,gBAAgB,CAAC,EAAE,MAAM;IAI/B,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA8BhE,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAiBpF"}
+{"version":3,"file":"state-manager.d.ts","sourceRoot":"","sources":["../../src/harness/state-manager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAErC,wBAAgB,uBAAuB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAKlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAK3D;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,gBAAgB,CAAC,EAAE,MAAM;IAI/B,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA8BhE,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAiBpF"}

package/dist/harness/state-manager.js

@@ -8,6 +8,21 @@ export function resolveScanStateBaseDir(outputDir) {
     }
     return isAbsolute(outputDir) ? resolve(outputDir) : resolve(process.cwd(), outputDir);
 }
+/**
+ * Where qulib writes `report.json` and `report.md` for non-ephemeral runs.
+ *
+ * When `outputDir` is set in HarnessConfig, both scan state and reports share that
+ * directory (state files and report files have non-overlapping names). When unset,
+ * reports default to `<cwd>/output` (the legacy default) while state defaults to
+ * `<cwd>/.scan-state` — separate so a casual `git add output/` doesn't accidentally
+ * commit scan state.
+ */
+export function resolveReportDir(outputDir) {
+    if (outputDir === undefined || outputDir === '') {
+        return join(process.cwd(), 'output');
+    }
+    return isAbsolute(outputDir) ? resolve(outputDir) : resolve(process.cwd(), outputDir);
+}
 export class StateManager {
     stateDir;
     constructor(scanStateBaseDir) {