@qulib/core 0.2.1 → 0.3.0

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:
@@ -67,6 +81,29 @@ Or via MCP:
 
 > "Use qulib's detect_auth tool on https://app.example.com — what's the recommended auth setup?"
 
+## Release confidence
+
+The score (0–100) is derived from **deterministic gaps** (untested routes vs repo, console errors, broken links, axe violations). High-severity items subtract more than low-severity ones. If **`coveragePagesScanned` is below `minPagesForConfidence`**, the score is **capped at 40** and `coverageWarning` is set to **`low-coverage`** so a shallow crawl cannot masquerade as high confidence.
+
+When **`mode` is `auth-required`**, the scan never reached real app pages behind login: **release confidence is 0**, gaps are empty, and Cost Intelligence reflects the blocked state (L0 maturity).
+
+## LLM scenario budget (naming)
+
+- **`llmTokenBudget`** (legacy name, still required in config files): **max output tokens for a single** scenario-generation LLM completion. It maps to the provider’s **per-request completion cap**, not a multi-call or “whole run” token budget.
+- **`llmMaxOutputTokensPerCall`** (optional): when set, **overrides** `llmTokenBudget` for the same purpose—clearer naming.
+- **`enableLlmScenarios`**: when **`false`**, Qulib never calls an LLM for scenarios (templates only).
+
+## Cost Intelligence and `qulib cost doctor`
+
+After a normal **`analyze`**, `output/report.json` includes **`gapAnalysis.costIntelligence`**: usage records (**`actual`** vs **`estimated`** vs **`none`**), per-completion ceiling, budget warnings, repeated prompt fingerprints (when the same hash appears twice in one run), deterministic maturity (L0–L3 with an explicit ceiling for L4/L5), and conversion recommendations.
+
+Re-print that block from disk:
+
+```bash
+npx tsx src/cli/index.ts cost doctor
+# or: npx tsx src/cli/index.ts cost doctor --report output/report.json
+```
+
 ## CLI (from npm)
 
 ```bash
@@ -87,6 +124,8 @@ const config: HarnessConfig = {
   timeoutMs: 30000,
   retryCount: 2,
   llmTokenBudget: 4000,
+  llmMaxOutputTokensPerCall: undefined,
+  enableLlmScenarios: true,
   testGenerationLimit: 10,
   readOnlyMode: true,
   requireHumanReview: true,
@@ -102,7 +141,7 @@ const result = await analyzeApp({
   writeArtifacts: false,
 });
 
-console.log(result.releaseConfidence, result.gapAnalysis);
+console.log(result.releaseConfidence, result.gapAnalysis.costIntelligence);
 ```
 
 ## Repository
@@ -120,7 +159,7 @@ This package is part of **[Qulib](https://github.com/TapeshN/qulib)** ([repo REA
 - Optional **authenticated** crawling via `auth` in config (`form-login` or Playwright `storage-state`).
 - Repo scanner: routes, tests, Cypress structure.
 - Gap engine: deterministic gaps, **release confidence** with a low-page coverage floor, coverage warnings.
-- Reports: `output/report.json` and `output/report.md` when not using **`--ephemeral`**.
+- Reports: `output/report.json` and `output/report.md` when not using **`--ephemeral`** (both include **Cost Intelligence** when present on `gapAnalysis`).
 - State under `.scan-state/` unless **`--ephemeral`** (no disk writes; full JSON on stdout).
 - **`npm run clean`** removes generated `output/` and `.scan-state/` and restores `.gitkeep` placeholders.
 
@@ -158,6 +197,9 @@ Use the same **hostname** for `--url` as your app’s canonical host when you ca
 - `npm run dev` — CLI via `tsx` (append subcommands, e.g. `npm run dev -- clean`)
 - `npm run analyze -- --url <url> [--repo <path>] [--config <file>] [--ephemeral]`
 - `npm run clean` — reset `output/` and `.scan-state/` here
+- `npm run test` — unit tests (cost intelligence + hashing)
+- `npm run smoke` — ephemeral analyze of `https://example.com` (uses this package’s `qulib.config.ts`)
+- `npm run cost-doctor` — print Cost Intelligence from `output/report.json` (run a non-ephemeral `analyze` first)
 - `npm run build` — compile to `dist/`
 
 From the **repository root**:
@@ -195,7 +237,7 @@ npx playwright install chromium
 
 ## Output and state (cwd = `packages/core` when you `cd` here)
 
-**Ephemeral:** stdout prints one JSON object: `gapAnalysis`, `discoveredRoutes`, `repoInventory`, `decisionLog`.
+**Ephemeral:** stdout prints one JSON object: `gapAnalysis` (including **`costIntelligence`** when populated), `discoveredRoutes`, `repoInventory`, `decisionLog`.
 
 **Persistent:**
 

package/dist/analyze.d.ts

@@ -1,22 +1,34 @@
-import type { HarnessConfig, DetectedAuth } from './schemas/config.schema.js';
-import { type GapAnalysis } from './schemas/gap-analysis.schema.js';
-import type { RouteInventory } from './schemas/route-inventory.schema.js';
+import { type HarnessConfig, type DetectedAuth } from './schemas/config.schema.js';
+import type { Gap, GapAnalysis } from './schemas/gap-analysis.schema.js';
+import { type RouteInventory } from './schemas/route-inventory.schema.js';
 import type { RepoAnalysis } from './schemas/repo-analysis.schema.js';
 import type { DecisionLogEntry } from './schemas/decision-log.schema.js';
+import { type PublicSurface } from './schemas/public-surface.schema.js';
+import type { AnalyzeProgressSink } from './harness/progress-log.js';
+export type AnalyzeStatus = 'complete' | 'blocked' | 'partial';
 export interface AnalyzeOptions {
     url: string;
     repoPath?: string;
     config: HarnessConfig;
     writeArtifacts?: boolean;
     skipAuthDetection?: boolean;
+    progressLog?: AnalyzeProgressSink;
 }
 export interface AnalyzeResult {
-    releaseConfidence: number;
+    status: AnalyzeStatus;
+    coverageScore: number | null;
+    /** Quality of evaluated pages only; `null` when no evaluable surface produced a score (fully blocked). */
+    releaseConfidence: number | null;
+    /** Same entries as `gapAnalysis.gaps` for consumers that read a flat `gaps` field. */
+    gaps: Gap[];
     gapAnalysis: GapAnalysis;
+    /** Authenticated crawl scope only; empty routes when the scan stopped at an auth wall without credentials. */
     routeInventory: RouteInventory;
     repoInventory: RepoAnalysis | null;
     decisionLog: DecisionLogEntry[];
     detectedAuth?: DetectedAuth;
+    /** Crawled public routes and their gap-derived surface (complete scans); OAuth-wall scans use the pre-auth crawl only. */
+    publicSurface: PublicSurface | null;
 }
 export declare function analyzeApp(options: AnalyzeOptions): Promise<AnalyzeResult>;
 //# sourceMappingURL=analyze.d.ts.map

package/dist/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAMzE,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,WAAW,CAAC;IACzB,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA0DhF"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAChG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAU7F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,0GAA0G;IAC1G,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,sFAAsF;IACtF,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,WAAW,EAAE,WAAW,CAAC;IACzB,8GAA8G;IAC9G,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0HAA0H;IAC1H,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;CACrC;AAcD,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA8HhF"}

package/dist/analyze.js

@@ -1,61 +1,121 @@
-import { GapAnalysisSchema } from './schemas/gap-analysis.schema.js';
+import { RouteInventorySchema } from './schemas/route-inventory.schema.js';
+import { PublicSurfaceSchema } from './schemas/public-surface.schema.js';
 import { observe } from './phases/observe.js';
 import { think } from './phases/think.js';
 import { act } from './phases/act.js';
 import { detectAuth } from './tools/auth-detector.js';
+import { analyzeGaps, computeCoverageScore, computeQualityScoreFromGaps } from './tools/gap-engine.js';
+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';
+function logScanEnd(progress, result) {
+    const rc = result.releaseConfidence === null ? 'null' : String(result.releaseConfidence);
+    const cs = result.coverageScore === null ? 'null' : String(result.coverageScore);
+    progress?.info(`status=${result.status} | coverageScore=${cs} | releaseConfidence=${rc} | gaps=${result.gaps.length}`);
+    for (const g of result.gaps) {
+        progress?.debug(`gap id=${g.id} severity=${g.severity} category=${g.category}`);
+    }
+    if (process.env.QULIB_DEBUG === '1') {
+        progress?.debug(`gaps json=${JSON.stringify(result.gaps)}`);
+    }
+}
 export async function analyzeApp(options) {
     const writeArtifacts = options.writeArtifacts ?? false;
     const decisionLog = [];
+    const progress = options.progressLog;
     const artifacts = {
         writeArtifacts,
         decisionMemory: decisionLog,
+        ...(progress !== undefined && { progressLog: progress }),
     };
+    progress?.info(`Starting scan → ${options.url} maxPagesToScan=${options.config.maxPagesToScan}`);
+    let detectedAuth;
+    let authWall = false;
     if (!options.config.auth && !options.skipAuthDetection) {
-        const detection = await detectAuth(options.url, options.config.timeoutMs);
-        if (detection.hasAuth) {
-            const gapAnalysis = GapAnalysisSchema.parse({
-                analyzedAt: new Date().toISOString(),
-                mode: 'auth-required',
-                releaseConfidence: 0,
-                coveragePagesScanned: 0,
-                coverageBudgetExceeded: false,
-                coverageWarning: 'auth-required',
-                gaps: [],
-                scenarios: [],
-                generatedTests: [],
-            });
-            return {
-                releaseConfidence: 0,
-                gapAnalysis,
-                routeInventory: {
-                    scannedAt: new Date().toISOString(),
-                    baseUrl: options.url,
-                    routes: [],
-                    pagesSkipped: 0,
-                    budgetExceeded: false,
-                },
-                repoInventory: null,
-                decisionLog: [
-                    {
-                        timestamp: new Date().toISOString(),
-                        phase: 'observe',
-                        decision: 'auth-required',
-                        reason: detection.recommendation,
-                        metadata: { detection },
-                    },
-                ],
-                detectedAuth: detection,
-            };
-        }
+        detectedAuth = await detectAuth(options.url, options.config.timeoutMs, progress);
+        authWall = Boolean(detectedAuth.hasAuth);
     }
     const observed = await observe(options.url, options.repoPath, options.config, artifacts);
+    if (authWall && !options.config.auth && detectedAuth) {
+        decisionLog.push({
+            timestamp: new Date().toISOString(),
+            phase: 'observe',
+            decision: 'auth-required',
+            reason: detectedAuth.recommendation,
+            metadata: { detection: detectedAuth },
+        });
+        const status = observed.routes.routes.length === 0 ? 'blocked' : 'partial';
+        if (status === 'blocked') {
+            progress?.warn('Scan blocked by auth wall');
+        }
+        else {
+            progress?.warn('Auth wall: continuing with public surface only (partial)');
+        }
+        const mode = observed.repo ? 'url-repo' : 'url-only';
+        const publicAnalysis = analyzeGaps(observed.routes, observed.repo, mode, options.config);
+        const publicSurface = PublicSurfaceSchema.parse(buildPublicSurface(observed.routes.routes, publicAnalysis.gaps));
+        progress?.info(`Public surface crawl: ${publicSurface.pages.length} page(s) reachable pre-auth`);
+        const authSurfaceGaps = await analyzeAuthSurfaceGaps(options.url, detectedAuth, options.config.timeoutMs);
+        const authBlockGap = buildAuthBlockGap(options.url);
+        const qualityInputGaps = [...publicAnalysis.gaps, ...authSurfaceGaps];
+        const qualityScore = computeQualityScoreFromGaps(qualityInputGaps);
+        const draftRelease = status === 'blocked' ? null : qualityScore;
+        const draft = {
+            analyzedAt: new Date().toISOString(),
+            mode: 'auth-required',
+            releaseConfidence: draftRelease,
+            coveragePagesScanned: 0,
+            coverageBudgetExceeded: false,
+            coverageWarning: 'auth-required',
+            gaps: [...authSurfaceGaps, authBlockGap],
+        };
+        const costContext = {
+            mode: publicAnalysis.mode,
+            coveragePagesScanned: observed.routes.routes.length,
+            releaseConfidence: qualityScore,
+            gaps: publicAnalysis.gaps,
+        };
+        const gapAnalysis = await finalizeGapAnalysisFromDraft(draft, options.config, artifacts, costContext);
+        const emptyAuthRoutes = RouteInventorySchema.parse({
+            scannedAt: new Date().toISOString(),
+            baseUrl: options.url,
+            routes: [],
+            pagesSkipped: 0,
+            budgetExceeded: false,
+        });
+        await act(gapAnalysis, options.config, artifacts);
+        const result = {
+            status,
+            coverageScore: computeCoverageScore(observed.routes),
+            releaseConfidence: draftRelease,
+            gaps: gapAnalysis.gaps,
+            gapAnalysis,
+            routeInventory: emptyAuthRoutes,
+            repoInventory: observed.repo,
+            decisionLog,
+            detectedAuth,
+            publicSurface,
+        };
+        logScanEnd(progress, result);
+        return result;
+    }
     const analysis = await think(observed, options.config, artifacts);
     await act(analysis, options.config, artifacts);
-    return {
+    const publicSurface = PublicSurfaceSchema.parse(buildPublicSurface(observed.routes.routes, analysis.gaps));
+    progress?.info(`Public surface crawl: ${publicSurface.pages.length} page(s) reachable pre-auth`);
+    const result = {
+        status: 'complete',
+        coverageScore: computeCoverageScore(observed.routes),
         releaseConfidence: analysis.releaseConfidence,
+        gaps: analysis.gaps,
         gapAnalysis: analysis,
         routeInventory: observed.routes,
         repoInventory: observed.repo,
         decisionLog,
+        ...(detectedAuth !== undefined && { detectedAuth }),
+        publicSurface,
     };
+    logScanEnd(progress, result);
+    return result;
 }

package/dist/cli/cost-doctor.d.ts

@@ -0,0 +1,2 @@
+export declare function runCostDoctor(reportPath: string): Promise<void>;
+//# sourceMappingURL=cost-doctor.d.ts.map

package/dist/cli/cost-doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-doctor.d.ts","sourceRoot":"","sources":["../../src/cli/cost-doctor.ts"],"names":[],"mappings":"AAIA,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA6ErE"}

package/dist/cli/cost-doctor.js

@@ -0,0 +1,72 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { GapAnalysisSchema } from '../schemas/gap-analysis.schema.js';
+export async function runCostDoctor(reportPath) {
+    const abs = resolve(process.cwd(), reportPath);
+    let raw;
+    try {
+        raw = await readFile(abs, 'utf8');
+    }
+    catch {
+        throw new Error(`Could not read ${abs}. Run \`qulib analyze --url <url>\` (without --ephemeral) from this directory first.`);
+    }
+    const parsed = GapAnalysisSchema.safeParse(JSON.parse(raw));
+    if (!parsed.success) {
+        throw new Error('File is not a valid gap analysis report (report.json schema mismatch).');
+    }
+    const ci = parsed.data.costIntelligence;
+    if (!ci) {
+        console.log('[qulib] No costIntelligence in this report (older scan). Re-run analyze with the current qulib version to populate Cost Intelligence.');
+        return;
+    }
+    console.log('# Qulib cost doctor\n');
+    console.log(`Report: ${abs}`);
+    console.log(`Analyzed at: ${parsed.data.analyzedAt}\n`);
+    console.log('## Token ceiling (per LLM completion)\n');
+    console.log(`- maxOutputTokensPerLlmCall: ${ci.maxOutputTokensPerLlmCall}`);
+    console.log(`- budgetRole: ${ci.budgetRole}\n`);
+    console.log('## Usage (this scan)\n');
+    console.log(`- Input / output tokens: ${ci.usageSummary.totalInputTokens} / ${ci.usageSummary.totalOutputTokens} (${ci.usageSummary.dataQuality})`);
+    if (ci.budgetWarnings.length) {
+        console.log('\n## Budget warnings\n');
+        for (const w of ci.budgetWarnings) {
+            console.log(`- ${w}`);
+        }
+    }
+    else {
+        console.log('\n## Budget warnings\n\n- (none)\n');
+    }
+    if (ci.repeatedOperations.length) {
+        console.log('\n## Repeated AI patterns\n');
+        for (const r of ci.repeatedOperations) {
+            console.log(`- ${r.promptHash} ×${r.count}`);
+            console.log(`  ${r.recommendation}`);
+        }
+    }
+    else {
+        console.log('\n## Repeated AI patterns\n\n- (none in this run)\n');
+    }
+    console.log('\n## Deterministic maturity\n');
+    console.log(`- ${ci.deterministicMaturity.label}`);
+    console.log(`- ${ci.deterministicMaturity.rationale}`);
+    if (ci.deterministicMaturity.ceilingNote) {
+        console.log(`- _${ci.deterministicMaturity.ceilingNote}_`);
+    }
+    console.log('\n## Conversion recommendations\n');
+    for (const c of ci.conversionRecommendations) {
+        console.log(`- ${c}`);
+    }
+    const topGap = [...parsed.data.gaps].sort((a, b) => {
+        const o = { critical: 0, high: 1, medium: 2, low: 3 };
+        return o[a.severity] - o[b.severity];
+    })[0];
+    console.log('\n## Next best deterministic check\n');
+    if (topGap) {
+        console.log(`- Prioritize **${topGap.category}** on \`${topGap.path}\` (${topGap.severity}): ${topGap.reason}`);
+    }
+    else {
+        console.log('- No gaps in this report; extend crawl coverage or add auth before chasing new checks.');
+    }
+    console.log('\n---\n');
+    console.log('TODO: correlate multiple historical reports and CI adapters for cross-run “cost doctor” diffing (not implemented yet).');
+}

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({
@@ -92,8 +93,13 @@ async function runAnalyze(options) {
     });
     if (ephemeral) {
         console.log(JSON.stringify({
+            status: result.status,
+            coverageScore: result.coverageScore,
+            releaseConfidence: result.releaseConfidence,
+            gaps: result.gaps,
             gapAnalysis: result.gapAnalysis,
             discoveredRoutes: result.routeInventory,
+            publicSurface: result.publicSurface,
             repoInventory: result.repoInventory,
             decisionLog: result.decisionLog,
             ...(result.detectedAuth !== undefined && { detectedAuth: result.detectedAuth }),
@@ -125,6 +131,15 @@ program
     await fs.writeFile('.scan-state/.gitkeep', '', 'utf8');
     console.log('[qulib] clean complete');
 });
+const costCmd = program.command('cost').description('Cost intelligence helpers');
+costCmd
+    .command('doctor')
+    .description('Print Cost Intelligence from output/report.json (run analyze without --ephemeral first)')
+    .option('--report <file>', 'Path to report.json relative to cwd', 'output/report.json')
+    .action(async (opts) => {
+    const { runCostDoctor } = await import('./cost-doctor.js');
+    await runCostDoctor(opts.report);
+});
 program
     .command('analyze')
     .description('Analyze an app for quality gaps')
@@ -166,6 +181,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 +200,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/harness/progress-log.d.ts

@@ -0,0 +1,7 @@
+export interface AnalyzeProgressSink {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+}
+//# sourceMappingURL=progress-log.d.ts.map

package/dist/harness/progress-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-log.d.ts","sourceRoot":"","sources":["../../src/harness/progress-log.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B"}

package/dist/harness/progress-log.js

@@ -0,0 +1 @@
+export {};

package/dist/harness/run-options.d.ts

@@ -1,6 +1,8 @@
 import type { DecisionLogEntry } from '../schemas/decision-log.schema.js';
+import type { AnalyzeProgressSink } from './progress-log.js';
 export type RunArtifactsOptions = {
     writeArtifacts: boolean;
     decisionMemory?: DecisionLogEntry[];
+    progressLog?: AnalyzeProgressSink;
 };
 //# sourceMappingURL=run-options.d.ts.map

package/dist/harness/run-options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-options.d.ts","sourceRoot":"","sources":["../../src/harness/run-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,MAAM,MAAM,mBAAmB,GAAG;IAChC,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,gBAAgB,EAAE,CAAC;CACrC,CAAC"}
+{"version":3,"file":"run-options.d.ts","sourceRoot":"","sources":["../../src/harness/run-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACpC,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACnC,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 export { analyzeApp } from './analyze.js';
 export { detectAuth } from './tools/auth-detector.js';
-export type { AnalyzeOptions, AnalyzeResult } from './analyze.js';
-export type { HarnessConfig, AuthConfig, RouteInventory, GapAnalysis, RepoAnalysis, DetectedAuth, } from './schemas/index.js';
+export { exploreAuth } from './tools/auth-explorer.js';
+export { addUserProvider, removeUserProvider, listUserProviders } from './tools/user-providers.js';
+export { resolveMaxOutputTokensPerLlmCall } from './schemas/config.schema.js';
+export type { AnalyzeOptions, AnalyzeResult, AnalyzeStatus } from './analyze.js';
+export type { AnalyzeProgressSink } from './harness/progress-log.js';
+export type { HarnessConfig, AuthConfig, RouteInventory, GapAnalysis, RepoAnalysis, DetectedAuth, AuthExploration, AuthPath, AuthPathRequirements, CostIntelligence, LlmUsageRecord, RepeatedAiPattern, DeterministicMaturity, PublicSurface, } 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,OAAO,EAAE,gCAAgC,EAAE,MAAM,4BAA4B,CAAC;AAC9E,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACjF,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,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,GACd,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,2 +1,5 @@
 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 { resolveMaxOutputTokensPerLlmCall } from './schemas/config.schema.js';

package/dist/llm/content-hash.d.ts

@@ -0,0 +1,2 @@
+export declare function hashForCostIntelligence(payload: string): string;
+//# sourceMappingURL=content-hash.d.ts.map

package/dist/llm/content-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-hash.d.ts","sourceRoot":"","sources":["../../src/llm/content-hash.ts"],"names":[],"mappings":"AAEA,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D"}

package/dist/llm/content-hash.js

@@ -0,0 +1,4 @@
+import { createHash } from 'node:crypto';
+export function hashForCostIntelligence(payload) {
+    return createHash('sha256').update(payload, 'utf8').digest('hex').slice(0, 32);
+}

package/dist/llm/context-builder.js

@@ -1,7 +1,7 @@
 export function buildGapPrompt(gaps, limit) {
     const topGaps = [...gaps]
         .sort((a, b) => {
-        const order = { high: 0, medium: 1, low: 2 };
+        const order = { critical: 0, high: 1, medium: 2, low: 3 };
         return order[a.severity] - order[b.severity];
     })
         .slice(0, limit);

package/dist/llm/cost-intelligence.d.ts

@@ -0,0 +1,29 @@
+import type { GapAnalysis } from '../schemas/gap-analysis.schema.js';
+import type { CostIntelligence, DeterministicMaturity, LlmUsageRecord, RepeatedAiPattern } from '../schemas/cost-intelligence.schema.js';
+export declare function summarizeUsageQuality(records: LlmUsageRecord[]): CostIntelligence['usageSummary'];
+export declare function buildBudgetWarnings(records: LlmUsageRecord[], maxOutputTokensPerLlmCall: number): string[];
+export declare function findRepeatedPromptPatterns(records: LlmUsageRecord[]): RepeatedAiPattern[];
+export declare function buildConversionRecommendations(params: {
+    scenarioSource: 'llm' | 'template';
+    repeatedOperations: RepeatedAiPattern[];
+    budgetWarnings: string[];
+    gapCount: number;
+}): string[];
+export declare function computeDeterministicMaturity(params: {
+    mode: GapAnalysis['mode'];
+    coveragePagesScanned: number;
+    gapCount: number;
+    scenarioSource: 'llm' | 'template';
+    repeatedOperations: RepeatedAiPattern[];
+    releaseConfidence: number | null;
+    requireHumanReview: boolean;
+}): DeterministicMaturity;
+export declare function assembleCostIntelligence(params: {
+    maxOutputTokensPerLlmCall: number;
+    records: LlmUsageRecord[];
+    partial: Pick<GapAnalysis, 'mode' | 'coveragePagesScanned' | 'releaseConfidence' | 'gaps'>;
+    scenarioSource: 'llm' | 'template';
+    requireHumanReview: boolean;
+}): CostIntelligence;
+export declare function costIntelligenceForAuthBlocked(maxOutputTokensPerLlmCall: number): CostIntelligence;
+//# sourceMappingURL=cost-intelligence.d.ts.map

package/dist/llm/cost-intelligence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-intelligence.d.ts","sourceRoot":"","sources":["../../src/llm/cost-intelligence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EAClB,MAAM,wCAAwC,CAAC;AAEhD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,gBAAgB,CAAC,cAAc,CAAC,CAYjG;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EAAE,EACzB,yBAAyB,EAAE,MAAM,GAChC,MAAM,EAAE,CAuBV;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,iBAAiB,EAAE,CAiBzF;AAED,wBAAgB,8BAA8B,CAAC,MAAM,EAAE;IACrD,cAAc,EAAE,KAAK,GAAG,UAAU,CAAC;IACnC,kBAAkB,EAAE,iBAAiB,EAAE,CAAC;IACxC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,EAAE,CAuBX;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,KAAK,GAAG,UAAU,CAAC;IACnC,kBAAkB,EAAE,iBAAiB,EAAE,CAAC;IACxC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,kBAAkB,EAAE,OAAO,CAAC;CAC7B,GAAG,qBAAqB,CA+CxB;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,yBAAyB,EAAE,MAAM,CAAC;IAClC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,OAAO,EAAE,IAAI,CACX,WAAW,EACX,MAAM,GAAG,sBAAsB,GAAG,mBAAmB,GAAG,MAAM,CAC/D,CAAC;IACF,cAAc,EAAE,KAAK,GAAG,UAAU,CAAC;IACnC,kBAAkB,EAAE,OAAO,CAAC;CAC7B,GAAG,gBAAgB,CA8BnB;AAED,wBAAgB,8BAA8B,CAAC,yBAAyB,EAAE,MAAM,GAAG,gBAAgB,CAoBlG"}