@qulib/core 0.2.1 → 0.2.2

package/README.md

@@ -55,6 +55,20 @@ 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.
 
+### 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.
+
+Unknown SSO buttons include **`unrecognizedButtons`** with a hint. Teach this machine to recognize a label next time:
+
+```bash
+qulib auth providers add --id scholastic-sync --label "Scholastic Sync" --pattern "scholastic sync"
+qulib auth providers list
+qulib auth providers remove --id scholastic-sync
+```
+
+Patterns live in **`~/.qulib/providers.json`** (per user, not in the repo). Built-in public platforms stay in qulib’s curated list; tenant-specific names are never shipped as built-ins.
+
 ### Auth detection
 
 To check what auth pattern a site uses before configuring anything:

package/dist/cli/index.js

@@ -6,6 +6,7 @@ import { z } from 'zod';
 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';
 const program = new Command();
 const AnalyzeUrlSchema = z.string().url();
 const FormLoginCliSchema = z.object({
@@ -166,6 +167,15 @@ program
         submitSelector: options.submitSelector,
     });
 });
+program
+    .command('explore-auth')
+    .description('Explore all sign-in paths (OAuth, forms, magic link) for agent-driven setup before analyze')
+    .requiredOption('--url <url>', 'URL of the app or login page')
+    .option('--timeout <ms>', 'Navigation timeout in ms', '20000')
+    .action(async (options) => {
+    const result = await exploreAuth(options.url, parseInt(options.timeout, 10));
+    console.log(JSON.stringify(result, null, 2));
+});
 program
     .command('detect-auth')
     .description('Detect the authentication pattern used by a deployed web app')
@@ -176,6 +186,43 @@ program
     console.log(JSON.stringify(result, null, 2));
 });
 const authCmd = program.command('auth').description('Authentication helpers for scans');
+const providersCmd = authCmd
+    .command('providers')
+    .description('User-local OAuth/SSO button patterns (~/.qulib/providers.json)');
+providersCmd
+    .command('list')
+    .description('List user-local providers registered on this machine')
+    .action(async () => {
+    const { listUserProviders } = await import('../tools/user-providers.js');
+    const providers = listUserProviders();
+    console.log(JSON.stringify(providers, null, 2));
+});
+providersCmd
+    .command('add')
+    .description('Register a custom provider pattern (case-insensitive regex source)')
+    .requiredOption('--id <id>', 'Stable id (kebab-case), e.g. scholastic-sync')
+    .requiredOption('--label <label>', 'Human-readable label')
+    .requiredOption('--pattern <regex>', 'Regex source, e.g. scholastic sync')
+    .action(async (opts) => {
+    try {
+        new RegExp(opts.pattern, 'i');
+    }
+    catch {
+        throw new Error(`Invalid regex pattern: ${opts.pattern}`);
+    }
+    const { addUserProvider } = await import('../tools/user-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`);
+});
+providersCmd
+    .command('remove')
+    .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 removed = removeUserProvider(opts.id);
+    console.log(removed ? `[qulib] Removed "${opts.id}"` : `[qulib] No provider with id "${opts.id}" found`);
+});
 authCmd
     .command('init')
     .description('Open a browser, let the user log in manually, save the storage state to a file for reuse')

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { analyzeApp } from './analyze.js';
 export { detectAuth } from './tools/auth-detector.js';
+export { exploreAuth } from './tools/auth-explorer.js';
+export { addUserProvider, removeUserProvider, listUserProviders } from './tools/user-providers.js';
 export type { AnalyzeOptions, AnalyzeResult } from './analyze.js';
-export type { HarnessConfig, AuthConfig, RouteInventory, GapAnalysis, RepoAnalysis, DetectedAuth, } from './schemas/index.js';
+export type { HarnessConfig, AuthConfig, RouteInventory, GapAnalysis, RepoAnalysis, DetectedAuth, AuthExploration, AuthPath, AuthPathRequirements, } 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,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnG,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EACV,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,oBAAoB,GACrB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,2 +1,4 @@
 export { analyzeApp } from './analyze.js';
 export { detectAuth } from './tools/auth-detector.js';
+export { exploreAuth } from './tools/auth-explorer.js';
+export { addUserProvider, removeUserProvider, listUserProviders } from './tools/user-providers.js';

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

@@ -384,5 +384,362 @@ export declare const DetectedAuthSchema: z.ZodObject<{
     recommendation: string;
 }>;
 export type DetectedAuth = z.infer<typeof DetectedAuthSchema>;
+export declare const AuthPathRequirementsSchema: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+    method: z.ZodLiteral<"storage-state">;
+    instruction: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    method: "storage-state";
+    instruction: string;
+}, {
+    method: "storage-state";
+    instruction: string;
+}>, z.ZodObject<{
+    method: z.ZodLiteral<"credentials">;
+    fields: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodEnum<["text", "password", "email", "select", "checkbox"]>;
+        observedOptions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        type: "password" | "text" | "email" | "select" | "checkbox";
+        name: string;
+        label: string;
+        observedOptions: string[];
+    }, {
+        type: "password" | "text" | "email" | "select" | "checkbox";
+        name: string;
+        label: string;
+        observedOptions?: string[] | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    method: "credentials";
+    fields: {
+        type: "password" | "text" | "email" | "select" | "checkbox";
+        name: string;
+        label: string;
+        observedOptions: string[];
+    }[];
+}, {
+    method: "credentials";
+    fields: {
+        type: "password" | "text" | "email" | "select" | "checkbox";
+        name: string;
+        label: string;
+        observedOptions?: string[] | undefined;
+    }[];
+}>, z.ZodObject<{
+    method: z.ZodLiteral<"unknown">;
+    instruction: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    method: "unknown";
+    instruction: string;
+}, {
+    method: "unknown";
+    instruction: string;
+}>]>;
+export declare const AuthPathSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodEnum<["oauth", "oauth-unknown", "form-login", "form-multi", "magic-link", "unknown"]>;
+    provider: z.ZodNullable<z.ZodString>;
+    source: z.ZodEnum<["built-in", "user-local", "heuristic"]>;
+    automatable: z.ZodBoolean;
+    confidence: z.ZodEnum<["high", "medium", "low"]>;
+    requirements: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+        method: z.ZodLiteral<"storage-state">;
+        instruction: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        method: "storage-state";
+        instruction: string;
+    }, {
+        method: "storage-state";
+        instruction: string;
+    }>, z.ZodObject<{
+        method: z.ZodLiteral<"credentials">;
+        fields: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodString;
+            type: z.ZodEnum<["text", "password", "email", "select", "checkbox"]>;
+            observedOptions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            type: "password" | "text" | "email" | "select" | "checkbox";
+            name: string;
+            label: string;
+            observedOptions: string[];
+        }, {
+            type: "password" | "text" | "email" | "select" | "checkbox";
+            name: string;
+            label: string;
+            observedOptions?: string[] | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        method: "credentials";
+        fields: {
+            type: "password" | "text" | "email" | "select" | "checkbox";
+            name: string;
+            label: string;
+            observedOptions: string[];
+        }[];
+    }, {
+        method: "credentials";
+        fields: {
+            type: "password" | "text" | "email" | "select" | "checkbox";
+            name: string;
+            label: string;
+            observedOptions?: string[] | undefined;
+        }[];
+    }>, z.ZodObject<{
+        method: z.ZodLiteral<"unknown">;
+        instruction: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        method: "unknown";
+        instruction: string;
+    }, {
+        method: "unknown";
+        instruction: string;
+    }>]>;
+}, "strip", z.ZodTypeAny, {
+    type: "unknown" | "form-login" | "oauth" | "magic-link" | "oauth-unknown" | "form-multi";
+    provider: string | null;
+    label: string;
+    id: string;
+    source: "built-in" | "user-local" | "heuristic";
+    automatable: boolean;
+    confidence: "high" | "medium" | "low";
+    requirements: {
+        method: "storage-state";
+        instruction: string;
+    } | {
+        method: "credentials";
+        fields: {
+            type: "password" | "text" | "email" | "select" | "checkbox";
+            name: string;
+            label: string;
+            observedOptions: string[];
+        }[];
+    } | {
+        method: "unknown";
+        instruction: string;
+    };
+}, {
+    type: "unknown" | "form-login" | "oauth" | "magic-link" | "oauth-unknown" | "form-multi";
+    provider: string | null;
+    label: string;
+    id: string;
+    source: "built-in" | "user-local" | "heuristic";
+    automatable: boolean;
+    confidence: "high" | "medium" | "low";
+    requirements: {
+        method: "storage-state";
+        instruction: string;
+    } | {
+        method: "credentials";
+        fields: {
+            type: "password" | "text" | "email" | "select" | "checkbox";
+            name: string;
+            label: string;
+            observedOptions?: string[] | undefined;
+        }[];
+    } | {
+        method: "unknown";
+        instruction: string;
+    };
+}>;
+export declare const AuthExplorationSchema: z.ZodObject<{
+    url: z.ZodString;
+    authRequired: z.ZodBoolean;
+    authScope: z.ZodEnum<["site-wide", "section-only", "optional", "none"]>;
+    authPaths: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodEnum<["oauth", "oauth-unknown", "form-login", "form-multi", "magic-link", "unknown"]>;
+        provider: z.ZodNullable<z.ZodString>;
+        source: z.ZodEnum<["built-in", "user-local", "heuristic"]>;
+        automatable: z.ZodBoolean;
+        confidence: z.ZodEnum<["high", "medium", "low"]>;
+        requirements: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+            method: z.ZodLiteral<"storage-state">;
+            instruction: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: "storage-state";
+            instruction: string;
+        }, {
+            method: "storage-state";
+            instruction: string;
+        }>, z.ZodObject<{
+            method: z.ZodLiteral<"credentials">;
+            fields: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                label: z.ZodString;
+                type: z.ZodEnum<["text", "password", "email", "select", "checkbox"]>;
+                observedOptions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            }, "strip", z.ZodTypeAny, {
+                type: "password" | "text" | "email" | "select" | "checkbox";
+                name: string;
+                label: string;
+                observedOptions: string[];
+            }, {
+                type: "password" | "text" | "email" | "select" | "checkbox";
+                name: string;
+                label: string;
+                observedOptions?: string[] | undefined;
+            }>, "many">;
+        }, "strip", z.ZodTypeAny, {
+            method: "credentials";
+            fields: {
+                type: "password" | "text" | "email" | "select" | "checkbox";
+                name: string;
+                label: string;
+                observedOptions: string[];
+            }[];
+        }, {
+            method: "credentials";
+            fields: {
+                type: "password" | "text" | "email" | "select" | "checkbox";
+                name: string;
+                label: string;
+                observedOptions?: string[] | undefined;
+            }[];
+        }>, z.ZodObject<{
+            method: z.ZodLiteral<"unknown">;
+            instruction: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            method: "unknown";
+            instruction: string;
+        }, {
+            method: "unknown";
+            instruction: string;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        type: "unknown" | "form-login" | "oauth" | "magic-link" | "oauth-unknown" | "form-multi";
+        provider: string | null;
+        label: string;
+        id: string;
+        source: "built-in" | "user-local" | "heuristic";
+        automatable: boolean;
+        confidence: "high" | "medium" | "low";
+        requirements: {
+            method: "storage-state";
+            instruction: string;
+        } | {
+            method: "credentials";
+            fields: {
+                type: "password" | "text" | "email" | "select" | "checkbox";
+                name: string;
+                label: string;
+                observedOptions: string[];
+            }[];
+        } | {
+            method: "unknown";
+            instruction: string;
+        };
+    }, {
+        type: "unknown" | "form-login" | "oauth" | "magic-link" | "oauth-unknown" | "form-multi";
+        provider: string | null;
+        label: string;
+        id: string;
+        source: "built-in" | "user-local" | "heuristic";
+        automatable: boolean;
+        confidence: "high" | "medium" | "low";
+        requirements: {
+            method: "storage-state";
+            instruction: string;
+        } | {
+            method: "credentials";
+            fields: {
+                type: "password" | "text" | "email" | "select" | "checkbox";
+                name: string;
+                label: string;
+                observedOptions?: string[] | undefined;
+            }[];
+        } | {
+            method: "unknown";
+            instruction: string;
+        };
+    }>, "many">;
+    observedAt: z.ZodString;
+    suggestedAgentBehavior: z.ZodString;
+    unrecognizedButtons: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        hint: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        hint: string;
+    }, {
+        label: string;
+        hint: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    authRequired: boolean;
+    authScope: "none" | "site-wide" | "section-only" | "optional";
+    authPaths: {
+        type: "unknown" | "form-login" | "oauth" | "magic-link" | "oauth-unknown" | "form-multi";
+        provider: string | null;
+        label: string;
+        id: string;
+        source: "built-in" | "user-local" | "heuristic";
+        automatable: boolean;
+        confidence: "high" | "medium" | "low";
+        requirements: {
+            method: "storage-state";
+            instruction: string;
+        } | {
+            method: "credentials";
+            fields: {
+                type: "password" | "text" | "email" | "select" | "checkbox";
+                name: string;
+                label: string;
+                observedOptions: string[];
+            }[];
+        } | {
+            method: "unknown";
+            instruction: string;
+        };
+    }[];
+    observedAt: string;
+    suggestedAgentBehavior: string;
+    unrecognizedButtons: {
+        label: string;
+        hint: string;
+    }[];
+}, {
+    url: string;
+    authRequired: boolean;
+    authScope: "none" | "site-wide" | "section-only" | "optional";
+    authPaths: {
+        type: "unknown" | "form-login" | "oauth" | "magic-link" | "oauth-unknown" | "form-multi";
+        provider: string | null;
+        label: string;
+        id: string;
+        source: "built-in" | "user-local" | "heuristic";
+        automatable: boolean;
+        confidence: "high" | "medium" | "low";
+        requirements: {
+            method: "storage-state";
+            instruction: string;
+        } | {
+            method: "credentials";
+            fields: {
+                type: "password" | "text" | "email" | "select" | "checkbox";
+                name: string;
+                label: string;
+                observedOptions?: string[] | undefined;
+            }[];
+        } | {
+            method: "unknown";
+            instruction: string;
+        };
+    }[];
+    observedAt: string;
+    suggestedAgentBehavior: string;
+    unrecognizedButtons?: {
+        label: string;
+        hint: string;
+    }[] | undefined;
+}>;
+export type AuthPathRequirements = z.infer<typeof AuthPathRequirementsSchema>;
+export type AuthPath = z.infer<typeof AuthPathSchema>;
+export type AuthExploration = z.infer<typeof AuthExplorationSchema>;
 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;AAEhE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmB7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,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;AAE9D,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAcrC,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASzB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAehC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/schemas/config.schema.js

@@ -55,3 +55,40 @@ export const DetectedAuthSchema = z.object({
     })),
     recommendation: z.string(),
 });
+export const AuthPathRequirementsSchema = z.discriminatedUnion('method', [
+    z.object({ method: z.literal('storage-state'), instruction: z.string() }),
+    z.object({
+        method: z.literal('credentials'),
+        fields: z.array(z.object({
+            name: z.string(),
+            label: z.string(),
+            type: z.enum(['text', 'password', 'email', 'select', 'checkbox']),
+            observedOptions: z.array(z.string()).default([]),
+        })),
+    }),
+    z.object({ method: z.literal('unknown'), instruction: z.string() }),
+]);
+export const AuthPathSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    type: z.enum(['oauth', 'oauth-unknown', 'form-login', 'form-multi', 'magic-link', 'unknown']),
+    provider: z.string().nullable(),
+    source: z.enum(['built-in', 'user-local', 'heuristic']),
+    automatable: z.boolean(),
+    confidence: z.enum(['high', 'medium', 'low']),
+    requirements: AuthPathRequirementsSchema,
+});
+export const AuthExplorationSchema = z.object({
+    url: z.string(),
+    authRequired: z.boolean(),
+    authScope: z.enum(['site-wide', 'section-only', 'optional', 'none']),
+    authPaths: z.array(AuthPathSchema),
+    observedAt: z.string(),
+    suggestedAgentBehavior: z.string(),
+    unrecognizedButtons: z
+        .array(z.object({
+        label: z.string(),
+        hint: z.string(),
+    }))
+        .default([]),
+});

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-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/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"}

package/dist/tools/oauth-providers.js

@@ -0,0 +1,21 @@
+export const BUILT_IN_OAUTH_PROVIDERS = [
+    { id: 'github', label: 'GitHub', patterns: [/\bgithub\b/i] },
+    { id: 'google', label: 'Google', patterns: [/\bgoogle\b/i, /accounts\.google\.com/i] },
+    { id: 'microsoft', label: 'Microsoft', patterns: [/microsoft/i, /login\.microsoftonline\.com/i] },
+    { id: 'apple', label: 'Apple', patterns: [/sign in with apple/i, /\bapple id\b/i] },
+    { id: 'facebook', label: 'Facebook', patterns: [/facebook/i] },
+    { id: 'twitter', label: 'Twitter/X', patterns: [/twitter\.com/i, /\bsign in with x\b/i] },
+    { id: 'linkedin', label: 'LinkedIn', patterns: [/linkedin/i] },
+    { id: 'auth0', label: 'Auth0', patterns: [/auth0/i] },
+    { id: 'okta', label: 'Okta', patterns: [/\bokta\b/i] },
+    { id: 'onelogin', label: 'OneLogin', patterns: [/onelogin/i] },
+    { id: 'duo', label: 'Duo Security', patterns: [/duo security/i] },
+    { id: 'ping', label: 'Ping Identity', patterns: [/pingidentity/i, /pingone/i] },
+    { id: 'workday', label: 'Workday', patterns: [/workday/i] },
+    { id: 'saml', label: 'SAML SSO', patterns: [/\bsaml\b/i] },
+    { id: 'clever', label: 'Clever', patterns: [/\bclever\b/i, /clever\.com/i] },
+    { id: 'classlink', label: 'ClassLink', patterns: [/classlink/i] },
+    { id: 'schoology', label: 'Schoology', patterns: [/schoology/i] },
+    { id: 'canvas', label: 'Canvas (Instructure)', patterns: [/\bcanvas lms\b/i, /instructure/i] },
+    { id: 'blackboard', label: 'Blackboard', patterns: [/blackboard/i] },
+];

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

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

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

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

package/dist/tools/user-providers.js

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

package/package.json

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