@qulib/core 0.8.2 → 0.10.0

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

@@ -0,0 +1,55 @@
+import type { Command } from 'commander';
+import type { BaselineSnapshot, BaselineDelta } from '../baseline/baseline.schema.js';
+import { type GapAnalysis } from '../schemas/gap-analysis.schema.js';
+/**
+ * Read and validate a GapAnalysis from a report.json written by `qulib analyze`.
+ * report.json is exactly a serialized GapAnalysis (see reporters/json-reporter.ts),
+ * so we parse it through GapAnalysisSchema — fail loudly on a malformed/foreign file
+ * rather than baselining garbage.
+ */
+export declare function loadGapAnalysisFromReport(reportPath: string, cwd?: string): Promise<GapAnalysis>;
+export interface BaselineSaveOptions {
+    url: string;
+    fromReport?: string;
+    label?: string;
+    dir?: string;
+    json?: boolean;
+}
+/** Render a saved snapshot as a short human line. */
+export declare function formatSavedSnapshot(snap: BaselineSnapshot): string;
+/**
+ * Core of `baseline save`, factored out so node:test can drive it without a process.
+ * Either --from-report (deterministic, reads a real on-disk report.json) or a live
+ * crawl of --url. --from-report is preferred for CI/agents that already ran analyze.
+ */
+export declare function runBaselineSave(options: BaselineSaveOptions, out?: (line: string) => void): Promise<BaselineSnapshot>;
+export interface BaselineListOptions {
+    url: string;
+    dir?: string;
+    json?: boolean;
+}
+/** Render a list of snapshots as a human table. */
+export declare function formatBaselineList(url: string, snaps: BaselineSnapshot[]): string;
+/** Core of `baseline list`, factored out for direct testing. */
+export declare function runBaselineList(options: BaselineListOptions, out?: (line: string) => void): Promise<BaselineSnapshot[]>;
+export interface BaselineCompareOptions {
+    /** Compare two explicit baseline ids. Takes precedence over --url. */
+    from?: string;
+    to?: string;
+    /** Or: compare the two most-recent baselines for this URL. */
+    url?: string;
+    dir?: string;
+    json?: boolean;
+}
+/** Render a delta as a human report. */
+export declare function formatBaselineDelta(delta: BaselineDelta): string;
+/**
+ * Core of `baseline compare`, factored out for direct testing.
+ * Resolution order:
+ *   1. --from and --to explicit ids → load both, compare.
+ *   2. --url → take the two most-recent baselines (prior = older, current = newest).
+ * Fails clearly when fewer than two baselines are available — never invents a delta.
+ */
+export declare function runBaselineCompare(options: BaselineCompareOptions, out?: (line: string) => void): Promise<BaselineDelta>;
+export declare function registerBaselineCommand(program: Command): void;
+//# sourceMappingURL=baseline-run.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"baseline-run.d.ts","sourceRoot":"","sources":["../../src/cli/baseline-run.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACtF,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,mCAAmC,CAAC;AA0BxF;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAsBtB;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,qDAAqD;AACrD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAQlE;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,EAC5B,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkC,GACxD,OAAO,CAAC,gBAAgB,CAAC,CA6B3B;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,mDAAmD;AACnD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAUjF;AAED,gEAAgE;AAChE,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,EAC5B,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkC,GACxD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAW7B;AAED,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wCAAwC;AACxC,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAiBhE;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,sBAAsB,EAC/B,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkC,GACxD,OAAO,CAAC,aAAa,CAAC,CAmCxB;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwD9D"}

package/dist/cli/baseline-run.js

@@ -0,0 +1,259 @@
+/**
+ * `qulib baseline` — capture and compare quality-gap baselines over time.
+ *
+ * Surfaces the previously dead-ended baseline module (../baseline/baseline.js) as a
+ * first-class CLI. Until now save/load/list/compare existed only as a programmatic API
+ * with no consumer; this exposes them so an agent or CI can snapshot a release's gaps
+ * and detect drift (new / resolved / severity-changed gaps + confidence delta) between
+ * runs.
+ *
+ * Subcommands:
+ *   baseline save     — snapshot a GapAnalysis for a URL. Source the analysis either by
+ *                       crawling live (--url alone) or, deterministically, from an
+ *                       existing report.json written by `qulib analyze` (--from-report).
+ *   baseline list     — list saved baselines for a URL, newest-first.
+ *   baseline compare  — diff two baselines (explicit ids, or the two most-recent for a URL).
+ *
+ * Storage honesty (root design principle — no false confidence):
+ *   Baselines persist under <cwd>/.qulib-baselines/<url-slug>/ unless --dir overrides.
+ *   `compare` with fewer than two baselines fails with a clear, actionable message
+ *   rather than fabricating a delta against nothing.
+ *
+ * This file owns the `baseline` command group end-to-end and is registered from
+ * cli/index.ts via `registerBaselineCommand(program)`, so this command's build never
+ * edits the body of index.ts beyond a single additive registration line (mirrors the
+ * score-automation / scaffold / confidence convention).
+ */
+import { resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { saveBaseline, listBaselines, loadBaseline, compareBaselines, } from '../baseline/baseline.js';
+import { GapAnalysisSchema } from '../schemas/gap-analysis.schema.js';
+import { analyzeApp } from '../analyze.js';
+const UrlSchema = z.string().url();
+/** Harness config used when `save --url` crawls live (no repo, read-only, no LLM). */
+function liveCrawlConfig() {
+    return {
+        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'],
+    };
+}
+/**
+ * Read and validate a GapAnalysis from a report.json written by `qulib analyze`.
+ * report.json is exactly a serialized GapAnalysis (see reporters/json-reporter.ts),
+ * so we parse it through GapAnalysisSchema — fail loudly on a malformed/foreign file
+ * rather than baselining garbage.
+ */
+export async function loadGapAnalysisFromReport(reportPath, cwd = process.cwd()) {
+    const abs = resolve(cwd, reportPath);
+    let raw;
+    try {
+        raw = await readFile(abs, 'utf8');
+    }
+    catch {
+        throw new Error(`--from-report path could not be read: ${abs}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`--from-report file is not valid JSON: ${abs}`);
+    }
+    const result = GapAnalysisSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`--from-report file is not a valid qulib report.json (GapAnalysis): ${abs}\n` +
+            result.error.issues.map((i) => `  • ${i.path.join('.')}: ${i.message}`).join('\n'));
+    }
+    return result.data;
+}
+/** Render a saved snapshot as a short human line. */
+export function formatSavedSnapshot(snap) {
+    const labelTag = snap.label ? ` "${snap.label}"` : '';
+    return (`[qulib] Saved baseline ${snap.id}${labelTag}\n` +
+        `  url: ${snap.url}\n` +
+        `  releaseConfidence: ${snap.releaseConfidence}/100\n` +
+        `  gaps: ${snap.gapCount}`);
+}
+/**
+ * Core of `baseline save`, factored out so node:test can drive it without a process.
+ * Either --from-report (deterministic, reads a real on-disk report.json) or a live
+ * crawl of --url. --from-report is preferred for CI/agents that already ran analyze.
+ */
+export async function runBaselineSave(options, out = (line) => console.log(line)) {
+    const url = UrlSchema.parse(options.url);
+    let analysis;
+    if (options.fromReport && options.fromReport.trim()) {
+        analysis = await loadGapAnalysisFromReport(options.fromReport.trim());
+    }
+    else {
+        if (!options.json) {
+            out(`[qulib] Crawling ${url} to capture a fresh baseline (analyze_app)…`);
+        }
+        const result = await analyzeApp({
+            url,
+            writeArtifacts: false,
+            config: liveCrawlConfig(),
+        });
+        analysis = result.gapAnalysis;
+    }
+    const snapshot = await saveBaseline(analysis, url, {
+        ...(options.dir ? { baseDir: resolve(process.cwd(), options.dir) } : {}),
+        ...(options.label !== undefined ? { label: options.label } : {}),
+    });
+    if (options.json) {
+        out(JSON.stringify(snapshot, null, 2));
+    }
+    else {
+        out(formatSavedSnapshot(snapshot));
+    }
+    return snapshot;
+}
+/** Render a list of snapshots as a human table. */
+export function formatBaselineList(url, snaps) {
+    if (snaps.length === 0) {
+        return `[qulib] No baselines saved for ${url} yet. Run: qulib baseline save --url ${url} --from-report output/report.json`;
+    }
+    const lines = [`[qulib] ${snaps.length} baseline(s) for ${url} (newest first):`];
+    for (const s of snaps) {
+        const labelTag = s.label ? `  "${s.label}"` : '';
+        lines.push(`  ${s.id}  —  confidence ${s.releaseConfidence}/100, ${s.gapCount} gap(s)${labelTag}`);
+    }
+    return lines.join('\n');
+}
+/** Core of `baseline list`, factored out for direct testing. */
+export async function runBaselineList(options, out = (line) => console.log(line)) {
+    const url = UrlSchema.parse(options.url);
+    const snaps = await listBaselines(url, {
+        ...(options.dir ? { baseDir: resolve(process.cwd(), options.dir) } : {}),
+    });
+    if (options.json) {
+        out(JSON.stringify(snaps, null, 2));
+    }
+    else {
+        out(formatBaselineList(url, snaps));
+    }
+    return snaps;
+}
+/** Render a delta as a human report. */
+export function formatBaselineDelta(delta) {
+    const lines = [];
+    lines.push(`[qulib] Baseline comparison`);
+    lines.push(`  from: ${delta.fromId} (${delta.fromReleaseConfidence}/100)`);
+    lines.push(`  to:   ${delta.toId} (${delta.toReleaseConfidence}/100)`);
+    lines.push(`  ${delta.summary}`);
+    const section = (title, items) => {
+        if (items.length === 0)
+            return;
+        lines.push(`  ${title}:`);
+        for (const g of items) {
+            lines.push(`    • [${g.severity}] ${g.path} (${g.category}) — ${g.reason}`);
+        }
+    };
+    section('new gaps', delta.newGaps);
+    section('resolved gaps', delta.resolvedGaps);
+    section('severity changes', delta.severityChanges);
+    return lines.join('\n');
+}
+/**
+ * Core of `baseline compare`, factored out for direct testing.
+ * Resolution order:
+ *   1. --from and --to explicit ids → load both, compare.
+ *   2. --url → take the two most-recent baselines (prior = older, current = newest).
+ * Fails clearly when fewer than two baselines are available — never invents a delta.
+ */
+export async function runBaselineCompare(options, out = (line) => console.log(line)) {
+    const baseDirOpt = options.dir ? { baseDir: resolve(process.cwd(), options.dir) } : {};
+    let prior;
+    let current;
+    if (options.from || options.to) {
+        if (!options.from || !options.to) {
+            throw new Error('baseline compare with explicit ids requires BOTH --from and --to.');
+        }
+        prior = await loadBaseline(options.from, baseDirOpt);
+        current = await loadBaseline(options.to, baseDirOpt);
+    }
+    else if (options.url) {
+        const url = UrlSchema.parse(options.url);
+        const snaps = await listBaselines(url, baseDirOpt);
+        if (snaps.length < 2) {
+            throw new Error(`baseline compare needs at least two saved baselines for ${url}; found ${snaps.length}. ` +
+                `Save another with: qulib baseline save --url ${url} --from-report output/report.json`);
+        }
+        // listBaselines is newest-first: snaps[0] is current, snaps[1] is the prior.
+        current = snaps[0];
+        prior = snaps[1];
+    }
+    else {
+        throw new Error('baseline compare requires either --from + --to, or --url.');
+    }
+    const delta = compareBaselines(prior, current);
+    if (options.json) {
+        out(JSON.stringify(delta, null, 2));
+    }
+    else {
+        out(formatBaselineDelta(delta));
+    }
+    return delta;
+}
+export function registerBaselineCommand(program) {
+    const baseline = program
+        .command('baseline')
+        .description('Capture and compare quality-gap baselines over time. Snapshot a release\'s gaps, ' +
+        'then diff later runs to surface new / resolved / severity-changed gaps and confidence drift.');
+    baseline
+        .command('save')
+        .description('Save a baseline snapshot for a URL (from a report.json or a fresh live crawl)')
+        .requiredOption('--url <url>', 'URL the baseline is keyed to')
+        .option('--from-report <path>', 'Path to a report.json from `qulib analyze` (deterministic, no network). If omitted, the URL is crawled live.')
+        .option('--label <label>', 'Optional human label for this snapshot, e.g. before-refactor')
+        .option('--dir <path>', 'Baseline storage root (default: <cwd>/.qulib-baselines)')
+        .option('--json', 'Emit the saved BaselineSnapshot as JSON to stdout', false)
+        .action(async (options) => {
+        await runBaselineSave({
+            url: options.url,
+            fromReport: options.fromReport,
+            label: options.label,
+            dir: options.dir,
+            json: Boolean(options.json),
+        });
+    });
+    baseline
+        .command('list')
+        .description('List saved baselines for a URL, newest first')
+        .requiredOption('--url <url>', 'URL whose baselines to list')
+        .option('--dir <path>', 'Baseline storage root (default: <cwd>/.qulib-baselines)')
+        .option('--json', 'Emit the BaselineSnapshot[] as JSON to stdout', false)
+        .action(async (options) => {
+        await runBaselineList({ url: options.url, dir: options.dir, json: Boolean(options.json) });
+    });
+    baseline
+        .command('compare')
+        .description('Compare two baselines — pass --from and --to ids, or --url for the two most-recent')
+        .option('--from <id>', 'Prior baseline id')
+        .option('--to <id>', 'Current baseline id')
+        .option('--url <url>', 'Compare the two most-recent baselines for this URL')
+        .option('--dir <path>', 'Baseline storage root (default: <cwd>/.qulib-baselines)')
+        .option('--json', 'Emit the full BaselineDelta as JSON to stdout', false)
+        .action(async (options) => {
+        await runBaselineCompare({
+            from: options.from,
+            to: options.to,
+            url: options.url,
+            dir: options.dir,
+            json: Boolean(options.json),
+        });
+    });
+}

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,CAuBhE"}

package/dist/cli/confidence-run.js

@@ -0,0 +1,162 @@
+/**
+ * `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) {
+    // Canonical flagship command. Alias: release-confidence (for integrations that prefer the
+    // full concept name over the short form). Both names are kept through 1.0.
+    program
+        .command('confidence')
+        .alias('release-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. ' +
+        '(Alias: release-confidence)')
+        .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,42 @@ 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';
+import { registerBaselineCommand } from './baseline-run.js';
+import { registerAnalyzeDiffCommand } from './analyze-diff-run.js';
 const program = new Command();
 const AnalyzeUrlSchema = z.string().url();
 const FormLoginCliSchema = z.object({
@@ -23,11 +53,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 +155,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 +203,14 @@ 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);
+registerBaselineCommand(program);
+registerAnalyzeDiffCommand(program);
 program
     .command('clean')
     .description('Remove all generated reports and scan state')
@@ -167,7 +247,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)