@qulib/core 0.2.0 → 0.2.2

package/dist/schemas/gap-analysis.schema.d.ts

@@ -23,13 +23,13 @@ export declare const FrameworkRecommendationSchema: z.ZodObject<{
     reason: z.ZodString;
     confidence: z.ZodEnum<["high", "medium", "low"]>;
 }, "strip", z.ZodTypeAny, {
+    confidence: "high" | "medium" | "low";
     reason: string;
     adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
-    confidence: "high" | "medium" | "low";
 }, {
+    confidence: "high" | "medium" | "low";
     reason: string;
     adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
-    confidence: "high" | "medium" | "low";
 }>;
 export declare const TestStepSchema: z.ZodObject<{
     action: z.ZodEnum<["navigate", "click", "type", "assert-visible", "assert-hidden", "assert-text", "assert-disabled", "assert-count", "wait", "api-call"]>;
@@ -75,13 +75,13 @@ export declare const NeutralScenarioSchema: z.ZodObject<{
         reason: z.ZodString;
         confidence: z.ZodEnum<["high", "medium", "low"]>;
     }, "strip", z.ZodTypeAny, {
+        confidence: "high" | "medium" | "low";
         reason: string;
         adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
-        confidence: "high" | "medium" | "low";
     }, {
+        confidence: "high" | "medium" | "low";
         reason: string;
         adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
-        confidence: "high" | "medium" | "low";
     }>, "many">;
     sourceGapIds: z.ZodArray<z.ZodString, "many">;
 }, "strip", z.ZodTypeAny, {
@@ -97,9 +97,9 @@ export declare const NeutralScenarioSchema: z.ZodObject<{
     }[];
     tags: string[];
     recommendations: {
+        confidence: "high" | "medium" | "low";
         reason: string;
         adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
-        confidence: "high" | "medium" | "low";
     }[];
     sourceGapIds: string[];
     targetComponent?: string | undefined;
@@ -116,9 +116,9 @@ export declare const NeutralScenarioSchema: z.ZodObject<{
     }[];
     tags: string[];
     recommendations: {
+        confidence: "high" | "medium" | "low";
         reason: string;
         adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
-        confidence: "high" | "medium" | "low";
     }[];
     sourceGapIds: string[];
     targetComponent?: string | undefined;
@@ -132,17 +132,17 @@ export declare const GeneratedTestSchema: z.ZodObject<{
     outputPath: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     code: string;
+    source: "llm" | "template";
     adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
     scenarioId: string;
     filename: string;
-    source: "llm" | "template";
     outputPath: string;
 }, {
     code: string;
+    source: "llm" | "template";
     adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
     scenarioId: string;
     filename: string;
-    source: "llm" | "template";
     outputPath: string;
 }>;
 export declare const GapAnalysisSchema: z.ZodObject<{
@@ -199,13 +199,13 @@ export declare const GapAnalysisSchema: z.ZodObject<{
             reason: z.ZodString;
             confidence: z.ZodEnum<["high", "medium", "low"]>;
         }, "strip", z.ZodTypeAny, {
+            confidence: "high" | "medium" | "low";
             reason: string;
             adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
-            confidence: "high" | "medium" | "low";
         }, {
+            confidence: "high" | "medium" | "low";
             reason: string;
             adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
-            confidence: "high" | "medium" | "low";
         }>, "many">;
         sourceGapIds: z.ZodArray<z.ZodString, "many">;
     }, "strip", z.ZodTypeAny, {
@@ -221,9 +221,9 @@ export declare const GapAnalysisSchema: z.ZodObject<{
         }[];
         tags: string[];
         recommendations: {
+            confidence: "high" | "medium" | "low";
             reason: string;
             adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
-            confidence: "high" | "medium" | "low";
         }[];
         sourceGapIds: string[];
         targetComponent?: string | undefined;
@@ -240,9 +240,9 @@ export declare const GapAnalysisSchema: z.ZodObject<{
         }[];
         tags: string[];
         recommendations: {
+            confidence: "high" | "medium" | "low";
             reason: string;
             adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
-            confidence: "high" | "medium" | "low";
         }[];
         sourceGapIds: string[];
         targetComponent?: string | undefined;
@@ -256,17 +256,17 @@ export declare const GapAnalysisSchema: z.ZodObject<{
         outputPath: z.ZodString;
     }, "strip", z.ZodTypeAny, {
         code: string;
+        source: "llm" | "template";
         adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
         scenarioId: string;
         filename: string;
-        source: "llm" | "template";
         outputPath: string;
     }, {
         code: string;
+        source: "llm" | "template";
         adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
         scenarioId: string;
         filename: string;
-        source: "llm" | "template";
         outputPath: string;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
@@ -295,19 +295,19 @@ export declare const GapAnalysisSchema: z.ZodObject<{
         }[];
         tags: string[];
         recommendations: {
+            confidence: "high" | "medium" | "low";
             reason: string;
             adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
-            confidence: "high" | "medium" | "low";
         }[];
         sourceGapIds: string[];
         targetComponent?: string | undefined;
     }[];
     generatedTests: {
         code: string;
+        source: "llm" | "template";
         adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
         scenarioId: string;
         filename: string;
-        source: "llm" | "template";
         outputPath: string;
     }[];
     coverageWarning?: "auth-required" | "budget-exceeded" | "low-coverage" | "navigation-failures" | undefined;
@@ -337,19 +337,19 @@ export declare const GapAnalysisSchema: z.ZodObject<{
         }[];
         tags: string[];
         recommendations: {
+            confidence: "high" | "medium" | "low";
             reason: string;
             adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
-            confidence: "high" | "medium" | "low";
         }[];
         sourceGapIds: string[];
         targetComponent?: string | undefined;
     }[];
     generatedTests: {
         code: string;
+        source: "llm" | "template";
         adapter: "playwright" | "cypress-e2e" | "cypress-component" | "api" | "accessibility";
         scenarioId: string;
         filename: string;
-        source: "llm" | "template";
         outputPath: string;
     }[];
     coverageWarning?: "auth-required" | "budget-exceeded" | "low-coverage" | "navigation-failures" | undefined;

package/dist/schemas/index.d.ts

@@ -1,4 +1,4 @@
-export { HarnessConfigSchema, AuthConfigSchema, DetectedAuthSchema, type ExplorerType, type AdapterType, type FormLoginAuthConfig, type StorageStateAuthConfig, type AuthConfig, type HarnessConfig, type DetectedAuth, } from './config.schema.js';
+export { HarnessConfigSchema, AuthConfigSchema, DetectedAuthSchema, AuthPathRequirementsSchema, AuthPathSchema, AuthExplorationSchema, type ExplorerType, type AdapterType, type FormLoginAuthConfig, type StorageStateAuthConfig, type AuthConfig, type HarnessConfig, type DetectedAuth, type AuthPathRequirements, type AuthPath, type AuthExploration, } from './config.schema.js';
 export { DecisionLogEntrySchema, type DecisionLogEntry, } from './decision-log.schema.js';
 export { RouteInventorySchema, RouteSchema, A11yViolationSchema, BrokenLinkSchema, type RouteInventory, type Route, } from './route-inventory.schema.js';
 export { GapAnalysisSchema, GapSchema, NeutralScenarioSchema, GeneratedTestSchema, TestStepSchema, FrameworkRecommendationSchema, type GapAnalysis, type Gap, type NeutralScenario, type GeneratedTest, type TestStep, type FrameworkRecommendation, } from './gap-analysis.schema.js';

package/dist/schemas/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,KAAK,GACX,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,iBAAiB,EACjB,SAAS,EACT,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,6BAA6B,EAC7B,KAAK,WAAW,EAChB,KAAK,GAAG,EACR,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,uBAAuB,GAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,GAClB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,0BAA0B,EAC1B,cAAc,EACd,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EACb,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,KAAK,GACX,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,iBAAiB,EACjB,SAAS,EACT,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,6BAA6B,EAC7B,KAAK,WAAW,EAChB,KAAK,GAAG,EACR,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,uBAAuB,GAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,GAClB,MAAM,2BAA2B,CAAC"}

package/dist/schemas/index.js

@@ -1,4 +1,4 @@
-export { HarnessConfigSchema, AuthConfigSchema, DetectedAuthSchema, } from './config.schema.js';
+export { HarnessConfigSchema, AuthConfigSchema, DetectedAuthSchema, AuthPathRequirementsSchema, AuthPathSchema, AuthExplorationSchema, } from './config.schema.js';
 export { DecisionLogEntrySchema, } from './decision-log.schema.js';
 export { RouteInventorySchema, RouteSchema, A11yViolationSchema, BrokenLinkSchema, } from './route-inventory.schema.js';
 export { GapAnalysisSchema, GapSchema, NeutralScenarioSchema, GeneratedTestSchema, TestStepSchema, FrameworkRecommendationSchema, } from './gap-analysis.schema.js';

package/dist/schemas/repo-analysis.schema.d.ts

@@ -5,12 +5,12 @@ export declare const RepoRouteSchema: z.ZodObject<{
     method: z.ZodEnum<["GET", "POST", "PUT", "DELETE", "PATCH", "unknown"]>;
 }, "strip", z.ZodTypeAny, {
     path: string;
-    file: string;
     method: "unknown" | "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    file: string;
 }, {
     path: string;
-    file: string;
     method: "unknown" | "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+    file: string;
 }>;
 export declare const TestFileSchema: z.ZodObject<{
     file: z.ZodString;
@@ -62,12 +62,12 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
         method: z.ZodEnum<["GET", "POST", "PUT", "DELETE", "PATCH", "unknown"]>;
     }, "strip", z.ZodTypeAny, {
         path: string;
-        file: string;
         method: "unknown" | "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+        file: string;
     }, {
         path: string;
-        file: string;
         method: "unknown" | "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+        file: string;
     }>, "many">;
     testFiles: z.ZodArray<z.ZodObject<{
         file: z.ZodString;
@@ -115,8 +115,8 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
     scannedAt: string;
     routes: {
         path: string;
-        file: string;
         method: "unknown" | "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+        file: string;
     }[];
     repoPath: string;
     testFiles: {
@@ -139,8 +139,8 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
     scannedAt: string;
     routes: {
         path: string;
-        file: string;
         method: "unknown" | "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+        file: string;
     }[];
     repoPath: string;
     testFiles: {

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,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAmDhE,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CAgGtF"}
+{"version":3,"file":"auth-detector.d.ts","sourceRoot":"","sources":["../../src/tools/auth-detector.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AA4DhE,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CAkGtF"}

package/dist/tools/auth-detector.js

@@ -1,4 +1,12 @@
-import { chromium } from '@playwright/test';
+import { launchBrowser } from './browser.js';
+async function waitNetworkIdleBestEffort(page) {
+    try {
+        await page.waitForLoadState('networkidle', { timeout: 5000 });
+    }
+    catch {
+        // best-effort — analytics or polling can prevent networkidle
+    }
+}
 const OAUTH_PROVIDERS = [
     { provider: 'github', patterns: [/github/i, /sign in with github/i] },
     {
@@ -43,11 +51,12 @@ async function firstTextInputNameForLogin(page) {
     return null;
 }
 export async function detectAuth(url, timeoutMs = 15000) {
-    const browser = await chromium.launch({ headless: true });
+    const browser = await launchBrowser();
     try {
         const context = await browser.newContext();
         const page = await context.newPage();
         await page.goto(url, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+        await waitNetworkIdleBestEffort(page);
         let loginUrl = url;
         const looksLikeLoginPage = /login|sign[- ]?in|auth/i.test(page.url()) ||
             (await page.locator('input[type="password"]').count()) > 0;
@@ -58,6 +67,7 @@ export async function detectAuth(url, timeoutMs = 15000) {
                 if (href) {
                     loginUrl = new URL(href, url).toString();
                     await page.goto(loginUrl, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+                    await waitNetworkIdleBestEffort(page);
                 }
             }
         }

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

@@ -0,0 +1,3 @@
+import { type AuthExploration } from '../schemas/config.schema.js';
+export declare function exploreAuth(url: string, timeoutMs?: number): Promise<AuthExploration>;
+//# sourceMappingURL=auth-explorer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth-explorer.d.ts","sourceRoot":"","sources":["../../src/tools/auth-explorer.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,6BAA6B,CAAC;AA6MrC,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,eAAe,CAAC,CA2J1F"}

package/dist/tools/auth-explorer.js

@@ -0,0 +1,324 @@
+import { AuthExplorationSchema, } from '../schemas/config.schema.js';
+import { launchBrowser } from './browser.js';
+import { BUILT_IN_OAUTH_PROVIDERS } from './oauth-providers.js';
+import { loadUserProviders } from './user-providers.js';
+const MAGIC_LINK_PATTERNS = [
+    /email me a (sign[- ]?in )?link/i,
+    /sign in with email/i,
+    /passwordless/i,
+    /we'll send you a link/i,
+];
+async function waitNetworkIdleBestEffort(page) {
+    try {
+        await page.waitForLoadState('networkidle', { timeout: 5000 });
+    }
+    catch {
+        // best-effort
+    }
+}
+function textLooksLikeOAuthIdpButton(text) {
+    const t = text.trim();
+    if (t.length === 0 || t.length > 120) {
+        return false;
+    }
+    return (/\b(sign in with|log in with|continue with|sign up with)\b/i.test(t) ||
+        /^(github|google|microsoft|apple)$/i.test(t));
+}
+function slugifyLabel(text) {
+    const s = text
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, '-')
+        .replace(/[^a-z0-9-]/g, '')
+        .slice(0, 48);
+    return s.length > 0 ? s : 'unknown';
+}
+function onLoginishPage(url) {
+    return /login|sign[- ]?in|auth|sso|oauth/i.test(new URL(url).pathname + new URL(url).hostname);
+}
+function isHeuristicUnknownSso(text, loginish) {
+    const t = text.trim();
+    if (!loginish || t.length < 3 || t.length > 80) {
+        return false;
+    }
+    if (/^(submit|cancel|back|close|next|skip|help|faq)$/i.test(t)) {
+        return false;
+    }
+    if (/\b(sign in with|log in with|continue with)\b/i.test(t)) {
+        return true;
+    }
+    if (/\b(sync|sso|portal|workspace|federation)\b/i.test(t)) {
+        return true;
+    }
+    return false;
+}
+function storageRequirement() {
+    return {
+        method: 'storage-state',
+        instruction: 'OAuth and most SSO flows cannot be scripted. Run `qulib auth init --base-url <app-url>` on this machine, then pass the saved storage state JSON to `analyze` or MCP `analyze_app` as `auth: { type: "storage-state", path: "..." }`.',
+    };
+}
+async function collectVisibleControlTexts(page) {
+    return page.evaluate(() => {
+        const seen = new Set();
+        const out = [];
+        const nodes = document.querySelectorAll('button, a[href], [role="button"]');
+        for (const el of nodes) {
+            const t = (el.textContent ?? '').trim().replace(/\s+/g, ' ');
+            if (!t || t.length > 120) {
+                continue;
+            }
+            const style = window.getComputedStyle(el);
+            if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') {
+                continue;
+            }
+            if (!seen.has(t)) {
+                seen.add(t);
+                out.push(t);
+            }
+        }
+        return out;
+    });
+}
+function buildAllProviders() {
+    const builtIn = BUILT_IN_OAUTH_PROVIDERS.map((p) => ({ ...p, source: 'built-in' }));
+    const user = loadUserProviders().map((p) => ({ ...p, source: 'user-local' }));
+    return [...builtIn, ...user];
+}
+function matchProvider(text, p) {
+    return p.patterns.some((re) => re.test(text));
+}
+function oauthConfidence(source, loginish) {
+    if (source === 'user-local') {
+        return 'high';
+    }
+    if (source === 'built-in' && loginish) {
+        return 'high';
+    }
+    if (source === 'built-in') {
+        return 'medium';
+    }
+    return 'low';
+}
+async function buildFormPaths(page) {
+    const passwordCount = await page.locator('input[type="password"]').count();
+    if (passwordCount === 0) {
+        return [];
+    }
+    const formType = passwordCount > 1 ? 'form-multi' : 'form-login';
+    const fields = await page.evaluate(() => {
+        const pwd = document.querySelector('input[type="password"]');
+        if (!pwd) {
+            return [];
+        }
+        const form = pwd.closest('form') ?? document.body;
+        const out = [];
+        const inputs = form.querySelectorAll('input, select, textarea');
+        for (const el of inputs) {
+            if (!(el instanceof HTMLElement)) {
+                continue;
+            }
+            const tag = el.tagName.toLowerCase();
+            if (tag === 'input') {
+                const inp = el;
+                const t = (inp.type || 'text').toLowerCase();
+                if (['hidden', 'submit', 'button', 'image', 'reset'].includes(t)) {
+                    continue;
+                }
+                let fieldType = 'text';
+                if (t === 'password') {
+                    fieldType = 'password';
+                }
+                else if (t === 'email') {
+                    fieldType = 'email';
+                }
+                else if (t === 'checkbox') {
+                    fieldType = 'checkbox';
+                }
+                const id = inp.id;
+                let label = inp.getAttribute('aria-label') ?? inp.placeholder ?? inp.name ?? fieldType;
+                if (id) {
+                    const lab = document.querySelector(`label[for="${CSS.escape(id)}"]`);
+                    if (lab?.textContent) {
+                        label = lab.textContent.trim();
+                    }
+                }
+                out.push({
+                    name: inp.name || inp.id || fieldType,
+                    label: label.slice(0, 120),
+                    type: fieldType,
+                    observedOptions: [],
+                });
+            }
+            else if (tag === 'select') {
+                const sel = el;
+                const opts = Array.from(sel.options).map((o) => o.text.trim()).filter(Boolean);
+                out.push({
+                    name: sel.name || sel.id || 'select',
+                    label: (sel.getAttribute('aria-label') ?? sel.name ?? 'select').slice(0, 120),
+                    type: 'select',
+                    observedOptions: opts.slice(0, 50),
+                });
+            }
+        }
+        return out;
+    });
+    const requirements = fields.length > 0
+        ? { method: 'credentials', fields }
+        : {
+            method: 'unknown',
+            instruction: 'A password field exists but field metadata could not be read. Inspect the page in devtools and configure form-login selectors manually, or use `qulib auth init`.',
+        };
+    return [
+        {
+            id: formType === 'form-multi' ? 'form-multi' : 'form-login',
+            label: formType === 'form-multi' ? 'Multi-field sign-in form' : 'Username / password form',
+            type: formType,
+            provider: null,
+            source: 'heuristic',
+            automatable: requirements.method === 'credentials',
+            confidence: requirements.method === 'credentials' ? 'medium' : 'low',
+            requirements,
+        },
+    ];
+}
+export async function exploreAuth(url, timeoutMs = 20000) {
+    const browser = await launchBrowser();
+    try {
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        await page.goto(url, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+        await waitNetworkIdleBestEffort(page);
+        const loginishAfterFirst = /login|sign[- ]?in|auth/i.test(page.url()) || (await page.locator('input[type="password"]').count()) > 0;
+        if (!loginishAfterFirst) {
+            const loginLink = page.locator('a').filter({ hasText: /^(log ?in|sign ?in|sign in)$/i }).first();
+            if ((await loginLink.count()) > 0) {
+                const href = await loginLink.getAttribute('href');
+                if (href) {
+                    const next = new URL(href, url).toString();
+                    await page.goto(next, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+                    await waitNetworkIdleBestEffort(page);
+                }
+            }
+        }
+        const finalUrl = page.url();
+        const loginish = onLoginishPage(finalUrl) || (await page.locator('input[type="password"]').count()) > 0;
+        const allProviders = buildAllProviders();
+        const texts = await collectVisibleControlTexts(page);
+        const consumed = new Set();
+        const authPaths = [];
+        const unrecognizedButtons = [];
+        for (const rawText of texts) {
+            const text = rawText.trim();
+            if (!text) {
+                continue;
+            }
+            let matched = null;
+            for (const p of allProviders) {
+                if (!matchProvider(text, p)) {
+                    continue;
+                }
+                if (p.source === 'built-in' && !(textLooksLikeOAuthIdpButton(text) || loginish)) {
+                    continue;
+                }
+                matched = { p, gate: textLooksLikeOAuthIdpButton(text) || loginish };
+                break;
+            }
+            if (matched) {
+                const { p, gate } = matched;
+                const id = `oauth:${p.id}`;
+                if (consumed.has(id)) {
+                    continue;
+                }
+                consumed.add(id);
+                authPaths.push({
+                    id,
+                    label: p.label,
+                    type: 'oauth',
+                    provider: p.id,
+                    source: p.source,
+                    automatable: false,
+                    confidence: oauthConfidence(p.source, loginish || gate),
+                    requirements: storageRequirement(),
+                });
+                continue;
+            }
+            if (isHeuristicUnknownSso(text, loginish)) {
+                const slug = slugifyLabel(text);
+                const id = `oauth-unknown:${slug}`;
+                if (consumed.has(id)) {
+                    continue;
+                }
+                consumed.add(id);
+                authPaths.push({
+                    id,
+                    label: text.slice(0, 100),
+                    type: 'oauth-unknown',
+                    provider: null,
+                    source: 'heuristic',
+                    automatable: false,
+                    confidence: 'low',
+                    requirements: storageRequirement(),
+                });
+                const safePattern = text.slice(0, 48).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+                unrecognizedButtons.push({
+                    label: text.slice(0, 100),
+                    hint: `If this is your org SSO, register it: qulib auth providers add --id "${slug}" --label "${text.replace(/"/g, '\\"').slice(0, 80)}" --pattern "${safePattern}"`,
+                });
+            }
+        }
+        const pageText = await page.locator('body').innerText().catch(() => '');
+        if (MAGIC_LINK_PATTERNS.some((re) => re.test(pageText))) {
+            authPaths.push({
+                id: 'magic-link',
+                label: 'Magic link / passwordless',
+                type: 'magic-link',
+                provider: null,
+                source: 'heuristic',
+                automatable: false,
+                confidence: 'medium',
+                requirements: {
+                    method: 'storage-state',
+                    instruction: 'Magic-link flows need a human in the loop. Use `qulib auth init --base-url <app-url>` and complete email or provider steps in the opened browser, then reuse the saved storage state for scans.',
+                },
+            });
+        }
+        authPaths.push(...(await buildFormPaths(page)));
+        const authRequired = authPaths.length > 0;
+        let authScope = 'none';
+        if (authRequired) {
+            if (loginish) {
+                authScope = 'site-wide';
+            }
+            else {
+                authScope = /login|signin|auth/i.test(new URL(finalUrl).pathname) ? 'site-wide' : 'optional';
+            }
+        }
+        const suggestedParts = [];
+        if (authPaths.some((p) => p.type === 'oauth' || p.type === 'oauth-unknown')) {
+            suggestedParts.push('For OAuth or unrecognized SSO buttons, collect a Playwright storage state with `qulib auth init` before calling `analyze_app`.');
+        }
+        if (authPaths.some((p) => p.type === 'form-login' || p.type === 'form-multi')) {
+            suggestedParts.push('For password forms, gather username/password and stable selectors (or use storage state if MFA applies).');
+        }
+        if (authPaths.some((p) => p.type === 'magic-link')) {
+            suggestedParts.push('For magic-link, use `qulib auth init` after the user completes email delivery.');
+        }
+        if (!authRequired) {
+            suggestedParts.push('No sign-in surface detected at this URL; you can run `analyze_app` without auth unless gated deeper in the app.');
+        }
+        const exploration = {
+            url: finalUrl,
+            authRequired,
+            authScope,
+            authPaths,
+            observedAt: new Date().toISOString(),
+            suggestedAgentBehavior: suggestedParts.join(' '),
+            unrecognizedButtons,
+        };
+        return AuthExplorationSchema.parse(exploration);
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/tools/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/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/tools/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/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/oauth-providers.d.ts

@@ -0,0 +1,7 @@
+export interface OAuthProvider {
+    id: string;
+    label: string;
+    patterns: RegExp[];
+}
+export declare const BUILT_IN_OAUTH_PROVIDERS: OAuthProvider[];
+//# sourceMappingURL=oauth-providers.d.ts.map

package/dist/tools/oauth-providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-providers.d.ts","sourceRoot":"","sources":["../../src/tools/oauth-providers.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,wBAAwB,EAAE,aAAa,EAsBnD,CAAC"}