@qulib/core 0.7.0 → 0.9.0

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)

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

@@ -0,0 +1,86 @@
+/**
+ * `qulib scaffold` — Q2 (scaffold-cli subtask).
+ *
+ * Wraps `scaffoldTests(url, options)` from ../scaffold-tests.js as a first-class
+ * CLI surface (scaffold was previously only reachable programmatically / via MCP).
+ *
+ * This file owns the `scaffold` subcommand end-to-end and is registered from
+ * cli/index.ts via `registerScaffoldCommand(program)` so this build agent never
+ * edits index.ts itself (avoids collision with score-automation). It mirrors the
+ * dynamic-import command style used by `cost` and the output-mode conventions of
+ * `analyze` (write-to-disk by default, `--json` for a stdout-only run).
+ *
+ * Output modes (one stdout shape, mutually exclusive with disk writes):
+ *   default            → write projectConfig + generated specs under --out (./qulib-scaffold)
+ *   --json             → no disk writes; print the full ScaffoldResult-shaped JSON on stdout
+ *
+ * Honesty rules (root design principle: never emit false confidence):
+ *   - If analyze produced ZERO scenarios, we do NOT write an empty-but-confident
+ *     scaffold. Write mode exits non-zero with a clear message; --json emits an
+ *     explicit `{ empty: true, ... }` payload so a caller/agent can branch on it.
+ *   - `--framework playwright` currently maps to a not-implemented adapter
+ *     (PlaywrightAdapter.renderAll throws). Rather than surfacing a raw stack, we
+ *     translate it into an actionable error pointing at the supported framework.
+ */
+import type { Command } from 'commander';
+import { type ScaffoldResult } from '../scaffold-tests.js';
+import type { SpecValidationReport } from '../adapters/validate-specs.js';
+import { type RecipeId } from '../schemas/recipe.schema.js';
+/** Frameworks `scaffoldTests` accepts. Mirrors its `ScaffoldOptions['framework']`. */
+declare const FRAMEWORKS: readonly ["cypress-e2e", "playwright"];
+type ScaffoldFramework = (typeof FRAMEWORKS)[number];
+/** A single file the scaffold wants on disk, with its repo-relative path. */
+interface ScaffoldFile {
+    /** Path relative to the --out root. */
+    relativePath: string;
+    contents: string;
+}
+interface ScaffoldRunOptions {
+    url: string;
+    framework: ScaffoldFramework;
+    maxPages?: number;
+    out: string;
+    json: boolean;
+    recipes?: RecipeId[];
+    /**
+     * When true, fail the command (non-zero exit) if any generated spec does not
+     * parse/compile. The dry-run validation always runs; this flag controls
+     * whether a validation failure is fatal vs merely reported.
+     */
+    validateSpecs?: boolean;
+}
+/**
+ * Raised when `--validate-specs` is set and at least one generated spec fails
+ * the dry-run. Carries a non-zero `exitCode` so the CLI surfaces a hard failure
+ * instead of writing a known-broken scaffold and exiting green.
+ */
+export declare class SpecValidationError extends Error {
+    readonly exitCode = 1;
+    constructor(message: string);
+}
+/**
+ * Flatten a ScaffoldResult into the concrete files a scaffold project needs:
+ * the framework config file, any support files, and one spec per generated test
+ * (each at its own `outputPath`, which the adapter already namespaces e.g.
+ * `cypress/e2e/<slug>.cy.ts`). Pure + side-effect-free so tests can assert on it.
+ */
+export declare function collectScaffoldFiles(result: ScaffoldResult): ScaffoldFile[];
+/**
+ * Apply the dry-run validation gate.
+ *
+ * Pure + side-effect-free (returns the warning text instead of logging) so it
+ * is unit-testable in isolation: feed it an `ok: false` report and assert it
+ * throws; feed it an `ok: true` report and assert it returns null. This is the
+ * discrimination witness for the fatal path — `runScaffold` cannot produce a
+ * broken spec on demand (the adapters always render valid code), so the gate's
+ * reject-vs-pass behavior is proven here directly against a report.
+ *
+ * @returns a non-null warning string when validation failed but `validateSpecs`
+ *   was not set (caller should log it); null when all specs parsed.
+ * @throws SpecValidationError when validation failed AND `validateSpecs` is set.
+ */
+export declare function enforceSpecValidation(validation: SpecValidationReport, validateSpecs: boolean): string | null;
+export declare function runScaffold(options: ScaffoldRunOptions): Promise<void>;
+export declare function registerScaffoldCommand(program: Command): void;
+export {};
+//# sourceMappingURL=scaffold-run.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-run.d.ts","sourceRoot":"","sources":["../../src/cli/scaffold-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAI5E,sFAAsF;AACtF,QAAA,MAAM,UAAU,wCAAyC,CAAC;AAC1D,KAAK,iBAAiB,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAKrD,6EAA6E;AAC7E,UAAU,YAAY;IACpB,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,kBAAkB;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,iBAAiB,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,KAAK;gBACV,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,EAAE,CAgC3E;AAOD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,oBAAoB,EAChC,aAAa,EAAE,OAAO,GACrB,MAAM,GAAG,IAAI,CAef;AA+BD,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiG5E;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkE9D"}

package/dist/cli/scaffold-run.js

@@ -0,0 +1,232 @@
+import { z } from 'zod';
+import { scaffoldTests } from '../scaffold-tests.js';
+import { RecipeIdSchema } from '../schemas/recipe.schema.js';
+const ScaffoldUrlSchema = z.string().url();
+/** Frameworks `scaffoldTests` accepts. Mirrors its `ScaffoldOptions['framework']`. */
+const FRAMEWORKS = ['cypress-e2e', 'playwright'];
+const FrameworkSchema = z.enum(FRAMEWORKS);
+const DEFAULT_OUT_DIR = 'qulib-scaffold';
+/**
+ * Raised when `--validate-specs` is set and at least one generated spec fails
+ * the dry-run. Carries a non-zero `exitCode` so the CLI surfaces a hard failure
+ * instead of writing a known-broken scaffold and exiting green.
+ */
+export class SpecValidationError extends Error {
+    exitCode = 1;
+    constructor(message) {
+        super(message);
+        this.name = 'SpecValidationError';
+    }
+}
+/**
+ * Flatten a ScaffoldResult into the concrete files a scaffold project needs:
+ * the framework config file, any support files, and one spec per generated test
+ * (each at its own `outputPath`, which the adapter already namespaces e.g.
+ * `cypress/e2e/<slug>.cy.ts`). Pure + side-effect-free so tests can assert on it.
+ */
+export function collectScaffoldFiles(result) {
+    const files = [];
+    const { projectConfig, generatedTests } = result;
+    files.push({
+        relativePath: projectConfig.configFile.filename,
+        contents: projectConfig.configFile.code,
+    });
+    for (const support of projectConfig.supportFiles) {
+        files.push({ relativePath: support.filename, contents: support.code });
+    }
+    for (const spec of generatedTests) {
+        files.push({ relativePath: spec.outputPath, contents: spec.code });
+    }
+    // A package.json fragment is informational (devDeps + scripts) — surface it as
+    // a file so the scaffold is runnable without the caller re-deriving it.
+    files.push({
+        relativePath: 'package.json',
+        contents: JSON.stringify({
+            name: 'qulib-scaffolded-suite',
+            private: true,
+            scripts: projectConfig.packageJson.scripts,
+            devDependencies: projectConfig.packageJson.devDependencies,
+        }, null, 2) + '\n',
+    });
+    return files;
+}
+/** True when scaffold produced nothing actionable (no scenarios → no specs). */
+function isEmptyScaffold(result) {
+    return result.scenarios.length === 0 || result.generatedTests.length === 0;
+}
+/**
+ * Apply the dry-run validation gate.
+ *
+ * Pure + side-effect-free (returns the warning text instead of logging) so it
+ * is unit-testable in isolation: feed it an `ok: false` report and assert it
+ * throws; feed it an `ok: true` report and assert it returns null. This is the
+ * discrimination witness for the fatal path — `runScaffold` cannot produce a
+ * broken spec on demand (the adapters always render valid code), so the gate's
+ * reject-vs-pass behavior is proven here directly against a report.
+ *
+ * @returns a non-null warning string when validation failed but `validateSpecs`
+ *   was not set (caller should log it); null when all specs parsed.
+ * @throws SpecValidationError when validation failed AND `validateSpecs` is set.
+ */
+export function enforceSpecValidation(validation, validateSpecs) {
+    if (validation.ok)
+        return null;
+    const failed = validation.results.filter((r) => !r.valid);
+    const detail = failed
+        .map((r) => `  ✗ ${r.outputPath}\n      ${r.errors.join('\n      ')}`)
+        .join('\n');
+    const summary = `${validation.invalidCount} of ${validation.total} generated spec(s) failed dry-run validation ` +
+        `(they do not parse/compile):\n${detail}`;
+    if (validateSpecs) {
+        throw new SpecValidationError(summary);
+    }
+    return summary;
+}
+/**
+ * Translate the known not-implemented-adapter failure into an actionable message.
+ * Re-throws anything else unchanged so real failures stay loud.
+ */
+function rethrowScaffoldError(error, framework) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/not implemented/i.test(message)) {
+        throw new Error(`The "${framework}" test adapter is not implemented yet, so qulib cannot render specs for it. ` +
+            `Re-run with --framework cypress-e2e (the supported scaffolder) until the ${framework} adapter ships.`);
+    }
+    throw error instanceof Error ? error : new Error(message);
+}
+async function writeScaffoldToDisk(files, outDir) {
+    const fs = await import('node:fs/promises');
+    const path = await import('node:path');
+    const outRoot = path.resolve(process.cwd(), outDir);
+    const written = [];
+    for (const file of files) {
+        const dest = path.join(outRoot, file.relativePath);
+        await fs.mkdir(path.dirname(dest), { recursive: true });
+        await fs.writeFile(dest, file.contents, 'utf8');
+        written.push(dest);
+    }
+    return written;
+}
+export async function runScaffold(options) {
+    const url = ScaffoldUrlSchema.parse(options.url);
+    const framework = FrameworkSchema.parse(options.framework);
+    if (options.json) {
+        console.error('[qulib] Scaffold JSON mode: no disk writes; full result JSON on stdout');
+    }
+    else {
+        console.error(`[qulib] Scaffolding ${framework} tests for ${url}`);
+        console.error('[qulib] Analyzing the deployed surface to derive scenarios — this may take a moment...');
+    }
+    let result;
+    try {
+        result = await scaffoldTests(url, {
+            framework,
+            ...(options.maxPages !== undefined && { maxPagesToScan: options.maxPages }),
+            ...(options.recipes && options.recipes.length > 0 && { recipes: options.recipes }),
+        });
+    }
+    catch (error) {
+        rethrowScaffoldError(error, framework);
+    }
+    // Honest empty handling — no false-confidence scaffolds.
+    if (isEmptyScaffold(result)) {
+        if (options.json) {
+            console.log(JSON.stringify({
+                url: result.url,
+                framework: result.framework,
+                empty: true,
+                scenarioCount: 0,
+                generatedTestCount: 0,
+                note: 'Analysis surfaced no scenarios for this URL, so no tests were generated. ' +
+                    'This is honest output, not a failure: there was nothing concrete to scaffold. ' +
+                    'Try a different URL, raise --max-pages, or provide authenticated access if the app is behind a login.',
+            }, null, 2));
+            return;
+        }
+        throw new Error('No scenarios were derived for this URL, so qulib generated no tests. ' +
+            'Refusing to write an empty scaffold (no false confidence). ' +
+            'Try a different URL, raise --max-pages, or supply auth if the app is behind a login.');
+    }
+    // Dry-run gate: the scaffold already validated every generated spec through
+    // the TS compiler. Surface a failure here so a broken generator output never
+    // silently lands on disk. With --validate-specs this is fatal (non-zero exit
+    // via SpecValidationError); without it we still warn so the signal is never
+    // hidden. The gate logic lives in enforceSpecValidation (unit-tested).
+    const validation = result.specValidation;
+    const warning = enforceSpecValidation(validation, Boolean(options.validateSpecs));
+    if (warning) {
+        console.error(`[qulib] WARNING — ${warning}`);
+        console.error('[qulib] Re-run with --validate-specs to make this a hard (non-zero) failure.');
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            url: result.url,
+            framework: result.framework,
+            empty: false,
+            scenarioCount: result.scenarios.length,
+            generatedTestCount: result.generatedTests.length,
+            scenarios: result.scenarios,
+            generatedTests: result.generatedTests,
+            projectConfig: result.projectConfig,
+            specValidation: result.specValidation,
+        }, null, 2));
+        return;
+    }
+    const files = collectScaffoldFiles(result);
+    const written = await writeScaffoldToDisk(files, options.out);
+    const path = await import('node:path');
+    const outRoot = path.resolve(process.cwd(), options.out);
+    console.error(`\n[qulib] Scaffold complete — ${framework}`);
+    console.error(`  Scenarios derived:   ${result.scenarios.length}`);
+    console.error(`  Specs generated:     ${result.generatedTests.length}`);
+    console.error(`  Specs validated:     ${validation.total - validation.invalidCount}/${validation.total} parse cleanly`);
+    console.error(`  Files written:       ${written.length}`);
+    console.error(`  Output directory:    ${outRoot}`);
+    console.error(`  Config:              ${result.projectConfig.configFile.filename}`);
+    console.error('\n[qulib] Next: cd into the output dir, `npm install`, then run the test script.');
+}
+export function registerScaffoldCommand(program) {
+    program
+        .command('scaffold')
+        .description('Generate a runnable test suite (config + specs) for a deployed app by analyzing its surface')
+        .requiredOption('--url <url>', 'Base URL of the app to scaffold tests for')
+        .option('--framework <framework>', `Test framework: ${FRAMEWORKS.join(' | ')}`, 'cypress-e2e')
+        .option('--max-pages <n>', 'Maximum number of pages to scan while deriving scenarios')
+        .option('--out <dir>', 'Directory to write the scaffolded project into', DEFAULT_OUT_DIR)
+        .option('--json', 'Do not write to disk — print the full scaffold result as JSON on stdout (use for MCP/CI)', false)
+        .option('--recipes <ids>', 'Comma-separated recipe ids to append proven test patterns: auth,a11y,nav,seed (e.g. --recipes auth,a11y)')
+        .option('--validate-specs', 'Fail (non-zero exit) if any generated spec does not parse/compile. Validation always runs; this makes a failure fatal.', false)
+        .action(async (options) => {
+        const parsedFramework = FrameworkSchema.safeParse(options.framework);
+        if (!parsedFramework.success) {
+            throw new Error(`Invalid --framework "${options.framework}". Supported: ${FRAMEWORKS.join(', ')}.`);
+        }
+        let maxPages;
+        if (options.maxPages !== undefined) {
+            const n = Number(options.maxPages);
+            if (!Number.isInteger(n) || n <= 0) {
+                throw new Error(`--max-pages must be a positive integer, got "${options.maxPages}".`);
+            }
+            maxPages = n;
+        }
+        let recipes;
+        if (options.recipes) {
+            const ids = options.recipes.split(',').map((s) => s.trim()).filter(Boolean);
+            const parsed = ids.map((id) => RecipeIdSchema.safeParse(id));
+            const invalid = parsed.map((p, i) => (!p.success ? ids[i] : null)).filter(Boolean);
+            if (invalid.length > 0) {
+                throw new Error(`Invalid --recipes value(s): ${invalid.join(', ')}. Supported: auth, a11y, nav, seed.`);
+            }
+            recipes = parsed.map((p) => (p.success ? p.data : null)).filter(Boolean);
+        }
+        await runScaffold({
+            url: options.url,
+            framework: parsedFramework.data,
+            maxPages,
+            out: options.out,
+            json: Boolean(options.json),
+            recipes,
+            validateSpecs: Boolean(options.validateSpecs),
+        });
+    });
+}

package/dist/cli/score-automation-run.d.ts

@@ -0,0 +1,25 @@
+import type { Command } from 'commander';
+import type { AutomationMaturity } from '../schemas/automation-maturity.schema.js';
+export interface ScoreAutomationOptions {
+    /** Path to the local repo to score (required). */
+    repo: string;
+    /** Emit the full AutomationMaturity object as JSON to stdout instead of the human report. */
+    json?: boolean;
+}
+/**
+ * Resolve `--repo` to an absolute path and assert it is an existing directory.
+ * Fails fast with a clear, actionable message rather than letting glob silently
+ * scan nothing and report a falsely-confident "everything is uncovered" score.
+ */
+export declare function resolveRepoPath(repoOption: string | undefined, cwd?: string): string;
+/** Build the human-readable report as a single string (kept pure so tests can assert on it). */
+export declare function formatHumanReport(maturity: AutomationMaturity): string;
+/**
+ * Core of the command, factored out of the action handler so node:test can drive it
+ * directly against a fixture repo without spawning a process.
+ *
+ * Reuses scanRepo (static repo intelligence) then computes maturity explicitly.
+ */
+export declare function runScoreAutomation(options: ScoreAutomationOptions, out?: (line: string) => void): Promise<AutomationMaturity>;
+export declare function registerScoreAutomationCommand(program: Command): void;
+//# sourceMappingURL=score-automation-run.d.ts.map

package/dist/cli/score-automation-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-automation-run.d.ts","sourceRoot":"","sources":["../../src/cli/score-automation-run.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EACV,kBAAkB,EAEnB,MAAM,0CAA0C,CAAC;AAIlD,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CAYnG;AA+BD,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAiBtE;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,sBAAsB,EAC/B,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkC,GACxD,OAAO,CAAC,kBAAkB,CAAC,CAW7B;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAWrE"}