@qulib/core 0.4.0 → 0.4.2

package/README.md

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

package/dist/analyze.js

@@ -10,7 +10,7 @@ import { analyzeAuthSurfaceGaps } from './tools/auth-surface-analyzer.js';
 import { buildPublicSurface } from './tools/public-surface.js';
 import { buildAuthBlockGap } from './tools/auth-block-gap.js';
 import { finalizeGapAnalysisFromDraft } from './phases/think-finalize.js';
-import { emitTelemetry } from './telemetry/emit.js';
+import { emitTelemetry, redactUrlForTelemetry } from './telemetry/emit.js';
 function logScanEnd(progress, result) {
     const rc = result.releaseConfidence === null ? 'null' : String(result.releaseConfidence);
     const cs = result.coverageScore === null ? 'null' : String(result.coverageScore);
@@ -35,7 +35,7 @@ export async function analyzeApp(options) {
         ...(progress !== undefined && { progressLog: progress }),
     };
     emitTelemetry(options.telemetry, 'scan.started', sessionId, {
-        url: options.url,
+        url: redactUrlForTelemetry(options.url),
         maxPagesToScan: options.config.maxPagesToScan,
         hasAuth: Boolean(options.config.auth),
     });

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

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

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

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

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

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth-login-run.d.ts","sourceRoot":"","sources":["../../src/cli/auth-login-run.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAqB5D,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAEhE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4GhB"}

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

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

package/dist/cli/index.js

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

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

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

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

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

package/dist/harness/state-manager.js

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

package/dist/index.d.ts

@@ -6,11 +6,12 @@ export { scanRepo } from './tools/repo-scanner.js';
 export { computeAutomationMaturity } from './tools/automation-maturity.js';
 export { createProvider } from './llm/provider-registry.js';
 export { resolveMaxOutputTokensPerLlmCall } from './schemas/config.schema.js';
-export { resolveScanStateBaseDir } from './harness/state-manager.js';
+export { resolveScanStateBaseDir, resolveReportDir } from './harness/state-manager.js';
 export type { AnalyzeOptions, AnalyzeResult, AnalyzeStatus } from './analyze.js';
 export type { AnalyzeProgressSink } from './harness/progress-log.js';
 export type { TelemetrySink, TelemetryEvent, TelemetryEventKind, } from './telemetry/telemetry.interface.js';
 export { NoopTelemetrySink } from './telemetry/telemetry.interface.js';
+export { redactUrlForTelemetry } from './telemetry/emit.js';
 export type { LlmCallResult, LlmProvider } from './llm/provider.interface.js';
 export type { CallLlmConfigSlice } from './llm/provider.js';
 export type { HarnessConfig, AuthConfig, RouteInventory, GapAnalysis, RepoAnalysis, DetectedAuth, AuthExploration, AuthPath, AuthPathRequirements, CostIntelligence, LlmUsageRecord, RepeatedAiPattern, DeterministicMaturity, PublicSurface, AutomationMaturity, AutomationMaturityDimension, FrameworkDetectionResult, DetectedFrameworkPrimary, } from './schemas/index.js';

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,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnG,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,gCAAgC,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACjF,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,YAAY,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC9E,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,YAAY,EACV,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,GACzB,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,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,gCAAgC,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACvF,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACjF,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,YAAY,EACV,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC9E,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,YAAY,EACV,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,aAAa,EACb,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -6,5 +6,6 @@ export { scanRepo } from './tools/repo-scanner.js';
 export { computeAutomationMaturity } from './tools/automation-maturity.js';
 export { createProvider } from './llm/provider-registry.js';
 export { resolveMaxOutputTokensPerLlmCall } from './schemas/config.schema.js';
-export { resolveScanStateBaseDir } from './harness/state-manager.js';
+export { resolveScanStateBaseDir, resolveReportDir } from './harness/state-manager.js';
 export { NoopTelemetrySink } from './telemetry/telemetry.interface.js';
+export { redactUrlForTelemetry } from './telemetry/emit.js';

package/dist/phases/act.js

@@ -3,10 +3,10 @@ import { writeJsonReport } from '../reporters/json-reporter.js';
 import { writeMarkdownReport } from '../reporters/markdown-reporter.js';
 import { logDecision } from '../harness/decision-logger.js';
 import { emitTelemetry } from '../telemetry/emit.js';
-import { resolveScanStateBaseDir } from '../harness/state-manager.js';
+import { resolveReportDir, resolveScanStateBaseDir } from '../harness/state-manager.js';
 export async function act(analysis, config, artifacts = { writeArtifacts: true }) {
     const sessionId = artifacts.telemetrySessionId ?? 'none';
-    const reportDir = join(process.cwd(), 'output');
+    const reportDir = resolveReportDir(config.outputDir);
     const logOpts = {
         persist: artifacts.writeArtifacts,
         memory: artifacts.decisionMemory,
@@ -48,7 +48,7 @@ export async function act(analysis, config, artifacts = { writeArtifacts: true }
     if (config.requireHumanReview) {
         log('\n[qulib] Human review required before applying any generated output.');
         if (artifacts.writeArtifacts) {
-            log('  Reports:   output/report.json and output/report.md');
+            log(`  Reports:   ${join(reportDir, 'report.json')} and ${join(reportDir, 'report.md')}`);
             log(`  Decisions: ${join(resolveScanStateBaseDir(config.outputDir), 'decision-log.json')}`);
         }
         else {

package/dist/phases/observe.js

@@ -4,7 +4,7 @@ import { createExplorer } from '../tools/explorer-factory.js';
 import { scanRepo } from '../tools/repo-scanner.js';
 import { StateManager } from '../harness/state-manager.js';
 import { logDecision } from '../harness/decision-logger.js';
-import { emitTelemetry } from '../telemetry/emit.js';
+import { emitTelemetry, redactUrlForTelemetry } from '../telemetry/emit.js';
 export async function observe(baseUrl, repoPath, config, artifacts = { writeArtifacts: true }) {
     const sessionId = artifacts.telemetrySessionId ?? 'none';
     const explorer = createExplorer(config.explorer);
@@ -15,7 +15,7 @@ export async function observe(baseUrl, repoPath, config, artifacts = { writeArti
         outputDir: config.outputDir,
     };
     emitTelemetry(artifacts.telemetry, 'phase.observe.started', sessionId, {
-        baseUrl,
+        baseUrl: redactUrlForTelemetry(baseUrl),
         hasRepoPath: Boolean(repoPath),
     });
     const rawRoutes = await explorer.explore(baseUrl, config, artifacts);
@@ -29,7 +29,7 @@ export async function observe(baseUrl, repoPath, config, artifacts = { writeArti
         decision: 'exploration-complete',
         reason: `Discovered ${routes.routes.length} routes; budgetExceeded=${routes.budgetExceeded}`,
         metadata: {
-            baseUrl,
+            baseUrl: redactUrlForTelemetry(baseUrl),
             scannedRoutes: routes.routes.length,
             budgetExceeded: routes.budgetExceeded,
             pagesSkipped: routes.pagesSkipped,

package/dist/schemas/automation-maturity.schema.d.ts

@@ -1,22 +1,48 @@
 import { z } from 'zod';
+export declare const AutomationMaturityApplicabilitySchema: z.ZodEnum<["applicable", "not_applicable", "unknown"]>;
+/**
+ * Maturity dimension with explicit applicability so absent capabilities are not silently
+ * awarded partial credit.
+ *
+ * - `applicable`   — Qulib has enough signal to compute a real `score`.
+ * - `not_applicable` — The capability does not apply to this repo (e.g. component-test-ratio
+ *                     with no Cypress detected, auth-test-coverage when no auth signal exists).
+ *                     `score` is reported but excluded from the overall calculation.
+ * - `unknown`      — Qulib could not collect enough signal to score honestly (e.g. zero
+ *                     interactive elements scanned for test-id hygiene). Excluded from overall.
+ *
+ * Overall score formula (in `computeAutomationMaturity`):
+ *   numerator   = Σ score_i * weight_i  for i ∈ applicable dimensions
+ *   denominator = Σ weight_i            for i ∈ applicable dimensions
+ *   overallScore = round(numerator / denominator) when denominator > 0, else 0
+ *
+ * Schema fields stay backward compatible: both `applicability` and `reason` are optional.
+ * Existing consumers that don't read them keep working; honest reports populate them.
+ */
 export declare const AutomationMaturityDimensionSchema: z.ZodObject<{
     dimension: z.ZodEnum<["test-coverage-breadth", "framework-adoption", "test-id-hygiene", "ci-integration", "auth-test-coverage", "component-test-ratio"]>;
     score: z.ZodNumber;
     weight: z.ZodNumber;
     evidence: z.ZodArray<z.ZodString, "many">;
     recommendations: z.ZodArray<z.ZodString, "many">;
+    applicability: z.ZodOptional<z.ZodEnum<["applicable", "not_applicable", "unknown"]>>;
+    reason: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     recommendations: string[];
     dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
     score: number;
     weight: number;
     evidence: string[];
+    reason?: string | undefined;
+    applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
 }, {
     recommendations: string[];
     dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
     score: number;
     weight: number;
     evidence: string[];
+    reason?: string | undefined;
+    applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
 }>;
 export declare const AutomationMaturitySchema: z.ZodObject<{
     computedAt: z.ZodString;
@@ -30,20 +56,27 @@ export declare const AutomationMaturitySchema: z.ZodObject<{
         weight: z.ZodNumber;
         evidence: z.ZodArray<z.ZodString, "many">;
         recommendations: z.ZodArray<z.ZodString, "many">;
+        applicability: z.ZodOptional<z.ZodEnum<["applicable", "not_applicable", "unknown"]>>;
+        reason: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         recommendations: string[];
         dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
         score: number;
         weight: number;
         evidence: string[];
+        reason?: string | undefined;
+        applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
     }, {
         recommendations: string[];
         dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
         score: number;
         weight: number;
         evidence: string[];
+        reason?: string | undefined;
+        applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
     }>, "many">;
     topRecommendations: z.ZodArray<z.ZodString, "many">;
+    scoreFormula: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     label: string;
     level: number;
@@ -56,8 +89,11 @@ export declare const AutomationMaturitySchema: z.ZodObject<{
         score: number;
         weight: number;
         evidence: string[];
+        reason?: string | undefined;
+        applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
     }[];
     topRecommendations: string[];
+    scoreFormula?: string | undefined;
 }, {
     label: string;
     level: number;
@@ -70,9 +106,13 @@ export declare const AutomationMaturitySchema: z.ZodObject<{
         score: number;
         weight: number;
         evidence: string[];
+        reason?: string | undefined;
+        applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
     }[];
     topRecommendations: string[];
+    scoreFormula?: string | undefined;
 }>;
+export type AutomationMaturityApplicability = z.infer<typeof AutomationMaturityApplicabilitySchema>;
 export type AutomationMaturityDimension = z.infer<typeof AutomationMaturityDimensionSchema>;
 export type AutomationMaturity = z.infer<typeof AutomationMaturitySchema>;
 //# sourceMappingURL=automation-maturity.schema.d.ts.map

package/dist/schemas/automation-maturity.schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"automation-maturity.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/automation-maturity.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;EAa5C,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQnC,CAAC;AAEH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAC5F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"automation-maturity.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/automation-maturity.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,qCAAqC,wDAIhD,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;EAe5C,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASnC,CAAC;AAEH,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AACpG,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAC5F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/schemas/automation-maturity.schema.js

@@ -1,4 +1,28 @@
 import { z } from 'zod';
+export const AutomationMaturityApplicabilitySchema = z.enum([
+    'applicable',
+    'not_applicable',
+    'unknown',
+]);
+/**
+ * Maturity dimension with explicit applicability so absent capabilities are not silently
+ * awarded partial credit.
+ *
+ * - `applicable`   — Qulib has enough signal to compute a real `score`.
+ * - `not_applicable` — The capability does not apply to this repo (e.g. component-test-ratio
+ *                     with no Cypress detected, auth-test-coverage when no auth signal exists).
+ *                     `score` is reported but excluded from the overall calculation.
+ * - `unknown`      — Qulib could not collect enough signal to score honestly (e.g. zero
+ *                     interactive elements scanned for test-id hygiene). Excluded from overall.
+ *
+ * Overall score formula (in `computeAutomationMaturity`):
+ *   numerator   = Σ score_i * weight_i  for i ∈ applicable dimensions
+ *   denominator = Σ weight_i            for i ∈ applicable dimensions
+ *   overallScore = round(numerator / denominator) when denominator > 0, else 0
+ *
+ * Schema fields stay backward compatible: both `applicability` and `reason` are optional.
+ * Existing consumers that don't read them keep working; honest reports populate them.
+ */
 export const AutomationMaturityDimensionSchema = z.object({
     dimension: z.enum([
         'test-coverage-breadth',
@@ -12,6 +36,8 @@ export const AutomationMaturityDimensionSchema = z.object({
     weight: z.number().min(0).max(1),
     evidence: z.array(z.string()),
     recommendations: z.array(z.string()),
+    applicability: AutomationMaturityApplicabilitySchema.optional(),
+    reason: z.string().optional(),
 });
 export const AutomationMaturitySchema = z.object({
     computedAt: z.string().datetime(),
@@ -21,4 +47,5 @@ export const AutomationMaturitySchema = z.object({
     label: z.string(),
     dimensions: z.array(AutomationMaturityDimensionSchema),
     topRecommendations: z.array(z.string()),
+    scoreFormula: z.string().optional(),
 });