@qulib/core 0.1.1 → 0.2.0

package/README.md

@@ -8,6 +8,55 @@
 npm install @qulib/core
 ```
 
+## Scanning authenticated apps
+
+Qulib supports three auth modes: anonymous (default), form-login, and storage-state.
+
+### Form login
+
+If your app uses a simple username/password form:
+
+```bash
+qulib analyze --url https://app.example.com \
+  --auth-form-login \
+  --login-url https://app.example.com/login \
+  --username you@example.com \
+  --password "..." \
+  --username-selector "input[name=email]" \
+  --password-selector "input[name=password]" \
+  --submit-selector "button[type=submit]"
+```
+
+### OAuth, magic link, SSO, or anything else
+
+These can't be automated. Qulib has a helper for this:
+
+```bash
+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`.
+
+Then scan with it:
+
+```bash
+qulib analyze --url https://app.example.com --auth-storage-state ./qulib-storage-state.json
+```
+
+The storage state is just a JSON file of cookies and localStorage — keep it private, treat it like a credential.
+
+### Auth detection
+
+To check what auth pattern a site uses before configuring anything:
+
+```bash
+qulib detect-auth --url https://app.example.com
+```
+
+Or via MCP:
+
+> "Use qulib's detect_auth tool on https://app.example.com — what's the recommended auth setup?"
+
 ## CLI (from npm)
 
 ```bash

package/dist/analyze.d.ts

@@ -1,5 +1,5 @@
-import type { HarnessConfig } from './schemas/config.schema.js';
-import type { GapAnalysis } from './schemas/gap-analysis.schema.js';
+import type { HarnessConfig, DetectedAuth } from './schemas/config.schema.js';
+import { type GapAnalysis } from './schemas/gap-analysis.schema.js';
 import type { RouteInventory } from './schemas/route-inventory.schema.js';
 import type { RepoAnalysis } from './schemas/repo-analysis.schema.js';
 import type { DecisionLogEntry } from './schemas/decision-log.schema.js';
@@ -8,6 +8,7 @@ export interface AnalyzeOptions {
     repoPath?: string;
     config: HarnessConfig;
     writeArtifacts?: boolean;
+    skipAuthDetection?: boolean;
 }
 export interface AnalyzeResult {
     releaseConfidence: number;
@@ -15,6 +16,7 @@ export interface AnalyzeResult {
     routeInventory: RouteInventory;
     repoInventory: RepoAnalysis | null;
     decisionLog: DecisionLogEntry[];
+    detectedAuth?: DetectedAuth;
 }
 export declare function analyzeApp(options: AnalyzeOptions): Promise<AnalyzeResult>;
 //# sourceMappingURL=analyze.d.ts.map

package/dist/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAKzE,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;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,WAAW,CAAC;IACzB,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE,gBAAgB,EAAE,CAAC;CACjC;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAmBhF"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAMzE,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;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,WAAW,CAAC;IACzB,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA0DhF"}

package/dist/analyze.js

@@ -1,6 +1,8 @@
+import { GapAnalysisSchema } from './schemas/gap-analysis.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';
 export async function analyzeApp(options) {
     const writeArtifacts = options.writeArtifacts ?? false;
     const decisionLog = [];
@@ -8,6 +10,44 @@ export async function analyzeApp(options) {
         writeArtifacts,
         decisionMemory: decisionLog,
     };
+    if (!options.config.auth && !options.skipAuthDetection) {
+        const detection = await detectAuth(options.url, options.config.timeoutMs);
+        if (detection.hasAuth) {
+            const gapAnalysis = GapAnalysisSchema.parse({
+                analyzedAt: new Date().toISOString(),
+                mode: 'auth-required',
+                releaseConfidence: 0,
+                coveragePagesScanned: 0,
+                coverageBudgetExceeded: false,
+                coverageWarning: 'auth-required',
+                gaps: [],
+                scenarios: [],
+                generatedTests: [],
+            });
+            return {
+                releaseConfidence: 0,
+                gapAnalysis,
+                routeInventory: {
+                    scannedAt: new Date().toISOString(),
+                    baseUrl: options.url,
+                    routes: [],
+                    pagesSkipped: 0,
+                    budgetExceeded: false,
+                },
+                repoInventory: null,
+                decisionLog: [
+                    {
+                        timestamp: new Date().toISOString(),
+                        phase: 'observe',
+                        decision: 'auth-required',
+                        reason: detection.recommendation,
+                        metadata: { detection },
+                    },
+                ],
+                detectedAuth: detection,
+            };
+        }
+    }
     const observed = await observe(options.url, options.repoPath, options.config, artifacts);
     const analysis = await think(observed, options.config, artifacts);
     await act(analysis, options.config, artifacts);

package/dist/cli/index.js

@@ -5,8 +5,17 @@ import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import { HarnessConfigSchema } from '../schemas/config.schema.js';
 import { analyzeApp } from '../analyze.js';
+import { detectAuth } from '../tools/auth-detector.js';
 const program = new Command();
 const AnalyzeUrlSchema = z.string().url();
+const FormLoginCliSchema = z.object({
+    loginUrl: z.string().url(),
+    username: z.string().min(1),
+    password: z.string(),
+    usernameSelector: z.string().min(1),
+    passwordSelector: z.string().min(1),
+    submitSelector: z.string().min(1),
+});
 async function loadConfigFile(relativePath) {
     const configPath = resolve(process.cwd(), relativePath);
     const configModule = await import(pathToFileURL(configPath).href);
@@ -25,10 +34,47 @@ function redactConfigForLog(config) {
     }
     return base;
 }
+function mergeAuthFromCli(config, options) {
+    if (options.authStorageState && options.authFormLogin) {
+        throw new Error('Use either --auth-storage-state or --auth-form-login, not both.');
+    }
+    if (options.authStorageState) {
+        return {
+            ...config,
+            auth: { type: 'storage-state', path: options.authStorageState },
+        };
+    }
+    if (options.authFormLogin) {
+        const parsed = FormLoginCliSchema.parse({
+            loginUrl: options.loginUrl,
+            username: options.username,
+            password: options.password,
+            usernameSelector: options.usernameSelector,
+            passwordSelector: options.passwordSelector,
+            submitSelector: options.submitSelector,
+        });
+        return {
+            ...config,
+            auth: {
+                type: 'form-login',
+                loginUrl: parsed.loginUrl,
+                credentials: { username: parsed.username, password: parsed.password },
+                selectors: {
+                    username: parsed.usernameSelector,
+                    password: parsed.passwordSelector,
+                    submit: parsed.submitSelector,
+                },
+                successIndicator: {},
+            },
+        };
+    }
+    return config;
+}
 async function runAnalyze(options) {
     const validatedUrl = AnalyzeUrlSchema.parse(options.url);
     const mode = options.repo ? 'url-repo' : 'url-only';
-    const config = await loadConfigFile(options.configFile ?? 'qulib.config.ts');
+    const baseConfig = await loadConfigFile(options.configFile ?? 'qulib.config.ts');
+    const config = mergeAuthFromCli(baseConfig, options);
     const ephemeral = options.ephemeral ?? false;
     const writeArtifacts = !ephemeral;
     if (ephemeral) {
@@ -50,6 +96,7 @@ async function runAnalyze(options) {
             discoveredRoutes: result.routeInventory,
             repoInventory: result.repoInventory,
             decisionLog: result.decisionLog,
+            ...(result.detectedAuth !== undefined && { detectedAuth: result.detectedAuth }),
         }, null, 2));
     }
 }
@@ -87,16 +134,86 @@ 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('--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)')
+    .option('--username <user>', 'Form login username')
+    .option('--password <secret>', 'Form login password')
+    .option('--username-selector <sel>', 'Selector for username field')
+    .option('--password-selector <sel>', 'Selector for password field')
+    .option('--submit-selector <sel>', 'Selector for submit control')
     .action(async (options) => {
+    const authFormLogin = Boolean(options.authFormLogin);
+    const loginUrl = options.loginUrl;
+    if (!authFormLogin && loginUrl !== undefined) {
+        throw new Error('--login-url is only valid with --auth-form-login');
+    }
+    if (authFormLogin && loginUrl === undefined) {
+        throw new Error('--auth-form-login requires --login-url');
+    }
     await runAnalyze({
         url: options.url,
         repo: options.repo,
         configFile: options.config,
         ephemeral: options.ephemeral,
+        authStorageState: options.authStorageState,
+        authFormLogin,
+        loginUrl,
+        username: options.username,
+        password: options.password,
+        usernameSelector: options.usernameSelector,
+        passwordSelector: options.passwordSelector,
+        submitSelector: options.submitSelector,
+    });
+});
+program
+    .command('detect-auth')
+    .description('Detect the authentication pattern used by a deployed web app')
+    .requiredOption('--url <url>', 'URL of the app or login page')
+    .option('--timeout <ms>', 'Page load timeout in ms', '15000')
+    .action(async (options) => {
+    const result = await detectAuth(options.url, parseInt(options.timeout, 10));
+    console.log(JSON.stringify(result, null, 2));
+});
+const authCmd = program.command('auth').description('Authentication helpers for scans');
+authCmd
+    .command('init')
+    .description('Open a browser, let the user log in manually, save the storage state to a file for reuse')
+    .requiredOption('--base-url <url>', 'The base URL of the app to log into')
+    .option('--out <path>', 'Output file path for the storage state JSON', './qulib-storage-state.json')
+    .option('--timeout <ms>', 'Maximum time to wait for the user to finish logging in (default 5 min)', '300000')
+    .action(async (options) => {
+    const { chromium } = await import('@playwright/test');
+    const browser = await chromium.launch({ headless: false });
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    const timeoutMs = parseInt(options.timeout, 10);
+    console.log(`\n[qulib] Opening ${options.baseUrl}`);
+    console.log('[qulib] Log in normally in the browser window that just opened.');
+    console.log('[qulib] After you reach a logged-in state, return to this terminal and press ENTER.');
+    console.log(`[qulib] You have ${timeoutMs / 1000}s before timeout.\n`);
+    await page.goto(options.baseUrl);
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('Timed out waiting for user')), timeoutMs);
+        process.stdin.once('data', () => {
+            clearTimeout(timer);
+            resolve();
+        });
+        process.stdin.resume();
     });
+    const fs = await import('node:fs/promises');
+    const pathMod = await import('node:path');
+    const outPath = pathMod.resolve(options.out);
+    await context.storageState({ path: outPath });
+    console.log(`\n[qulib] Saved storage state to ${outPath}`);
+    console.log('[qulib] To use it, pass to qulib like:');
+    console.log(`        qulib analyze --url ${options.baseUrl} --auth-storage-state ${outPath}`);
+    console.log(`[qulib] Or in MCP, pass auth: { type: 'storage-state', path: '${outPath}' }`);
+    await browser.close();
+    process.exit(0);
 });
 program.parseAsync().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
-    console.error('[qulib] Analyze failed:', message);
+    console.error('[qulib] Failed:', message);
     process.exit(1);
 });

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { analyzeApp } from './analyze.js';
+export { detectAuth } from './tools/auth-detector.js';
 export type { AnalyzeOptions, AnalyzeResult } from './analyze.js';
-export type { HarnessConfig, AuthConfig, RouteInventory, GapAnalysis, RepoAnalysis, } from './schemas/index.js';
+export type { HarnessConfig, AuthConfig, RouteInventory, GapAnalysis, RepoAnalysis, DetectedAuth, } from './schemas/index.js';
 //# sourceMappingURL=index.d.ts.map

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,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EACV,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,YAAY,GACb,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,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EACV,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,YAAY,EACZ,YAAY,GACb,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1 +1,2 @@
 export { analyzeApp } from './analyze.js';
+export { detectAuth } from './tools/auth-detector.js';

package/dist/schemas/config.schema.d.ts

@@ -323,5 +323,66 @@ export declare const HarnessConfigSchema: z.ZodObject<{
     } | undefined;
 }>;
 export type HarnessConfig = z.infer<typeof HarnessConfigSchema>;
+export declare const DetectedAuthSchema: z.ZodObject<{
+    hasAuth: z.ZodBoolean;
+    type: z.ZodEnum<["none", "form-login", "oauth", "magic-link", "unknown"]>;
+    provider: z.ZodNullable<z.ZodString>;
+    loginUrl: z.ZodNullable<z.ZodString>;
+    observedSelectors: z.ZodNullable<z.ZodObject<{
+        usernameSelector: z.ZodNullable<z.ZodString>;
+        passwordSelector: z.ZodNullable<z.ZodString>;
+        submitSelector: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        usernameSelector: string | null;
+        passwordSelector: string | null;
+        submitSelector: string | null;
+    }, {
+        usernameSelector: string | null;
+        passwordSelector: string | null;
+        submitSelector: string | null;
+    }>>;
+    oauthButtons: z.ZodArray<z.ZodObject<{
+        provider: z.ZodString;
+        text: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        text: string;
+    }, {
+        provider: string;
+        text: string;
+    }>, "many">;
+    recommendation: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "unknown" | "form-login" | "none" | "oauth" | "magic-link";
+    loginUrl: string | null;
+    hasAuth: boolean;
+    provider: string | null;
+    observedSelectors: {
+        usernameSelector: string | null;
+        passwordSelector: string | null;
+        submitSelector: string | null;
+    } | null;
+    oauthButtons: {
+        provider: string;
+        text: string;
+    }[];
+    recommendation: string;
+}, {
+    type: "unknown" | "form-login" | "none" | "oauth" | "magic-link";
+    loginUrl: string | null;
+    hasAuth: boolean;
+    provider: string | null;
+    observedSelectors: {
+        usernameSelector: string | null;
+        passwordSelector: string | null;
+        submitSelector: string | null;
+    } | null;
+    oauthButtons: {
+        provider: string;
+        text: string;
+    }[];
+    recommendation: string;
+}>;
+export type DetectedAuth = z.infer<typeof DetectedAuthSchema>;
 export {};
 //# sourceMappingURL=config.schema.d.ts.map

package/dist/schemas/config.schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/config.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,SAAS,CAAC;AACpD,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,aAAa,GAAG,mBAAmB,GAAG,KAAK,GAAG,eAAe,CAAC;AAEvG,QAAA,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBvB,CAAC;AAEH,QAAA,MAAM,sBAAsB;;;;;;;;;EAG1B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAA8E,CAAC;AAE5G,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACtE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC5E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAe9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}
+{"version":3,"file":"config.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/config.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,SAAS,CAAC;AACpD,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,aAAa,GAAG,mBAAmB,GAAG,KAAK,GAAG,eAAe,CAAC;AAEvG,QAAA,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBvB,CAAC;AAEH,QAAA,MAAM,sBAAsB;;;;;;;;;EAG1B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAA8E,CAAC;AAE5G,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACtE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC5E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAe9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmB7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/schemas/config.schema.js

@@ -37,3 +37,21 @@ export const HarnessConfigSchema = z.object({
     adapters: z.array(z.enum(['playwright', 'cypress-e2e', 'cypress-component', 'api', 'accessibility'])).default(['playwright']),
     auth: AuthConfigSchema.optional(),
 });
+export const DetectedAuthSchema = z.object({
+    hasAuth: z.boolean(),
+    type: z.enum(['none', 'form-login', 'oauth', 'magic-link', 'unknown']),
+    provider: z.string().nullable(),
+    loginUrl: z.string().nullable(),
+    observedSelectors: z
+        .object({
+        usernameSelector: z.string().nullable(),
+        passwordSelector: z.string().nullable(),
+        submitSelector: z.string().nullable(),
+    })
+        .nullable(),
+    oauthButtons: z.array(z.object({
+        provider: z.string(),
+        text: z.string(),
+    })),
+    recommendation: z.string(),
+});

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

@@ -147,11 +147,11 @@ export declare const GeneratedTestSchema: z.ZodObject<{
 }>;
 export declare const GapAnalysisSchema: z.ZodObject<{
     analyzedAt: z.ZodString;
-    mode: z.ZodEnum<["url-only", "url-repo"]>;
+    mode: z.ZodEnum<["url-only", "url-repo", "auth-required"]>;
     releaseConfidence: z.ZodNumber;
     coveragePagesScanned: z.ZodNumber;
     coverageBudgetExceeded: z.ZodBoolean;
-    coverageWarning: z.ZodOptional<z.ZodEnum<["budget-exceeded", "low-coverage", "navigation-failures"]>>;
+    coverageWarning: z.ZodOptional<z.ZodEnum<["budget-exceeded", "low-coverage", "navigation-failures", "auth-required"]>>;
     gaps: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         path: z.ZodString;
@@ -271,7 +271,7 @@ export declare const GapAnalysisSchema: z.ZodObject<{
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     analyzedAt: string;
-    mode: "url-only" | "url-repo";
+    mode: "url-only" | "url-repo" | "auth-required";
     releaseConfidence: number;
     coveragePagesScanned: number;
     coverageBudgetExceeded: boolean;
@@ -310,10 +310,10 @@ export declare const GapAnalysisSchema: z.ZodObject<{
         source: "llm" | "template";
         outputPath: string;
     }[];
-    coverageWarning?: "budget-exceeded" | "low-coverage" | "navigation-failures" | undefined;
+    coverageWarning?: "auth-required" | "budget-exceeded" | "low-coverage" | "navigation-failures" | undefined;
 }, {
     analyzedAt: string;
-    mode: "url-only" | "url-repo";
+    mode: "url-only" | "url-repo" | "auth-required";
     releaseConfidence: number;
     coveragePagesScanned: number;
     coverageBudgetExceeded: boolean;
@@ -352,7 +352,7 @@ export declare const GapAnalysisSchema: z.ZodObject<{
         source: "llm" | "template";
         outputPath: string;
     }[];
-    coverageWarning?: "budget-exceeded" | "low-coverage" | "navigation-failures" | undefined;
+    coverageWarning?: "auth-required" | "budget-exceeded" | "low-coverage" | "navigation-failures" | undefined;
 }>;
 export type GapAnalysis = z.infer<typeof GapAnalysisSchema>;
 export type Gap = z.infer<typeof GapSchema>;

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

@@ -1 +1 @@
-{"version":3,"file":"gap-analysis.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/gap-analysis.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;EAMpB,CAAC;AAEH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;EAIxC,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;EAgBzB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAUhC,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;EAO9B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAC5C,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC"}
+{"version":3,"file":"gap-analysis.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/gap-analysis.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;EAMpB,CAAC;AAEH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;EAIxC,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;EAgBzB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAUhC,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;EAO9B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAC5C,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC"}

package/dist/schemas/gap-analysis.schema.js

@@ -49,11 +49,13 @@ export const GeneratedTestSchema = z.object({
 });
 export const GapAnalysisSchema = z.object({
     analyzedAt: z.string().datetime(),
-    mode: z.enum(['url-only', 'url-repo']),
+    mode: z.enum(['url-only', 'url-repo', 'auth-required']),
     releaseConfidence: z.number().min(0).max(100),
     coveragePagesScanned: z.number().int().min(0),
     coverageBudgetExceeded: z.boolean(),
-    coverageWarning: z.enum(['budget-exceeded', 'low-coverage', 'navigation-failures']).optional(),
+    coverageWarning: z
+        .enum(['budget-exceeded', 'low-coverage', 'navigation-failures', 'auth-required'])
+        .optional(),
     gaps: z.array(GapSchema),
     scenarios: z.array(NeutralScenarioSchema),
     generatedTests: z.array(GeneratedTestSchema),

package/dist/schemas/index.d.ts

@@ -1,4 +1,4 @@
-export { HarnessConfigSchema, AuthConfigSchema, type ExplorerType, type AdapterType, type FormLoginAuthConfig, type StorageStateAuthConfig, type AuthConfig, type HarnessConfig, } from './config.schema.js';
+export { HarnessConfigSchema, AuthConfigSchema, DetectedAuthSchema, type ExplorerType, type AdapterType, type FormLoginAuthConfig, type StorageStateAuthConfig, type AuthConfig, type HarnessConfig, type DetectedAuth, } 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,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,KAAK,aAAa,GACnB,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,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"}

package/dist/schemas/index.js

@@ -1,4 +1,4 @@
-export { HarnessConfigSchema, AuthConfigSchema, } from './config.schema.js';
+export { HarnessConfigSchema, AuthConfigSchema, DetectedAuthSchema, } 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/tools/auth-detector.d.ts

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

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

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

package/dist/tools/auth-detector.js

@@ -0,0 +1,134 @@
+import { chromium } from '@playwright/test';
+const OAUTH_PROVIDERS = [
+    { provider: 'github', patterns: [/github/i, /sign in with github/i] },
+    {
+        provider: 'google',
+        patterns: [/google/i, /sign in with google/i, /accounts\.google\.com/i],
+    },
+    {
+        provider: 'microsoft',
+        patterns: [/microsoft/i, /sign in with microsoft/i, /login\.microsoftonline\.com/i],
+    },
+    { provider: 'apple', patterns: [/apple/i, /sign in with apple/i] },
+    { provider: 'auth0', patterns: [/auth0/i] },
+    { provider: 'okta', patterns: [/okta/i] },
+];
+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));
+}
+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 firstTextInputNameForLogin(page) {
+    const emailName = await page.locator('input[type="email"]').first().getAttribute('name').catch(() => null);
+    if (emailName) {
+        return emailName;
+    }
+    const textInputs = page.locator('input[type="text"]');
+    const count = await textInputs.count();
+    for (let i = 0; i < count; i++) {
+        const name = await textInputs.nth(i).getAttribute('name');
+        if (name && /user|email|login/i.test(name)) {
+            return name;
+        }
+    }
+    return null;
+}
+export async function detectAuth(url, timeoutMs = 15000) {
+    const browser = await chromium.launch({ headless: true });
+    try {
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        await page.goto(url, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+        let loginUrl = url;
+        const looksLikeLoginPage = /login|sign[- ]?in|auth/i.test(page.url()) ||
+            (await page.locator('input[type="password"]').count()) > 0;
+        if (!looksLikeLoginPage) {
+            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) {
+                    loginUrl = new URL(href, url).toString();
+                    await page.goto(loginUrl, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+                }
+            }
+        }
+        const passwordInputs = page.locator('input[type="password"]');
+        const passwordCount = await passwordInputs.count();
+        const hasFormLogin = passwordCount > 0;
+        const oauthButtons = [];
+        const buttonTexts = await page.locator('button, a').allInnerTexts();
+        for (const text of buttonTexts) {
+            const trimmed = text.trim();
+            if (!textLooksLikeOAuthIdpButton(trimmed)) {
+                continue;
+            }
+            for (const { provider, patterns } of OAUTH_PROVIDERS) {
+                if (patterns.some((p) => p.test(trimmed))) {
+                    if (!oauthButtons.find((b) => b.provider === provider)) {
+                        oauthButtons.push({ provider, text: trimmed.slice(0, 100) });
+                    }
+                }
+            }
+        }
+        const pageText = await page.locator('body').innerText().catch(() => '');
+        const hasMagicLink = MAGIC_LINK_PATTERNS.some((p) => p.test(pageText));
+        let type = 'none';
+        let provider = null;
+        let observedSelectors = null;
+        let recommendation = '';
+        if (oauthButtons.length > 0) {
+            type = 'oauth';
+            provider = oauthButtons[0].provider;
+            recommendation = `OAuth detected (${oauthButtons.map((b) => b.provider).join(', ')}). OAuth cannot be automated. Run "qulib auth init --base-url ${url}" to log in manually once and save a reusable storage state file.`;
+        }
+        else if (hasFormLogin) {
+            type = 'form-login';
+            const usernameName = await firstTextInputNameForLogin(page);
+            const passwordName = await passwordInputs.first().getAttribute('name').catch(() => null);
+            const submitName = await page
+                .locator('button[type="submit"], input[type="submit"]')
+                .first()
+                .getAttribute('name')
+                .catch(() => null);
+            observedSelectors = {
+                usernameSelector: usernameName ? `input[name="${usernameName}"]` : null,
+                passwordSelector: passwordName ? `input[name="${passwordName}"]` : null,
+                submitSelector: submitName ? `button[name="${submitName}"]` : 'button[type="submit"]',
+            };
+            recommendation = `Form login detected. Configure auth with type="form-login", credentials, and the selectors above. Test selectors in your browser dev tools to confirm.`;
+        }
+        else if (hasMagicLink) {
+            type = 'magic-link';
+            recommendation = `Magic link / passwordless auth detected. Qulib cannot complete email-link flows. Run "qulib auth init --base-url ${url}" to log in manually once and save a storage state file.`;
+        }
+        else if (looksLikeLoginPage) {
+            type = 'unknown';
+            recommendation = `Authentication required but the pattern is unrecognized. Use "qulib auth init --base-url ${url}" to capture a storage state by logging in manually.`;
+        }
+        else {
+            type = 'none';
+            recommendation = `No authentication required for the entry URL. Qulib can scan anonymously.`;
+        }
+        return {
+            hasAuth: type !== 'none',
+            type,
+            provider,
+            loginUrl: type === 'none' ? null : loginUrl,
+            observedSelectors,
+            oauthButtons,
+            recommendation,
+        };
+    }
+    finally {
+        await browser.close();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qulib/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Qulib — analyze deployed web apps for honest quality gaps (CLI + programmatic API)",
   "license": "MIT",
   "author": "Tapesh Nagarwal",