@qulib/core 0.8.2 → 0.9.0

package/dist/baseline/baseline.schema.d.ts

@@ -0,0 +1,233 @@
+import { z } from 'zod';
+/**
+ * A snapshot of a single gap found during a scan, stored in a baseline.
+ * Intentionally lighter than the full GapSchema: only the fields needed to
+ * detect meaningful drift between scans are captured.
+ */
+export declare const BaselineGapSchema: z.ZodObject<{
+    path: z.ZodString;
+    severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
+    category: z.ZodEnum<["untested-route", "a11y", "console-error", "broken-link", "auth-surface", "coverage", "untested-api-endpoint"]>;
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    severity: "critical" | "high" | "medium" | "low";
+    reason: string;
+    category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+}, {
+    path: string;
+    severity: "critical" | "high" | "medium" | "low";
+    reason: string;
+    category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+}>;
+export type BaselineGap = z.infer<typeof BaselineGapSchema>;
+/**
+ * A persisted baseline snapshot for a given URL, saved by `qulib baseline save`.
+ */
+export declare const BaselineSnapshotSchema: z.ZodObject<{
+    /** Monotonic slug used as the on-disk filename stem: <url-slug>__<timestamp> */
+    id: z.ZodString;
+    url: z.ZodString;
+    savedAt: z.ZodString;
+    releaseConfidence: z.ZodNumber;
+    gapCount: z.ZodNumber;
+    gaps: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
+        category: z.ZodEnum<["untested-route", "a11y", "console-error", "broken-link", "auth-surface", "coverage", "untested-api-endpoint"]>;
+        reason: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }, {
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }>, "many">;
+    label: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    url: string;
+    releaseConfidence: number;
+    gaps: {
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+    gapCount: number;
+    savedAt: string;
+    label?: string | undefined;
+}, {
+    id: string;
+    url: string;
+    releaseConfidence: number;
+    gaps: {
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+    gapCount: number;
+    savedAt: string;
+    label?: string | undefined;
+}>;
+export type BaselineSnapshot = z.infer<typeof BaselineSnapshotSchema>;
+/**
+ * A single change in gap status between two baselines.
+ */
+export declare const BaselineDeltaItemSchema: z.ZodObject<{
+    path: z.ZodString;
+    category: z.ZodEnum<["untested-route", "a11y", "console-error", "broken-link", "auth-surface", "coverage", "untested-api-endpoint"]>;
+    severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
+    reason: z.ZodString;
+    status: z.ZodEnum<["new", "resolved", "severity-increased", "severity-decreased"]>;
+}, "strip", z.ZodTypeAny, {
+    status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+    path: string;
+    severity: "critical" | "high" | "medium" | "low";
+    reason: string;
+    category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+}, {
+    status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+    path: string;
+    severity: "critical" | "high" | "medium" | "low";
+    reason: string;
+    category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+}>;
+export type BaselineDeltaItem = z.infer<typeof BaselineDeltaItemSchema>;
+/**
+ * The result of comparing two snapshots.
+ */
+export declare const BaselineDeltaSchema: z.ZodObject<{
+    fromId: z.ZodString;
+    toId: z.ZodString;
+    fromSavedAt: z.ZodString;
+    toSavedAt: z.ZodString;
+    fromReleaseConfidence: z.ZodNumber;
+    toReleaseConfidence: z.ZodNumber;
+    confidenceDelta: z.ZodNumber;
+    newGaps: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        category: z.ZodEnum<["untested-route", "a11y", "console-error", "broken-link", "auth-surface", "coverage", "untested-api-endpoint"]>;
+        severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
+        reason: z.ZodString;
+        status: z.ZodEnum<["new", "resolved", "severity-increased", "severity-decreased"]>;
+    }, "strip", z.ZodTypeAny, {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }, {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }>, "many">;
+    resolvedGaps: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        category: z.ZodEnum<["untested-route", "a11y", "console-error", "broken-link", "auth-surface", "coverage", "untested-api-endpoint"]>;
+        severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
+        reason: z.ZodString;
+        status: z.ZodEnum<["new", "resolved", "severity-increased", "severity-decreased"]>;
+    }, "strip", z.ZodTypeAny, {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }, {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }>, "many">;
+    severityChanges: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        category: z.ZodEnum<["untested-route", "a11y", "console-error", "broken-link", "auth-surface", "coverage", "untested-api-endpoint"]>;
+        severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
+        reason: z.ZodString;
+        status: z.ZodEnum<["new", "resolved", "severity-increased", "severity-decreased"]>;
+    }, "strip", z.ZodTypeAny, {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }, {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }>, "many">;
+    summary: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    summary: string;
+    fromId: string;
+    toId: string;
+    fromSavedAt: string;
+    toSavedAt: string;
+    fromReleaseConfidence: number;
+    toReleaseConfidence: number;
+    confidenceDelta: number;
+    newGaps: {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+    resolvedGaps: {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+    severityChanges: {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+}, {
+    summary: string;
+    fromId: string;
+    toId: string;
+    fromSavedAt: string;
+    toSavedAt: string;
+    fromReleaseConfidence: number;
+    toReleaseConfidence: number;
+    confidenceDelta: number;
+    newGaps: {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+    resolvedGaps: {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+    severityChanges: {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+}>;
+export type BaselineDelta = z.infer<typeof BaselineDeltaSchema>;
+//# sourceMappingURL=baseline.schema.d.ts.map

package/dist/baseline/baseline.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.schema.d.ts","sourceRoot":"","sources":["../../src/baseline/baseline.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;EAa5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,sBAAsB;IACjC,gFAAgF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQhF,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;EAMlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/baseline/baseline.schema.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+/**
+ * A snapshot of a single gap found during a scan, stored in a baseline.
+ * Intentionally lighter than the full GapSchema: only the fields needed to
+ * detect meaningful drift between scans are captured.
+ */
+export const BaselineGapSchema = z.object({
+    path: z.string(),
+    severity: z.enum(['critical', 'high', 'medium', 'low']),
+    category: z.enum([
+        'untested-route',
+        'a11y',
+        'console-error',
+        'broken-link',
+        'auth-surface',
+        'coverage',
+        'untested-api-endpoint',
+    ]),
+    reason: z.string(),
+});
+/**
+ * A persisted baseline snapshot for a given URL, saved by `qulib baseline save`.
+ */
+export const BaselineSnapshotSchema = z.object({
+    /** Monotonic slug used as the on-disk filename stem: <url-slug>__<timestamp> */
+    id: z.string(),
+    url: z.string(),
+    savedAt: z.string().datetime(),
+    releaseConfidence: z.number().min(0).max(100),
+    gapCount: z.number().int().min(0),
+    gaps: z.array(BaselineGapSchema),
+    label: z.string().optional(),
+});
+/**
+ * A single change in gap status between two baselines.
+ */
+export const BaselineDeltaItemSchema = z.object({
+    path: z.string(),
+    category: BaselineGapSchema.shape.category,
+    severity: BaselineGapSchema.shape.severity,
+    reason: z.string(),
+    status: z.enum(['new', 'resolved', 'severity-increased', 'severity-decreased']),
+});
+/**
+ * The result of comparing two snapshots.
+ */
+export const BaselineDeltaSchema = z.object({
+    fromId: z.string(),
+    toId: z.string(),
+    fromSavedAt: z.string().datetime(),
+    toSavedAt: z.string().datetime(),
+    fromReleaseConfidence: z.number().min(0).max(100),
+    toReleaseConfidence: z.number().min(0).max(100),
+    confidenceDelta: z.number(),
+    newGaps: z.array(BaselineDeltaItemSchema),
+    resolvedGaps: z.array(BaselineDeltaItemSchema),
+    severityChanges: z.array(BaselineDeltaItemSchema),
+    summary: z.string(),
+});

package/dist/cli/confidence-run.d.ts

@@ -0,0 +1,16 @@
+import type { Command } from 'commander';
+import type { ReleaseConfidence } from '../schemas/confidence.schema.js';
+export interface ConfidenceOptions {
+    url?: string;
+    repo?: string;
+    json?: boolean;
+}
+/** Render the human-friendly report for a ReleaseConfidence result. */
+export declare function formatConfidenceReport(rc: ReleaseConfidence, subjectRef: string): string;
+/**
+ * Core of the command, factored out of the action handler so node:test can drive it
+ * without spawning a subprocess.
+ */
+export declare function runConfidence(options: ConfidenceOptions, out?: (line: string) => void): Promise<ReleaseConfidence>;
+export declare function registerConfidenceCommand(program: Command): void;
+//# sourceMappingURL=confidence-run.d.ts.map

package/dist/cli/confidence-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence-run.d.ts","sourceRoot":"","sources":["../../src/cli/confidence-run.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAGzE,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAiBD,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAuCxF;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,iBAAiB,EAC1B,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkC,GACxD,OAAO,CAAC,iBAAiB,CAAC,CAmE5B;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmBhE"}

package/dist/cli/confidence-run.js

@@ -0,0 +1,158 @@
+/**
+ * `qulib confidence` — compute a fused Release Confidence verdict from qulib's own collectors.
+ *
+ * P3 — qulib Confidence Layer v1.
+ *
+ * Composes analyze_app (when --url is given) + computeAutomationMaturity + computeApiCoverage
+ * (when --repo is given) through buildConfidenceInputFromQulib → computeReleaseConfidence.
+ *
+ * The --json flag emits the full ReleaseConfidence object as JSON to stdout (for CI gates and
+ * orchestrators). Without --json, a human-readable report is printed.
+ *
+ * Mirrors the idiom established by score-automation-run.ts: one file owns the command end-to-end
+ * and is registered from cli/index.ts via registerConfidenceCommand(program).
+ */
+import { resolve } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import { analyzeApp } from '../analyze.js';
+import { scanRepo } from '../tools/repo/scan.js';
+import { computeAutomationMaturity } from '../tools/scoring/automation-maturity.js';
+import { discoverApiSurfaceWithRepo } from '../tools/repo/api-surface.js';
+import { computeApiCoverage } from '../tools/scoring/api-coverage.js';
+import { buildConfidenceInputFromQulib } from '../tools/scoring/confidence-from-qulib.js';
+import { computeReleaseConfidence } from '../tools/scoring/confidence.js';
+/**
+ * Resolve and validate an optional --repo path. Returns null if none was provided.
+ */
+function maybeResolveRepoPath(repoOption, cwd = process.cwd()) {
+    if (!repoOption || !repoOption.trim())
+        return null;
+    const abs = resolve(cwd, repoOption.trim());
+    if (!existsSync(abs)) {
+        throw new Error(`--repo path does not exist: ${abs}`);
+    }
+    if (!statSync(abs).isDirectory()) {
+        throw new Error(`--repo path is not a directory: ${abs}`);
+    }
+    return abs;
+}
+/** Render the human-friendly report for a ReleaseConfidence result. */
+export function formatConfidenceReport(rc, subjectRef) {
+    const lines = [];
+    const scoreStr = rc.confidenceScore !== null ? `${rc.confidenceScore}/100` : 'null (nothing evaluable)';
+    lines.push(`[qulib] Release confidence for ${subjectRef}`);
+    lines.push(`  verdict: ${rc.verdict}  —  ${rc.label} (score ${scoreStr}, level ${rc.level}/5)`);
+    if (rc.blockers.length > 0) {
+        lines.push('  blockers:');
+        for (const b of rc.blockers)
+            lines.push(`    • ${b}`);
+    }
+    lines.push('  contributions:');
+    for (const c of rc.contributions) {
+        const scoreLabel = c.score !== null ? `${c.score}/100` : 'n/a';
+        const ewLabel = c.effectiveWeight > 0
+            ? `ew=${(c.effectiveWeight * 100).toFixed(1)}%`
+            : 'excluded';
+        const blockingTag = c.blocking ? ' [BLOCKER]' : '';
+        lines.push(`    - ${c.source} [${c.applicability}]${blockingTag}: ${scoreLabel}  ${ewLabel}`);
+    }
+    if (rc.topRisks.length > 0) {
+        lines.push('  top risks:');
+        for (const r of rc.topRisks)
+            lines.push(`    • ${r}`);
+    }
+    if (rc.recommendedNextChecks.length > 0) {
+        lines.push('  recommended next checks:');
+        for (const r of rc.recommendedNextChecks)
+            lines.push(`    • ${r}`);
+    }
+    if (rc.honestyNotes.length > 0) {
+        lines.push('  honesty notes:');
+        for (const n of rc.honestyNotes)
+            lines.push(`    • ${n}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Core of the command, factored out of the action handler so node:test can drive it
+ * without spawning a subprocess.
+ */
+export async function runConfidence(options, out = (line) => console.log(line)) {
+    if (!options.url && !options.repo) {
+        throw new Error('qulib confidence requires at least one of --url or --repo.');
+    }
+    const repoPath = maybeResolveRepoPath(options.repo);
+    const subjectRef = options.url ?? repoPath ?? 'unknown';
+    const subjectKind = options.url && repoPath ? 'release' : options.url ? 'app' : 'repo';
+    const subject = { kind: subjectKind, ref: subjectRef, tenantId: 'default' };
+    let analyzeResult;
+    let maturityResult;
+    let apiCoverageResult;
+    if (options.url) {
+        if (!options.json) {
+            out(`[qulib] Analyzing ${options.url} (analyze_app)…`);
+        }
+        const harnessConfig = {
+            maxPagesToScan: 10,
+            maxDepth: 3,
+            minPagesForConfidence: 3,
+            timeoutMs: 30000,
+            retryCount: 0,
+            llmTokenBudget: 4096,
+            testGenerationLimit: 5,
+            enableLlmScenarios: false,
+            readOnlyMode: true,
+            requireHumanReview: false,
+            failOnConsoleError: false,
+            explorer: 'playwright',
+            defaultAdapter: 'playwright',
+            adapters: ['playwright'],
+        };
+        analyzeResult = await analyzeApp({
+            url: options.url,
+            writeArtifacts: false,
+            config: harnessConfig,
+        });
+    }
+    if (repoPath) {
+        if (!options.json) {
+            out(`[qulib] Scoring automation maturity + API coverage for ${repoPath}…`);
+        }
+        const repo = await scanRepo(repoPath);
+        maturityResult = computeAutomationMaturity(repo);
+        const apiSurface = await discoverApiSurfaceWithRepo(repoPath, repo, { enableTier3: false });
+        apiCoverageResult = computeApiCoverage(repo, apiSurface);
+    }
+    const confidenceInput = buildConfidenceInputFromQulib({
+        analyze: analyzeResult,
+        maturity: maturityResult,
+        apiCoverage: apiCoverageResult,
+        subject,
+    });
+    const rc = computeReleaseConfidence(confidenceInput);
+    if (options.json) {
+        out(JSON.stringify(rc, null, 2));
+    }
+    else {
+        out(formatConfidenceReport(rc, subjectRef));
+    }
+    return rc;
+}
+export function registerConfidenceCommand(program) {
+    program
+        .command('confidence')
+        .description('Compute a fused Release Confidence verdict from qulib evidence collectors. ' +
+        'Pass --url to include live-app quality + a11y + coverage evidence. ' +
+        'Pass --repo to include test-automation maturity + API coverage. ' +
+        'Both may be combined.')
+        .option('--url <url>', 'URL of the deployed app to analyze')
+        .option('--repo <path>', 'Path to the local repository to score')
+        .option('--json', 'Emit the full ReleaseConfidence object as JSON to stdout', false)
+        .action(async (options) => {
+        await runConfidence({
+            url: options.url,
+            repo: options.repo,
+            json: Boolean(options.json),
+        });
+    });
+}

package/dist/cli/index.d.ts

@@ -1,3 +1,13 @@
 #!/usr/bin/env node
-export {};
+import { type HarnessConfig } from '../schemas/config.schema.js';
+/**
+ * Built-in fallback used when no --config is passed AND the default qulib.config.ts
+ * is absent from the working directory. Mirrors the values in packages/core/qulib.config.ts
+ * so `npx @qulib/core analyze --url ... --ephemeral` works in any directory.
+ *
+ * An EXPLICIT --config pointing at a missing file is always a hard error.
+ * This constant lives in the CLI layer — schemas remain additive-only and required
+ * fields are NOT converted to defaulted ones.
+ */
+export declare const DEFAULT_HARNESS_CONFIG: HarnessConfig;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AASA,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEtF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAepC,CAAC"}

package/dist/cli/index.js

@@ -7,12 +7,40 @@ import { z } from 'zod';
 const requirePkg = createRequire(import.meta.url);
 const pkg = requirePkg('../../package.json');
 import { HarnessConfigSchema } from '../schemas/config.schema.js';
+/**
+ * Built-in fallback used when no --config is passed AND the default qulib.config.ts
+ * is absent from the working directory. Mirrors the values in packages/core/qulib.config.ts
+ * so `npx @qulib/core analyze --url ... --ephemeral` works in any directory.
+ *
+ * An EXPLICIT --config pointing at a missing file is always a hard error.
+ * This constant lives in the CLI layer — schemas remain additive-only and required
+ * fields are NOT converted to defaulted ones.
+ */
+export const DEFAULT_HARNESS_CONFIG = {
+    maxPagesToScan: 20,
+    maxDepth: 3,
+    minPagesForConfidence: 3,
+    timeoutMs: 30000,
+    retryCount: 2,
+    llmTokenBudget: 4000,
+    testGenerationLimit: 10,
+    enableLlmScenarios: true,
+    readOnlyMode: true,
+    requireHumanReview: true,
+    failOnConsoleError: false,
+    explorer: 'playwright',
+    defaultAdapter: 'playwright',
+    adapters: ['playwright'],
+};
 import { analyzeApp } from '../analyze.js';
 import { toAgentSummary } from '../agent-summary.js';
 import { detectAuth } from '../tools/auth/detect.js';
 import { exploreAuth } from '../tools/auth/explore.js';
 import { assertExactlyOneCredentialSource, parseCredentialsJsonString, resolveAuthLoginConfig, } from './auth-login-resolve.js';
 import { runAutomatedAuthLogin } from './auth-login-run.js';
+import { registerScaffoldCommand } from './scaffold-run.js';
+import { registerScoreAutomationCommand } from './score-automation-run.js';
+import { registerConfidenceCommand } from './confidence-run.js';
 const program = new Command();
 const AnalyzeUrlSchema = z.string().url();
 const FormLoginCliSchema = z.object({
@@ -23,11 +51,50 @@ const FormLoginCliSchema = z.object({
     passwordSelector: z.string().min(1),
     submitSelector: z.string().min(1),
 });
-async function loadConfigFile(relativePath) {
+/**
+ * Load a harness config from a file path.
+ *
+ * When `explicit` is false (the user did not pass --config) and the file does
+ * not exist, this returns DEFAULT_HARNESS_CONFIG silently rather than crashing.
+ * An explicit --config that points at a missing file is always a hard error.
+ */
+async function loadConfigFile(relativePath, explicit) {
     const configPath = resolve(process.cwd(), relativePath);
-    const configModule = await import(pathToFileURL(configPath).href);
+    // Implicit default + file absent → use built-in fallback, no crash.
+    if (!explicit) {
+        const { existsSync } = await import('node:fs');
+        if (!existsSync(configPath)) {
+            console.error('[qulib] No qulib.config.ts found in the working directory; using built-in default config. ' +
+                'Pass --config <file> to supply your own.');
+            return DEFAULT_HARNESS_CONFIG;
+        }
+    }
+    const href = pathToFileURL(configPath).href;
+    let configModule;
+    try {
+        configModule = await import(href);
+    }
+    catch (err) {
+        // Plain node (the published CLI) cannot import a .ts config directly.
+        if (!configPath.endsWith('.ts') ||
+            err.code !== 'ERR_UNKNOWN_FILE_EXTENSION') {
+            throw err;
+        }
+        configModule = await importTsConfigViaTsx(configPath, href);
+    }
     return HarnessConfigSchema.parse(configModule.default);
 }
+async function importTsConfigViaTsx(configPath, href) {
+    let tsImport;
+    try {
+        ({ tsImport } = await import('tsx/esm/api'));
+    }
+    catch {
+        throw new Error(`"${configPath}" is a TypeScript config, which this Node runtime cannot import directly. ` +
+            'Install tsx (npm i -D tsx) or point --config at a .js or .mjs config file.');
+    }
+    return tsImport(href, import.meta.url);
+}
 function redactConfigForLog(config) {
     const base = { ...config };
     if (config.auth?.type === 'form-login') {
@@ -86,7 +153,10 @@ async function runAnalyze(options) {
     }
     const validatedUrl = AnalyzeUrlSchema.parse(options.url);
     const mode = options.repo ? 'url-repo' : 'url-only';
-    const baseConfig = await loadConfigFile(options.configFile ?? 'qulib.config.ts');
+    // configFile is undefined when --config was not explicitly passed (Commander
+    // no longer sets a default on the flag so we can distinguish the two cases).
+    const configFileExplicit = options.configFile !== undefined;
+    const baseConfig = await loadConfigFile(options.configFile ?? 'qulib.config.ts', configFileExplicit);
     const config = mergeAuthFromCli(baseConfig, options);
     const ephemeral = options.ephemeral ?? false;
     const agentSummary = options.agentSummary ?? false;
@@ -131,6 +201,12 @@ program
     .name('qulib')
     .description('Qulib — QA harness')
     .version(pkg.version);
+// Q2 (CLIs + evals): each new CLI surface owns its own file and self-registers
+// here, so the scaffold and score-automation commands never edit index.ts
+// concurrently. Implemented in scaffold-run.ts / score-automation-run.ts.
+registerScaffoldCommand(program);
+registerScoreAutomationCommand(program);
+registerConfidenceCommand(program);
 program
     .command('clean')
     .description('Remove all generated reports and scan state')
@@ -167,7 +243,7 @@ program
     .requiredOption('--url <url>', 'Base URL of the app to analyze')
     .option('--repo <path>', 'Path to the app repo')
     .option('--prd <path>', 'Path to a PRD markdown file')
-    .option('--config <file>', 'Path to config file (relative to cwd)', 'qulib.config.ts')
+    .option('--config <file>', 'Path to config file (relative to cwd; defaults to qulib.config.ts if present, otherwise built-in defaults are used)')
     .option('--adapter <type>', 'Override default test adapter (playwright, cypress-e2e, cypress-component, api)', 'playwright')
     .option('--ephemeral', 'Do not write to disk — return full report as JSON on stdout (use for MCP/CI)', false)
     .option('--agent-summary', 'Do not write to disk — return the compact agent-summary gate JSON on stdout (pass/warn/fail with honesty notes). Mutually exclusive with --ephemeral.', false)