@qa-ai-stlc/core 0.0.0

package/README.md

@@ -0,0 +1,13 @@
+# @qa-ai-stlc/core
+
+The deterministic engine underneath the `qa` CLI and the MCP server. This package owns the
+`.qa/` store: reading and validating `config.yaml`, hashing every registered artifact into
+`manifest.json`, and normalizing project-relative paths so a hash or a reference recorded on one
+OS still resolves on another.
+
+Filesystem access, wall-clock time and logging are injected through small ports (`FileSystem`,
+`Clock`, `Logger`) rather than called directly, so the engine's logic is testable without real
+I/O and so hosts (CLI, MCP server, tests) can supply their own implementations.
+
+Part of [QA-AI-STLC](https://github.com/Klim-101/QA-AI-STLC). See the repository root for
+license, contributing and security information.

package/dist/auth-session-store.d.ts

@@ -0,0 +1,15 @@
+import type { StorageState } from './ports/browser-launcher.js';
+import type { QaStore } from './qa-store.js';
+/**
+ * Persists `storageState` per identity under `.qa/auth/`, outside the manifest and evidence: it
+ * holds live session cookies and tokens, which must never be treated as a registered, hashed
+ * artifact or shared the way evidence is (AGENTS.md 5.8, development plan section 6.4).
+ */
+export declare class AuthSessionStore {
+    private readonly store;
+    constructor(store: QaStore);
+    private pathFor;
+    save(identityName: string, storageState: StorageState): Promise<void>;
+    load(identityName: string): Promise<StorageState | undefined>;
+}
+//# sourceMappingURL=auth-session-store.d.ts.map

package/dist/auth-session-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-session-store.d.ts","sourceRoot":"","sources":["../src/auth-session-store.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAS7C;;;;GAIG;AACH,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,OAAO;IAE3C,OAAO,CAAC,OAAO;IAIT,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;CAOpE"}

package/dist/auth-session-store.js

@@ -0,0 +1,34 @@
+// Copyright The QA-AI-STLC Authors
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+// Playwright's own storageState shape has no published Zod schema to import; this is a loose
+// structural check, not a full re-validation of every field.
+const StorageStateSchema = z.object({
+    cookies: z.array(z.record(z.string(), z.unknown())),
+    origins: z.array(z.record(z.string(), z.unknown())),
+});
+/**
+ * Persists `storageState` per identity under `.qa/auth/`, outside the manifest and evidence: it
+ * holds live session cookies and tokens, which must never be treated as a registered, hashed
+ * artifact or shared the way evidence is (AGENTS.md 5.8, development plan section 6.4).
+ */
+export class AuthSessionStore {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    pathFor(identityName) {
+        return `auth/${identityName}.json`;
+    }
+    async save(identityName, storageState) {
+        await this.store.writeJson(this.pathFor(identityName), storageState);
+    }
+    async load(identityName) {
+        const relativePath = this.pathFor(identityName);
+        if (!(await this.store.pathExists(relativePath))) {
+            return undefined;
+        }
+        return this.store.readJson(relativePath, StorageStateSchema);
+    }
+}
+//# sourceMappingURL=auth-session-store.js.map

package/dist/auth-session-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-session-store.js","sourceRoot":"","sources":["../src/auth-session-store.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,sCAAsC;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,6FAA6F;AAC7F,6DAA6D;AAC7D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IACnD,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;CACpD,CAAuC,CAAC;AAEzC;;;;GAIG;AACH,MAAM,OAAO,gBAAgB;IACE;IAA7B,YAA6B,KAAc;QAAd,UAAK,GAAL,KAAK,CAAS;IAAG,CAAC;IAEvC,OAAO,CAAC,YAAoB;QAClC,OAAO,QAAQ,YAAY,OAAO,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,YAAoB,EAAE,YAA0B;QACzD,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC,CAAC;IACvE,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,YAAoB;QAC7B,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAChD,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;YACjD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/auth.d.ts

@@ -0,0 +1,28 @@
+import type { IdentityConfig } from '@qa-ai-stlc/schemas';
+import type { BrowserLauncher, StorageState } from './ports/browser-launcher.js';
+/**
+ * Attaches to a browser the operator has already signed into (`connectOverCDP`), covering SSO,
+ * MFA and custom redirects the framework never has to reproduce. Never closes the attached
+ * browser: it belongs to the operator, not the engine.
+ */
+export declare function attachViaCdp(launcher: BrowserLauncher, endpointUrl: string): Promise<StorageState>;
+export interface LoginCredentials {
+    readonly loginUrl: string;
+    readonly username: string;
+    readonly password: string;
+    readonly usernameSelector?: string;
+    readonly passwordSelector?: string;
+    readonly submitSelector?: string;
+}
+/** Scripted login with secrets from environment variables (development plan section 6.2 step 2). */
+export declare function loginWithCredentials(launcher: BrowserLauncher, credentials: LoginCredentials): Promise<StorageState>;
+export interface AuthenticateOptions {
+    /** Required, and only used, when `identity.auth` is `"cdp-attach"`. */
+    readonly cdpEndpointUrl?: string;
+}
+/**
+ * Produces a reusable session for one configured identity, dispatching to the CDP-attach or
+ * scripted-login path per `identity.auth` (development plan section 6.2).
+ */
+export declare function authenticate(launcher: BrowserLauncher, identity: IdentityConfig, env: Readonly<Record<string, string | undefined>>, options?: AuthenticateOptions): Promise<StorageState>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAe,eAAe,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAS9F;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAUxG;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,oGAAoG;AACpG,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,eAAe,EACzB,WAAW,EAAE,gBAAgB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAcvB;AAED,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,cAAc,EACxB,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EACjD,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,YAAY,CAAC,CAoCvB"}

package/dist/auth.js

@@ -0,0 +1,77 @@
+// Copyright The QA-AI-STLC Authors
+// SPDX-License-Identifier: Apache-2.0
+import { QaError } from './errors.js';
+// Generic fallbacks for a login form the operator has not described in config.yaml
+// (development plan section 6.2); given only when `identity.selectors` omits one.
+const DEFAULT_USERNAME_SELECTOR = 'input[type="email"], input[name="username"], input[id="username"], input[autocomplete="username"]';
+const DEFAULT_PASSWORD_SELECTOR = 'input[type="password"]';
+const DEFAULT_SUBMIT_SELECTOR = 'button[type="submit"], input[type="submit"]';
+/**
+ * Attaches to a browser the operator has already signed into (`connectOverCDP`), covering SSO,
+ * MFA and custom redirects the framework never has to reproduce. Never closes the attached
+ * browser: it belongs to the operator, not the engine.
+ */
+export async function attachViaCdp(launcher, endpointUrl) {
+    const browser = await launcher.connectOverCdp(endpointUrl);
+    const context = browser.contexts()[0];
+    if (context === undefined) {
+        throw new QaError('CDP_NO_CONTEXT', `No browser context found at "${endpointUrl}"`, {
+            remediation: 'Open at least one tab in the browser started with --remote-debugging-port before attaching.',
+        });
+    }
+    return context.storageState();
+}
+/** Scripted login with secrets from environment variables (development plan section 6.2 step 2). */
+export async function loginWithCredentials(launcher, credentials) {
+    const browser = await launcher.launch();
+    try {
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        await page.goto(credentials.loginUrl);
+        await page.fill(credentials.usernameSelector ?? DEFAULT_USERNAME_SELECTOR, credentials.username);
+        await page.fill(credentials.passwordSelector ?? DEFAULT_PASSWORD_SELECTOR, credentials.password);
+        await page.click(credentials.submitSelector ?? DEFAULT_SUBMIT_SELECTOR);
+        await page.waitForLoadState('networkidle');
+        return await context.storageState();
+    }
+    finally {
+        await browser.close();
+    }
+}
+/**
+ * Produces a reusable session for one configured identity, dispatching to the CDP-attach or
+ * scripted-login path per `identity.auth` (development plan section 6.2).
+ */
+export async function authenticate(launcher, identity, env, options = {}) {
+    if (identity.auth === 'cdp-attach') {
+        if (options.cdpEndpointUrl === undefined) {
+            throw new QaError('CDP_ENDPOINT_MISSING', 'No CDP endpoint URL was given for a "cdp-attach" identity', {
+                remediation: 'Start Chrome with --remote-debugging-port and pass its endpoint URL.',
+            });
+        }
+        return attachViaCdp(launcher, options.cdpEndpointUrl);
+    }
+    const password = env[identity.secret];
+    if (password === undefined || password === '') {
+        throw new QaError('IDENTITY_SECRET_MISSING', `Environment variable "${identity.secret}" is not set`, {
+            remediation: `Set ${identity.secret} before authenticating this identity.`,
+        });
+    }
+    // The schema requires loginUrl and username whenever auth is "storage-state" (packages/schemas
+    // IdentityConfigSchema); a config that reached this point without them is not one qa validate
+    // would have accepted, but the check stays for anyone constructing IdentityConfig by hand.
+    if (identity.loginUrl === undefined || identity.username === undefined) {
+        throw new QaError('LOGIN_CONFIG_INCOMPLETE', 'A "storage-state" identity needs both loginUrl and username', {
+            remediation: 'Set identities.<name>.loginUrl and identities.<name>.username in config.yaml.',
+        });
+    }
+    return loginWithCredentials(launcher, {
+        loginUrl: identity.loginUrl,
+        username: identity.username,
+        password,
+        ...(identity.selectors?.username !== undefined ? { usernameSelector: identity.selectors.username } : {}),
+        ...(identity.selectors?.password !== undefined ? { passwordSelector: identity.selectors.password } : {}),
+        ...(identity.selectors?.submit !== undefined ? { submitSelector: identity.selectors.submit } : {}),
+    });
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/browser-doctor.d.ts

@@ -0,0 +1,29 @@
+import type { IdentityConfig } from '@qa-ai-stlc/schemas';
+import type { FileSystem } from './ports/file-system.js';
+import type { HttpClient } from './ports/http-client.js';
+import type { ProcessRunner } from './ports/process-runner.js';
+export type DoctorCheckStatus = 'pass' | 'fail';
+export interface DoctorCheckResult {
+    readonly name: string;
+    readonly status: DoctorCheckStatus;
+    readonly message: string;
+    readonly remediation?: string;
+}
+export declare const SUPPORTED_BROWSERS: readonly ["chromium", "firefox", "webkit"];
+export type SupportedBrowser = (typeof SUPPORTED_BROWSERS)[number];
+export declare function resolveBrowserExecutablePath(browser: SupportedBrowser): string;
+/** Checks the running Node version against the framework's documented floor (ADR-004). */
+export declare function checkNodeVersion(currentVersion?: string): DoctorCheckResult;
+/** Checks whether a browser Playwright owns (ADR-004) is actually present on disk. */
+export declare function checkBrowserInstalled(fs: FileSystem, browser: SupportedBrowser): Promise<DoctorCheckResult>;
+export interface CheckBaseUrlOptions {
+    readonly httpClient?: HttpClient;
+    readonly timeoutMs?: number;
+}
+/** Checks that the configured environment's base URL responds at all (ADR-004, section 2.7 step 2). */
+export declare function checkBaseUrlReachable(baseUrl: string, options?: CheckBaseUrlOptions): Promise<DoctorCheckResult>;
+/** Checks that every configured identity's secret environment variable is actually set. */
+export declare function checkIdentitiesPresent(identities: Readonly<Record<string, IdentityConfig>>, env: Readonly<Record<string, string | undefined>>): readonly DoctorCheckResult[];
+/** `qa doctor --fix`: installs the given browsers through Playwright's own installer. */
+export declare function installBrowsers(processRunner: ProcessRunner, browsers?: readonly SupportedBrowser[]): Promise<DoctorCheckResult>;
+//# sourceMappingURL=browser-doctor.d.ts.map

package/dist/browser-doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-doctor.d.ts","sourceRoot":"","sources":["../src/browser-doctor.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,eAAO,MAAM,kBAAkB,4CAA6C,CAAC;AAC7E,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAQnE,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAE9E;AA8BD,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,cAAc,GAAE,MAAwB,GAAG,iBAAiB,CAwB5F;AAED,sFAAsF;AACtF,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,UAAU,EACd,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAW5B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,uGAAuG;AACvG,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,iBAAiB,CAAC,CAoB5B;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,EACpD,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAChD,SAAS,iBAAiB,EAAE,CAY9B;AAQD,yFAAyF;AACzF,wBAAsB,eAAe,CACnC,aAAa,EAAE,aAAa,EAC5B,QAAQ,GAAE,SAAS,gBAAgB,EAAuB,GACzD,OAAO,CAAC,iBAAiB,CAAC,CAY5B"}

package/dist/browser-doctor.js

@@ -0,0 +1,130 @@
+// Copyright The QA-AI-STLC Authors
+// SPDX-License-Identifier: Apache-2.0
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { chromium, firefox, webkit } from 'playwright';
+import { fetchHttpClient } from './ports/http-client.js';
+export const SUPPORTED_BROWSERS = ['chromium', 'firefox', 'webkit'];
+const EXECUTABLE_PATH_RESOLVERS = {
+    chromium: () => chromium.executablePath(),
+    firefox: () => firefox.executablePath(),
+    webkit: () => webkit.executablePath(),
+};
+export function resolveBrowserExecutablePath(browser) {
+    return EXECUTABLE_PATH_RESOLVERS[browser]();
+}
+// Keep in sync with the root package.json "engines.node" floor (AGENTS.md 5.1); there is no
+// single runtime source both a packaged CLI and this check can share.
+const MIN_NODE_VERSION = { major: 22, minor: 12, patch: 0 };
+function parseVersion(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version);
+    if (!match?.[1] || !match[2] || !match[3]) {
+        return undefined;
+    }
+    return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+function isAtLeast(version, floor) {
+    if (version.major !== floor.major) {
+        return version.major > floor.major;
+    }
+    if (version.minor !== floor.minor) {
+        return version.minor > floor.minor;
+    }
+    return version.patch >= floor.patch;
+}
+/** Checks the running Node version against the framework's documented floor (ADR-004). */
+export function checkNodeVersion(currentVersion = process.version) {
+    const floorLabel = [MIN_NODE_VERSION.major, MIN_NODE_VERSION.minor, MIN_NODE_VERSION.patch].join('.');
+    const parsed = parseVersion(currentVersion);
+    if (parsed === undefined) {
+        return {
+            name: 'node-version',
+            status: 'fail',
+            message: `Could not parse Node version "${currentVersion}"`,
+            remediation: `Install Node >=${floorLabel}.`,
+        };
+    }
+    if (!isAtLeast(parsed, MIN_NODE_VERSION)) {
+        return {
+            name: 'node-version',
+            status: 'fail',
+            message: `Node ${currentVersion} is older than the required ${floorLabel}`,
+            remediation: `Install Node >=${floorLabel}.`,
+        };
+    }
+    return {
+        name: 'node-version',
+        status: 'pass',
+        message: `Node ${currentVersion} satisfies >=${floorLabel}`,
+    };
+}
+/** Checks whether a browser Playwright owns (ADR-004) is actually present on disk. */
+export async function checkBrowserInstalled(fs, browser) {
+    const executablePath = resolveBrowserExecutablePath(browser);
+    const installed = await fs.pathExists(executablePath);
+    return installed
+        ? { name: `browser:${browser}`, status: 'pass', message: `${browser} is installed` }
+        : {
+            name: `browser:${browser}`,
+            status: 'fail',
+            message: `${browser} is not installed`,
+            remediation: `Run "qa doctor --fix" to install it, or "npx playwright install ${browser}".`,
+        };
+}
+/** Checks that the configured environment's base URL responds at all (ADR-004, section 2.7 step 2). */
+export async function checkBaseUrlReachable(baseUrl, options = {}) {
+    const httpClient = options.httpClient ?? fetchHttpClient;
+    const timeoutMs = options.timeoutMs ?? 5000;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        await httpClient.get(baseUrl, { signal: controller.signal });
+        return { name: 'base-url', status: 'pass', message: `${baseUrl} is reachable` };
+    }
+    catch {
+        return {
+            name: 'base-url',
+            status: 'fail',
+            message: `${baseUrl} is not reachable`,
+            remediation: 'Check the environment is running and the configured baseUrl is correct.',
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/** Checks that every configured identity's secret environment variable is actually set. */
+export function checkIdentitiesPresent(identities, env) {
+    return Object.entries(identities).map(([name, identity]) => {
+        const value = env[identity.secret];
+        return value !== undefined && value !== ''
+            ? { name: `identity:${name}`, status: 'pass', message: `${identity.secret} is set` }
+            : {
+                name: `identity:${name}`,
+                status: 'fail',
+                message: `${identity.secret} is not set`,
+                remediation: `Set the ${identity.secret} environment variable before using identity "${name}".`,
+            };
+    });
+}
+function resolvePlaywrightCliPath() {
+    const require = createRequire(import.meta.url);
+    const packageJsonPath = require.resolve('playwright/package.json');
+    return join(dirname(packageJsonPath), 'cli.js');
+}
+/** `qa doctor --fix`: installs the given browsers through Playwright's own installer. */
+export async function installBrowsers(processRunner, browsers = SUPPORTED_BROWSERS) {
+    const cliPath = resolvePlaywrightCliPath();
+    const result = await processRunner.run(process.execPath, [cliPath, 'install', ...browsers]);
+    return result.exitCode === 0
+        ? { name: 'browser-install', status: 'pass', message: `Installed: ${browsers.join(', ')}` }
+        : {
+            name: 'browser-install',
+            status: 'fail',
+            message: `Installing browsers failed with exit code ${String(result.exitCode)}`,
+            remediation: result.stderr.trim() || 'Run "npx playwright install" manually and check network access.',
+        };
+}
+//# sourceMappingURL=browser-doctor.js.map

package/dist/browser-doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-doctor.js","sourceRoot":"","sources":["../src/browser-doctor.ts"],"names":[],"mappings":"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"}

package/dist/config-loader.d.ts

@@ -0,0 +1,9 @@
+import { type Config } from '@qa-ai-stlc/schemas';
+import type { QaStore } from './qa-store.js';
+/**
+ * Reads and validates `.qa/config.yaml` against `ConfigSchema`, the schema-versioned contract
+ * every other package trusts. Throws `QaError` with a stable `code` and a remediation an agent
+ * or CLI flag can act on, never a bare Zod or YAML parse error (AGENTS.md 5.4).
+ */
+export declare function loadConfig(store: QaStore): Promise<Config>;
+//# sourceMappingURL=config-loader.d.ts.map

package/dist/config-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../src/config-loader.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,MAAM,EAAqB,MAAM,qBAAqB,CAAC;AAGnF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAI7C;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CA+BhE"}

package/dist/config-loader.js

@@ -0,0 +1,40 @@
+// Copyright The QA-AI-STLC Authors
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+import { ConfigSchema } from '@qa-ai-stlc/schemas';
+import { parse as parseYaml } from 'yaml';
+import { QaError } from './errors.js';
+const CONFIG_PATH = 'config.yaml';
+/**
+ * Reads and validates `.qa/config.yaml` against `ConfigSchema`, the schema-versioned contract
+ * every other package trusts. Throws `QaError` with a stable `code` and a remediation an agent
+ * or CLI flag can act on, never a bare Zod or YAML parse error (AGENTS.md 5.4).
+ */
+export async function loadConfig(store) {
+    const exists = await store.pathExists(CONFIG_PATH);
+    if (!exists) {
+        throw new QaError('CONFIG_MISSING', 'No .qa/config.yaml found', {
+            remediation: 'Run "qa init" to create the .qa/ store and its configuration file.',
+        });
+    }
+    const raw = await store.readText(CONFIG_PATH);
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch (error) {
+        throw new QaError('CONFIG_MALFORMED', '.qa/config.yaml is not valid YAML', {
+            remediation: 'Fix the YAML syntax reported below and re-run.',
+            cause: error,
+        });
+    }
+    const result = ConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new QaError('CONFIG_INVALID', `.qa/config.yaml does not match its schema:\n${z.prettifyError(result.error)}`, {
+            remediation: 'Fix the reported fields or regenerate the file with "qa init".',
+            cause: result.error,
+        });
+    }
+    return result.data;
+}
+//# sourceMappingURL=config-loader.js.map

package/dist/config-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loader.js","sourceRoot":"","sources":["../src/config-loader.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,sCAAsC;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAkC,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC,MAAM,WAAW,GAAiB,aAAa,CAAC;AAEhD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAc;IAC7C,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,OAAO,CAAC,gBAAgB,EAAE,0BAA0B,EAAE;YAC9D,WAAW,EAAE,oEAAoE;SAClF,CAAC,CAAC;IACL,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC9C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,OAAO,CAAC,kBAAkB,EAAE,mCAAmC,EAAE;YACzE,WAAW,EAAE,gDAAgD;YAC7D,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,OAAO,CACf,gBAAgB,EAChB,+CAA+C,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAC9E;YACE,WAAW,EAAE,gEAAgE;YAC7E,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CACF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+export interface QaErrorOptions {
+    readonly remediation?: string;
+    readonly cause?: unknown;
+}
+/**
+ * Every expected engine failure (bad config, hash mismatch, unregistered artifact) is a
+ * `QaError` with a stable, machine-readable `code` an agent or CLI flag can branch on, and an
+ * optional `remediation` it can act on or show the operator (AGENTS.md 5.4).
+ */
+export declare class QaError extends Error {
+    readonly code: string;
+    readonly remediation: string | undefined;
+    constructor(code: string, message: string, options?: QaErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,qBAAa,OAAQ,SAAQ,KAAK;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE7B,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB;CAMxE"}

package/dist/errors.js

@@ -0,0 +1,18 @@
+// Copyright The QA-AI-STLC Authors
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Every expected engine failure (bad config, hash mismatch, unregistered artifact) is a
+ * `QaError` with a stable, machine-readable `code` an agent or CLI flag can branch on, and an
+ * optional `remediation` it can act on or show the operator (AGENTS.md 5.4).
+ */
+export class QaError extends Error {
+    code;
+    remediation;
+    constructor(code, message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = 'QaError';
+        this.code = code;
+        this.remediation = options.remediation;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,sCAAsC;AAOtC;;;;GAIG;AACH,MAAM,OAAO,OAAQ,SAAQ,KAAK;IACvB,IAAI,CAAS;IACb,WAAW,CAAqB;IAEzC,YAAY,IAAY,EAAE,OAAe,EAAE,UAA0B,EAAE;QACrE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACzC,CAAC;CACF"}

package/dist/evidence-store.d.ts

@@ -0,0 +1,43 @@
+import { type Evidence, type EvidenceKind, type Identifier, type RelativePath } from '@qa-ai-stlc/schemas';
+import { type Clock } from './ports/clock.js';
+import type { ManifestStore } from './manifest-store.js';
+import type { QaStore } from './qa-store.js';
+export interface EvidenceRegisterOptions {
+    readonly id: Identifier;
+    readonly runId: Identifier;
+    readonly stepId?: Identifier;
+    readonly kind: EvidenceKind;
+    readonly content: string | Uint8Array;
+    /** Without a leading dot. Defaults to a sensible extension for `kind`. */
+    readonly fileExtension?: string;
+}
+export type EvidenceRegistration = {
+    readonly status: 'registered';
+    readonly evidence: Evidence;
+} | {
+    readonly status: 'quarantined';
+    readonly receiptPath: RelativePath;
+    readonly patterns: readonly string[];
+};
+export interface EvidenceStoreOptions {
+    readonly store: QaStore;
+    readonly manifest: ManifestStore;
+    readonly clock?: Clock;
+}
+/**
+ * Registers evidence the way AGENTS.md 2.5/12.5 require: hashed, timestamped, linked to a step,
+ * and scanned for leaked secrets before anything is written to disk. `network-har` content is
+ * redacted proactively (development plan section 6.4); the secret scan is the safety net for
+ * everything else, or for whatever that redaction pass could not understand. Content that still
+ * matches a known secret shape after redaction is never written — a sanitized quarantine receipt
+ * is registered in its place instead (AGENTS.md 12.5).
+ */
+export declare class EvidenceStore {
+    private readonly store;
+    private readonly manifest;
+    private readonly clock;
+    constructor(options: EvidenceStoreOptions);
+    register(options: EvidenceRegisterOptions): Promise<EvidenceRegistration>;
+    private writeQuarantineReceipt;
+}
+//# sourceMappingURL=evidence-store.d.ts.map

package/dist/evidence-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-store.d.ts","sourceRoot":"","sources":["../src/evidence-store.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAG3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAW7C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IACtC,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAC9D;IACE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC;AAEN,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;gBAElB,OAAO,EAAE,oBAAoB;IAMnC,QAAQ,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,oBAAoB,CAAC;YAqCjE,sBAAsB;CAkBrC"}

package/dist/evidence-store.js

@@ -0,0 +1,81 @@
+// Copyright The QA-AI-STLC Authors
+// SPDX-License-Identifier: Apache-2.0
+import { EvidenceQuarantineReceiptSchema, EvidenceSchema, } from '@qa-ai-stlc/schemas';
+import { hashContent } from './hash.js';
+import { toCanonicalJson } from './json-file.js';
+import { systemClock } from './ports/clock.js';
+import { redactHar } from './redaction.js';
+import { scanForSecrets } from './secret-scan.js';
+const DEFAULT_FILE_EXTENSIONS = {
+    screenshot: 'png',
+    trace: 'zip',
+    'network-har': 'har',
+    'console-log': 'log',
+    video: 'webm',
+    other: 'bin',
+};
+/**
+ * Registers evidence the way AGENTS.md 2.5/12.5 require: hashed, timestamped, linked to a step,
+ * and scanned for leaked secrets before anything is written to disk. `network-har` content is
+ * redacted proactively (development plan section 6.4); the secret scan is the safety net for
+ * everything else, or for whatever that redaction pass could not understand. Content that still
+ * matches a known secret shape after redaction is never written — a sanitized quarantine receipt
+ * is registered in its place instead (AGENTS.md 12.5).
+ */
+export class EvidenceStore {
+    store;
+    manifest;
+    clock;
+    constructor(options) {
+        this.store = options.store;
+        this.manifest = options.manifest;
+        this.clock = options.clock ?? systemClock;
+    }
+    async register(options) {
+        const extension = options.fileExtension ?? DEFAULT_FILE_EXTENSIONS[options.kind];
+        let content = options.content;
+        let redacted = false;
+        if (options.kind === 'network-har' && typeof content === 'string') {
+            const result = redactHar(content);
+            content = result.content;
+            redacted = result.redacted;
+        }
+        const textForScan = typeof content === 'string' ? content : Buffer.from(content).toString('latin1');
+        const matches = scanForSecrets(textForScan);
+        if (matches.length > 0) {
+            const patterns = matches.map((match) => match.pattern);
+            const receiptPath = await this.writeQuarantineReceipt(options, patterns);
+            return { status: 'quarantined', receiptPath, patterns };
+        }
+        const relativePath = `evidence/${options.runId}/${options.id}.${extension}`;
+        await this.store.writeBytes(relativePath, content);
+        await this.manifest.register(relativePath, content);
+        const evidence = EvidenceSchema.parse({
+            id: options.id,
+            runId: options.runId,
+            ...(options.stepId !== undefined ? { stepId: options.stepId } : {}),
+            kind: options.kind,
+            path: relativePath,
+            sha256: hashContent(content),
+            createdAt: this.clock.now().toISOString(),
+            redacted,
+        });
+        return { status: 'registered', evidence };
+    }
+    async writeQuarantineReceipt(options, patterns) {
+        const receiptPath = `evidence/${options.runId}/${options.id}.quarantine.json`;
+        const receipt = EvidenceQuarantineReceiptSchema.parse({
+            id: options.id,
+            runId: options.runId,
+            ...(options.stepId !== undefined ? { stepId: options.stepId } : {}),
+            kind: options.kind,
+            createdAt: this.clock.now().toISOString(),
+            reason: 'secret-detected',
+            patterns,
+        });
+        await this.store.writeJson(receiptPath, receipt);
+        await this.manifest.register(receiptPath, toCanonicalJson(receipt));
+        return receiptPath;
+    }
+}
+//# sourceMappingURL=evidence-store.js.map

package/dist/evidence-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-store.js","sourceRoot":"","sources":["../src/evidence-store.ts"],"names":[],"mappings":"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"}

package/dist/hash.d.ts

@@ -0,0 +1,6 @@
+import type { Sha256Hex } from '@qa-ai-stlc/schemas';
+export declare function hashText(content: string): Sha256Hex;
+export declare function hashBytes(content: Uint8Array): Sha256Hex;
+/** Picks the text or binary hasher based on the content's runtime type. */
+export declare function hashContent(content: string | Uint8Array): Sha256Hex;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAIrD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAGnD;AAID,wBAAgB,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAExD;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAEnE"}