@qulib/core 0.5.2 → 0.5.3

package/README.md

@@ -49,13 +49,13 @@ This opens a real browser. Log in normally (OAuth, magic link, password manager,
 
 ### Automated form login (`auth login`)
 
-When **`detect-auth`** shows **`authOptions`** with **`type: "form-login"`** and **`requirements.method: "credentials"`** (including click-to-reveal paths such as Scholastic Sync), you can save a storage state **without** manual clicking:
+When **`detect-auth`** shows **`authOptions`** with **`type: "form-login"`** and **`requirements.method: "credentials"`** (including click-to-reveal paths such as NQ Login), you can save a storage state **without** manual clicking:
 
 ```bash
-qulib auth login --base-url https://platform.scholastic.com \
-  --auth-path scholastic-sync \
-  --credentials-file ~/.qulib/scholastic-creds.json \
-  --out ~/.qulib/scholastic-state.json
+qulib auth login --base-url https://notquality.com \
+  --auth-path nq-login \
+  --credentials-file ~/.qulib/nq-creds.json \
+  --out ~/.qulib/nq-state.json
 ```
 
 The JSON file must map **field `name`** values from `authOptions` to secrets, e.g. `{"username":"…","password":"…","hidden.datasource":"…"}`. Prefer **`--credentials-file`** over **`--credentials`** so values are not stored in shell history.
@@ -63,8 +63,8 @@ The JSON file must map **field `name`** values from `authOptions` to secrets, e.
 Then analyze with the saved session:
 
 ```bash
-qulib analyze --url https://platform.scholastic.com \
-  --auth-storage-state ~/.qulib/scholastic-state.json
+qulib analyze --url https://notquality.com \
+  --auth-storage-state ~/.qulib/nq-state.json
 ```
 
 Use **`--auth-path <id>`** when multiple **`form-login`** paths appear in **`authOptions`**. Use **`--success-url-contains <substring>`** for stricter success detection; otherwise Qulib infers success from URL changes or the password field disappearing (and warns if it cannot confirm).
@@ -102,9 +102,9 @@ For unfamiliar apps (especially enterprise SSO with several buttons), run **`qul
 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 add --id nq-login --label "NQ Login" --pattern "nq login"
 qulib auth providers list
-qulib auth providers remove --id scholastic-sync
+qulib auth providers remove --id nq-login
 ```
 
 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.

package/dist/cli/index.js

@@ -225,9 +225,9 @@ providersCmd
 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('--id <id>', 'Stable id (kebab-case), e.g. nq-login')
     .requiredOption('--label <label>', 'Human-readable label')
-    .requiredOption('--pattern <regex>', 'Regex source, e.g. scholastic sync')
+    .requiredOption('--pattern <regex>', 'Regex source, e.g. nq login')
     .action(async (opts) => {
     try {
         new RegExp(opts.pattern, 'i');
@@ -289,7 +289,7 @@ authCmd
     .command('login')
     .description('Detect form-login on the URL, fill credentials, and save the storage state automatically (uses selectors from detect-auth)')
     .requiredOption('--base-url <url>', 'The base URL of the app to log into')
-    .option('--auth-path <id>', 'Specific authOption id to use (e.g. "scholastic-sync") when multiple form-login paths exist')
+    .option('--auth-path <id>', 'Specific authOption id to use (e.g. "nq-login") when multiple form-login paths exist')
     .option('--credentials <json>', 'JSON object mapping field name → value, e.g. \'{"username":"a","password":"b","hidden.datasource":"NYC"}\'')
     .option('--credentials-file <path>', 'Path to a JSON file with the credentials object (keeps secrets out of shell history)')
     .option('--out <path>', 'Output file path for the storage state JSON', './qulib-storage-state.json')

package/dist/tools/auth/detect.d.ts

@@ -7,6 +7,14 @@ export interface StorageStateValidationResult {
     reasonCode: StorageStateInvalidReason | 'ok';
     reason: string;
 }
+export declare function pickCredentialFieldName(attrs: {
+    name?: string | null;
+    id?: string | null;
+    autocomplete?: string | null;
+    type?: string | null;
+    placeholder?: string | null;
+    ariaLabel?: string | null;
+}): string;
 export declare function evaluateStorageStateValidity(signals: {
     expectedOrigin: string;
     finalUrl: string;

package/dist/tools/auth/detect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../../src/tools/auth/detect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAIzE,MAAM,MAAM,yBAAyB,GACjC,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,cAAc,GACd,yBAAyB,GACzB,iBAAiB,GACjB,SAAS,CAAC;AAEd,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAuRD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;CAC9B,GAAG,4BAA4B,CA6B/B;AAOD,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC,CAgD9C;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,SAAS,SAAQ,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAelD;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,SAAS,SAAQ,GAChB,OAAO,CAAC,4BAA4B,CAAC,CAyDvC;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAqJvB"}
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../../src/tools/auth/detect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAIzE,MAAM,MAAM,yBAAyB,GACjC,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,cAAc,GACd,yBAAyB,GACzB,iBAAiB,GACjB,SAAS,CAAC;AAEd,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AA4FD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,GAAG,MAAM,CAgBT;AAiMD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;CAC9B,GAAG,4BAA4B,CA6B/B;AAOD,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC,CAgD9C;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,SAAS,SAAQ,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAelD;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,SAAS,SAAQ,GAChB,OAAO,CAAC,4BAA4B,CAAC,CAyDvC;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAqJvB"}

package/dist/tools/auth/detect.js

@@ -83,21 +83,45 @@ async function resolveVisibleFieldLabel(page, el) {
     const typ = (await el.getAttribute('type'))?.trim();
     return typ && typ !== 'select' ? typ : 'text';
 }
-async function deriveCredentialFieldName(el) {
-    const name = (await el.getAttribute('name'))?.trim();
+function looksLikeExampleValue(s) {
+    return /@|:\/\//.test(s);
+}
+export function pickCredentialFieldName(attrs) {
+    const name = attrs.name?.trim();
     if (name)
         return name;
-    const placeholder = (await el.getAttribute('placeholder'))?.trim();
-    if (placeholder)
-        return slugify(placeholder);
-    const aria = (await el.getAttribute('aria-label'))?.trim();
-    if (aria)
-        return slugify(aria);
-    const id = (await el.getAttribute('id'))?.trim();
+    const id = attrs.id?.trim();
     if (id)
         return slugify(id);
+    const autocomplete = attrs.autocomplete?.trim().toLowerCase();
+    if (autocomplete === 'username' || autocomplete === 'email')
+        return autocomplete;
+    if (autocomplete === 'current-password' || autocomplete === 'new-password')
+        return 'password';
+    const type = attrs.type?.trim().toLowerCase();
+    if (type === 'email')
+        return 'email';
+    if (type === 'password')
+        return 'password';
+    const placeholder = attrs.placeholder?.trim();
+    if (placeholder && !looksLikeExampleValue(placeholder))
+        return slugify(placeholder);
+    const aria = attrs.ariaLabel?.trim();
+    if (aria && !looksLikeExampleValue(aria))
+        return slugify(aria);
     return 'field';
 }
+async function deriveCredentialFieldName(el) {
+    const [name, id, autocomplete, type, placeholder, ariaLabel] = await Promise.all([
+        el.getAttribute('name'),
+        el.getAttribute('id'),
+        el.getAttribute('autocomplete'),
+        el.getAttribute('type'),
+        el.getAttribute('placeholder'),
+        el.getAttribute('aria-label'),
+    ]);
+    return pickCredentialFieldName({ name, id, autocomplete, type, placeholder, ariaLabel });
+}
 async function buildCredentialFieldsFromVisibleForm(page) {
     const fields = [];
     const seen = new Set();

package/package.json

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

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

@@ -1,4 +0,0 @@
-import type { Browser, BrowserContext } from '@playwright/test';
-import type { AuthConfig } from '../schemas/config.schema.js';
-export declare function createAuthenticatedContext(browser: Browser, auth: AuthConfig | undefined, timeoutMs: number): Promise<BrowserContext>;
-//# sourceMappingURL=apply-auth.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"apply-auth.d.ts","sourceRoot":"","sources":["../../src/tools/apply-auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEhE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,UAAU,GAAG,SAAS,EAC5B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,CAAC,CAsCzB"}

package/dist/tools/apply-auth.js

@@ -1,35 +0,0 @@
-import { resolve } from 'node:path';
-export async function createAuthenticatedContext(browser, auth, timeoutMs) {
-    if (!auth) {
-        return browser.newContext();
-    }
-    if (auth.type === 'storage-state') {
-        const storagePath = resolve(process.cwd(), auth.path);
-        return browser.newContext({ storageState: storagePath });
-    }
-    const context = await browser.newContext();
-    const page = await context.newPage();
-    try {
-        await page.goto(auth.loginUrl, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
-        await page.fill(auth.selectors.username, auth.credentials.username);
-        await page.fill(auth.selectors.password, auth.credentials.password);
-        await page.click(auth.selectors.submit);
-        const urlFragment = auth.successIndicator.urlContains;
-        if (urlFragment) {
-            await page.waitForURL((url) => url.toString().includes(urlFragment), {
-                timeout: timeoutMs,
-            });
-        }
-        const visibleSelector = auth.successIndicator.selectorVisible;
-        if (visibleSelector) {
-            await page.waitForSelector(visibleSelector, {
-                timeout: timeoutMs,
-                state: 'visible',
-            });
-        }
-    }
-    finally {
-        await page.close();
-    }
-    return context;
-}

package/dist/tools/auth/block-gap.d.ts

@@ -1,9 +0,0 @@
-import type { Gap } from '../../schemas/gap-analysis.schema.js';
-import type { StorageStateInvalidReason } from './detector.js';
-export declare function buildAuthBlockGap(url: string): Gap;
-export declare function buildStorageStateInvalidGap(input: {
-    url: string;
-    reasonCode: StorageStateInvalidReason;
-    reason: string;
-}): Gap;
-//# sourceMappingURL=block-gap.d.ts.map

package/dist/tools/auth/block-gap.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"block-gap.d.ts","sourceRoot":"","sources":["../../../src/tools/auth/block-gap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,sCAAsC,CAAC;AAChE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAmB/D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAYlD;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,yBAAyB,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,GAAG,CAqBN"}

package/dist/tools/auth/block-gap.js

@@ -1,52 +0,0 @@
-function safeOriginAndPath(url) {
-    try {
-        const u = new URL(url);
-        return `${u.origin}${u.pathname}`;
-    }
-    catch {
-        return url;
-    }
-}
-function safeHost(url) {
-    try {
-        return new URL(url).hostname;
-    }
-    catch {
-        return url;
-    }
-}
-export function buildAuthBlockGap(url) {
-    const host = safeHost(url);
-    const safeUrl = safeOriginAndPath(url);
-    return {
-        id: 'auth-block',
-        path: '/',
-        severity: 'critical',
-        category: 'coverage',
-        reason: `Scan blocked by authentication. No authenticated pages were evaluated for ${host}.`,
-        description: 'Scan blocked by authentication. 0 authenticated pages were evaluated.',
-        recommendation: `Run \`qulib auth init --base-url ${safeUrl}\` to capture a storage state, then re-run with --auth storage-state.`,
-    };
-}
-export function buildStorageStateInvalidGap(input) {
-    const host = safeHost(input.url);
-    const safeUrl = safeOriginAndPath(input.url);
-    const recoveryByCode = {
-        'missing-file': `Storage state file was not found. Run \`qulib auth login --base-url ${safeUrl} --out <path>\` (or \`qulib auth init\`) to capture a fresh state, then re-run \`qulib analyze --url ${safeUrl} --auth-storage-state <path>\`.`,
-        'unreadable-file': `Storage state file exists but could not be read. Check file permissions, then re-run \`qulib auth login\` if needed.`,
-        'invalid-json': `Storage state file is not valid JSON. Run \`qulib auth login --base-url ${safeUrl} --out <path>\` again to regenerate it.`,
-        'wrong-origin': `Storage state belongs to a different origin than ${host}. Re-run \`qulib auth login --base-url ${safeUrl}\` against this target and pass the new file to \`qulib analyze\`.`,
-        'expired-or-unauthorized': `The session in the storage state has expired or is unauthorized. Run \`qulib auth login --base-url ${safeUrl}\` to capture a fresh state, then re-run \`qulib analyze --url ${safeUrl} --auth-storage-state <path>\`.`,
-        'no-auth-cookies': `Storage state file contains no cookies or localStorage entries — it is effectively empty. Run \`qulib auth login --base-url ${safeUrl}\` to capture a real session.`,
-        unknown: `Storage state could not be validated. Try \`qulib auth login --base-url ${safeUrl}\` again, and verify the file was saved on the same origin.`,
-    };
-    return {
-        id: 'storage-state-invalid',
-        path: '/',
-        severity: 'critical',
-        category: 'coverage',
-        reason: `Authenticated scan could not continue because the provided storage state is invalid for ${host}. Reason: ${input.reasonCode} — ${input.reason}.`,
-        description: `Storage state validation failed before crawling. The session was checked against ${host} and rejected with reason code "${input.reasonCode}".`,
-        recommendation: recoveryByCode[input.reasonCode],
-    };
-}

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

@@ -1,23 +0,0 @@
-import type { Page } from '@playwright/test';
-import type { DetectedAuth } from '../../schemas/config.schema.js';
-import type { AnalyzeProgressSink } from '../../harness/progress-log.js';
-export type StorageStateInvalidReason = 'missing-file' | 'unreadable-file' | 'invalid-json' | 'wrong-origin' | 'expired-or-unauthorized' | 'no-auth-cookies' | 'unknown';
-export interface StorageStateValidationResult {
-    valid: boolean;
-    reasonCode: StorageStateInvalidReason | 'ok';
-    reason: string;
-}
-export declare function evaluateStorageStateValidity(signals: {
-    expectedOrigin: string;
-    finalUrl: string;
-    visiblePasswordCount: number;
-    hadUnauthorizedHttp: boolean;
-}): StorageStateValidationResult;
-export declare function preflightStorageStateFile(storagePath: string): Promise<StorageStateValidationResult | null>;
-export declare function waitForReturnToOrigin(page: Page, baseUrl: string, timeoutMs?: number): Promise<{
-    returned: boolean;
-    finalUrl: string;
-}>;
-export declare function validateStorageState(url: string, storagePath: string, timeoutMs?: number): Promise<StorageStateValidationResult>;
-export declare function detectAuth(url: string, timeoutMs?: number, progress?: AnalyzeProgressSink): Promise<DetectedAuth>;
-//# sourceMappingURL=detector.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../../../src/tools/auth/detector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAIzE,MAAM,MAAM,yBAAyB,GACjC,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,cAAc,GACd,yBAAyB,GACzB,iBAAiB,GACjB,SAAS,CAAC;AAEd,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAsQD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;CAC9B,GAAG,4BAA4B,CA6B/B;AAOD,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC,CAgD9C;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,SAAS,SAAQ,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAelD;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,SAAS,SAAQ,GAChB,OAAO,CAAC,4BAA4B,CAAC,CAyDvC;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAqJvB"}