@molecule/api-ai-tools 1.16.8 → 1.17.1

package/dist/playwright-feedback-selection.js

@@ -0,0 +1,206 @@
+/**
+ * Prioritize native spec files from explicit route declarations and source imports.
+ * TypeScript parses syntax; Playwright judges behavior. Unreadable/dynamic routing
+ * falls back to all specs, rather than treating an absent index entry as coverage.
+ * @module
+ */
+import { createRequire } from 'node:module';
+import { posix } from 'node:path';
+const require = createRequire(import.meta.url);
+let compiler;
+const typescript = () => (compiler ??= require('typescript'));
+/** Get the text of a literal or the static prefix of a route template. */
+function routeText(node) {
+    const ts = typescript();
+    if (!node)
+        return undefined;
+    if (ts.isJsxExpression(node))
+        return routeText(node.expression);
+    if (ts.isStringLiteralLike(node))
+        return node.text;
+    if (ts.isTemplateExpression(node))
+        return `${node.head.text}*`;
+    return undefined;
+}
+/** Parse each file once, resolving only relative source imports we actually have. */
+function sourceIndex(files) {
+    const ts = typescript();
+    const trees = new Map(files.map((f) => [
+        f.path,
+        ts.createSourceFile(f.path, f.content, ts.ScriptTarget.Latest, true),
+    ]));
+    const imports = new Map();
+    const dependencies = new Map();
+    for (const [file, tree] of trees) {
+        const names = new Map(), deps = new Set();
+        const resolve = (text) => {
+            if (!text.startsWith('.'))
+                return undefined;
+            const base = posix.resolve(posix.dirname(file), text);
+            return [
+                base,
+                base.replace(/\.[cm]?jsx?$/, '.ts'),
+                base.replace(/\.[cm]?jsx?$/, '.tsx'),
+                ...['.ts', '.tsx', '.js', '.jsx', '/index.ts', '/index.tsx'].map((ext) => base + ext),
+            ].find((p) => trees.has(p));
+        };
+        const visit = (node) => {
+            if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+                const target = resolve(node.moduleSpecifier.text);
+                if (target) {
+                    deps.add(target);
+                    const clause = node.importClause;
+                    if (clause?.name)
+                        names.set(clause.name.text, target);
+                    if (clause?.namedBindings && ts.isNamedImports(clause.namedBindings))
+                        for (const n of clause.namedBindings.elements)
+                            names.set(n.name.text, target);
+                }
+            }
+            if (ts.isExportDeclaration(node) &&
+                node.moduleSpecifier &&
+                ts.isStringLiteral(node.moduleSpecifier)) {
+                const target = resolve(node.moduleSpecifier.text);
+                if (target)
+                    deps.add(target);
+            }
+            if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+                const text = routeText(node.arguments[0]), target = text && resolve(text);
+                if (target)
+                    deps.add(target);
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(tree);
+        imports.set(file, names);
+        dependencies.set(file, deps);
+    }
+    return { trees, imports, dependencies };
+}
+/** The explicit routes a module declares; unknown framework shapes remain unindexed. */
+function routeFiles(files) {
+    const ts = typescript();
+    const { trees, imports, dependencies } = sourceIndex(files);
+    const out = [];
+    const closure = (file, seen) => {
+        if (seen.has(file))
+            return;
+        seen.add(file);
+        for (const dep of dependencies.get(file) ?? [])
+            closure(dep, seen);
+    };
+    for (const [file, tree] of trees) {
+        const add = (path, element) => {
+            const route = routeText(path);
+            // Relative and nested declarations need the router's own resolution. Do not guess it.
+            if (!route?.startsWith('/') || !element)
+                return;
+            const selected = new Set([file]);
+            const refs = (node) => {
+                if (ts.isIdentifier(node)) {
+                    const target = imports.get(file)?.get(node.text);
+                    if (target)
+                        closure(target, selected);
+                }
+                ts.forEachChild(node, refs);
+            };
+            refs(element);
+            // A local component, namespace or lazy binding cannot be resolved narrowly here.
+            if (selected.size === 1)
+                closure(file, selected);
+            out.push({ route, files: selected });
+        };
+        const visit = (node) => {
+            if (ts.isJsxSelfClosingElement(node) || ts.isJsxOpeningElement(node)) {
+                const attrs = node.attributes.properties.filter(ts.isJsxAttribute);
+                const path = attrs.find((a) => a.name.getText(tree) === 'path')?.initializer;
+                const element = attrs.find((a) => /^(element|component|Component)$/.test(a.name.getText(tree)))?.initializer;
+                add(path, element);
+            }
+            if (ts.isObjectLiteralExpression(node)) {
+                const props = node.properties.filter(ts.isPropertyAssignment);
+                add(props.find((p) => p.name.getText(tree).replace(/['"]/g, '') === 'path')?.initializer, props.find((p) => /^(element|component|Component)$/.test(p.name.getText(tree).replace(/['"]/g, '')))?.initializer);
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(tree);
+    }
+    return out;
+}
+/** Goto targets in a spec and its supplied helpers. Unknown targets force a conservative run. */
+function specRoutes(spec, index) {
+    const ts = typescript();
+    const { trees, dependencies } = index;
+    const seen = new Set(), routes = [];
+    let unknown = false;
+    const read = (file) => {
+        if (seen.has(file))
+            return;
+        seen.add(file);
+        const tree = trees.get(file);
+        if (!tree) {
+            unknown = true;
+            return;
+        }
+        const visit = (node) => {
+            if (ts.isCallExpression(node) &&
+                ts.isPropertyAccessExpression(node.expression) &&
+                node.expression.name.text === 'goto') {
+                const route = routeText(node.arguments[0]);
+                if (route?.startsWith('/'))
+                    routes.push(route.split('?')[0].split('#')[0]);
+                else
+                    unknown = true;
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(tree);
+        for (const dep of dependencies.get(file) ?? [])
+            read(dep);
+    };
+    read(spec.path);
+    return { routes, unknown: unknown || routes.length === 0 };
+}
+/** Compare route patterns for selection only, never for a correctness claim. */
+function routeOverlaps(a, b) {
+    const left = a.split('/').filter(Boolean), right = b.split('/').filter(Boolean);
+    const n = Math.max(left.length, right.length);
+    for (let i = 0; i < n; i++) {
+        if (left[i] === '*' || right[i] === '*')
+            return true;
+        if (!left[i] || !right[i])
+            return false;
+        if (!left[i].startsWith(':') && !right[i].startsWith(':') && left[i] !== right[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Prioritize spec files potentially affected by writes. Every file still runs: a click or
+ * a helper can navigate somewhere a literal-goto index cannot see. This index never excludes work.
+ * @param project - Caller-supplied source and runner inventory.
+ * @param changed - Absolute source paths changed since the previous diagnosis.
+ * @returns Spec files to run, with their rendering-source context.
+ */
+export function selectFeedbackSpecs(project, changed) {
+    if (project.specs.length === 0)
+        return [];
+    const routes = routeFiles(project.sources);
+    const affected = routes.filter((r) => changed.some((p) => r.files.has(p)));
+    const index = sourceIndex([...project.sources, ...project.specs]);
+    return project.specs
+        .map((spec) => {
+        const targets = specRoutes(spec, index);
+        const hits = affected.filter((r) => targets.routes.some((path) => routeOverlaps(r.route, path)));
+        return {
+            spec,
+            priority: hits.length,
+            sourceFiles: [
+                ...new Set(hits.length
+                    ? hits.flatMap((r) => [...r.files]).filter((p) => changed.includes(p))
+                    : changed),
+            ],
+        };
+    })
+        .sort((a, b) => b.priority - a.priority);
+}

package/dist/playwright-feedback-types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Native Playwright diagnosis while an app is being written.
+ *
+ * @module
+ */
+import type { PlaywrightReportStats } from './playwright-report.js';
+/** A source file already read by the caller. Paths are absolute. */
+export interface FeedbackSource {
+    path: string;
+    content: string;
+}
+/** One supplied or scaffolded spec, with its normal, locally targeted runner command. */
+export interface FeedbackSpec extends FeedbackSource {
+    command: string;
+    cwd: string;
+}
+/** The inputs the host already knows; no suite discovery or vendor selection in the scheduler. */
+export interface FeedbackProject {
+    /** Base for relative source-change paths, already resolved by the host. */
+    root?: string;
+    sources: FeedbackSource[];
+    specs: FeedbackSpec[];
+}
+/** A native failure, never a static prediction or a completed-suite proof. */
+export interface PlaywrightFeedbackFailure {
+    spec: string;
+    line: number;
+    error: string;
+    /** The native runner's locator, assertion or timed-out browser operation, apart from redaction. */
+    locator: string;
+    /** Playwright's own failure-time accessibility snapshot, when recorded. */
+    rendered?: string;
+    /** Route render dependencies affected by this write, or the triggering source paths. */
+    sourceFiles: string[];
+}
+/** A diagnosis of one spec file at one source revision. A pass is not whole-suite proof. */
+export interface PlaywrightFeedbackResult {
+    spec: string;
+    revision: number;
+    durationMs: number;
+    status: 'passed' | 'failed' | 'unavailable';
+    failures: PlaywrightFeedbackFailure[];
+    /** Native counts for this one diagnostic selection, never whole-suite proof. */
+    nativeStats?: PlaywrightReportStats;
+    reason?: string;
+}
+/** Host operations for the same scheduler in a CLI process or a remote sandbox. */
+export interface PlaywrightFeedbackOptions {
+    load: () => Promise<FeedbackProject>;
+    run: (spec: FeedbackSpec, sources: string[], revision: number, emit: (result: PlaywrightFeedbackResult) => void) => Promise<PlaywrightFeedbackResult>;
+    /** Only current native failures are delivered. Passing apps receive no note. */
+    onFailures?: (result: PlaywrightFeedbackResult) => void;
+    /** Operational state is separate from defect feedback. */
+    onResult?: (result: PlaywrightFeedbackResult) => void;
+    debounceMs?: number;
+}
+/** A nonblocking source-change subscription. */
+export interface PlaywrightFeedback {
+    changed: (paths: readonly string[]) => void;
+    takeFailures: () => PlaywrightFeedbackResult[];
+    /** Wait only in tests or shutdown; file writes and deploys must never await this. */
+    settled: () => Promise<void>;
+    close: () => Promise<void>;
+}
+//# sourceMappingURL=playwright-feedback-types.d.ts.map

package/dist/playwright-feedback-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-feedback-types.d.ts","sourceRoot":"","sources":["../src/playwright-feedback-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAEnE,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,yFAAyF;AACzF,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,kGAAkG;AAClG,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,KAAK,EAAE,YAAY,EAAE,CAAA;CACtB;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,mGAAmG;IACnG,OAAO,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wFAAwF;IACxF,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB;AAED,4FAA4F;AAC5F,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAA;IAC3C,QAAQ,EAAE,yBAAyB,EAAE,CAAA;IACrC,gFAAgF;IAChF,WAAW,CAAC,EAAE,qBAAqB,CAAA;IACnC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,mFAAmF;AACnF,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAA;IACpC,GAAG,EAAE,CACH,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,KAC7C,OAAO,CAAC,wBAAwB,CAAC,CAAA;IACtC,gFAAgF;IAChF,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACvD,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACrD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAA;IAC3C,YAAY,EAAE,MAAM,wBAAwB,EAAE,CAAA;IAC9C,qFAAqF;IACrF,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B"}

package/dist/playwright-feedback-types.js

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

package/dist/playwright-feedback.d.ts

@@ -0,0 +1,42 @@
+import type { FeedbackSource, FeedbackSpec, PlaywrightFeedback, PlaywrightFeedbackOptions, PlaywrightFeedbackResult } from './playwright-feedback-types.js';
+import type { ExecutionBackend } from './types.js';
+/**
+ * Whether a source change can alter markup, copy, styling or local runner configuration.
+ * @param path - The path reported by the host's file-change subscription.
+ * @returns True for app source and data formats; never a correctness judgment.
+ */
+export declare function isPlaywrightFeedbackSource(path: string): boolean;
+/**
+ * Subscribe to writes without making them wait for browser work.
+ * @param options - Source loader, native runner and delivery callbacks.
+ * @returns A source-change subscription; settle/close are for tests and shutdown only.
+ */
+export declare function createPlaywrightFeedback(options: PlaywrightFeedbackOptions): PlaywrightFeedback;
+/**
+ * Read explicit source roots and supplied helper/spec paths in one backend round trip.
+ * The standard filesystem and TypeScript parser own traversal/syntax; this is transport batching.
+ * @param backend - Local or sandbox execution backend.
+ * @param sourceRoots - App source directories, absolute.
+ * @param suiteFiles - Supplied spec/helper paths, absolute.
+ * @returns Existing, bounded text sources. Missing/unsupported files are ignored.
+ */
+export declare function readFeedbackSources(backend: ExecutionBackend, sourceRoots: readonly string[], suiteFiles: readonly string[]): Promise<FeedbackSource[]>;
+/**
+ * Run ONE spec's native command. Callers supply the correctly configured local command and
+ * append these runner flags at composition time (rather than modifying shell text here).
+ * Native failures are diagnosis, never proof that a complete supplied suite passed.
+ * @param backend - Existing execution backend.
+ * @param spec - The supplied spec and its normal per-file command.
+ * @param sourceFiles - Triggering component files, known to the write/index.
+ * @param revision - Source revision the scheduler will validate before delivery.
+ * @param options - Output location, command composition and a bounded backend budget.
+ * @returns The actual native outcome and actionable failures only.
+ */
+export declare function runPlaywrightFeedback(backend: ExecutionBackend, spec: FeedbackSpec, sourceFiles: string[], revision: number, options: {
+    command: (flags: string[]) => string;
+    scratchRoot?: string;
+    timeoutMs?: number;
+    emit?: (result: PlaywrightFeedbackResult) => void;
+    pollMs?: number;
+}): Promise<PlaywrightFeedbackResult>;
+//# sourceMappingURL=playwright-feedback.d.ts.map

package/dist/playwright-feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-feedback.d.ts","sourceRoot":"","sources":["../src/playwright-feedback.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAEV,cAAc,EACd,YAAY,EACZ,kBAAkB,EAElB,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,gCAAgC,CAAA;AAEvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAGlD;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CAyG/F;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,gBAAgB,EACzB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,OAAO,CAAC,cAAc,EAAE,CAAC,CAkB3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,YAAY,EAClB,WAAW,EAAE,MAAM,EAAE,EACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IACP,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;IACpC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACjD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GACA,OAAO,CAAC,wBAAwB,CAAC,CAwInC"}

package/dist/playwright-feedback.js

@@ -0,0 +1,318 @@
+/**
+ * Run the project's real Playwright files while an agent keeps writing.
+ *
+ * The native runner, JSON reporter and error-context snapshot already answer what
+ * failed and what rendered. The small scheduler only coalesces writes, prioritizes
+ * route-related spec files, runs one at a time, and discards stale revisions.
+ * No correctness inference, foreground barrier, extra browser or passing-run note.
+ * @module
+ */
+import { randomUUID } from 'node:crypto';
+import { posix } from 'node:path';
+import { feedbackReporterSource, nativeFeedbackFailures } from './playwright-feedback-reporter.js';
+import { selectFeedbackSpecs } from './playwright-feedback-selection.js';
+import { summarizePlaywrightReport } from './playwright-report.js';
+import { redactSecrets, shellQuote } from './utilities.js';
+/**
+ * Whether a source change can alter markup, copy, styling or local runner configuration.
+ * @param path - The path reported by the host's file-change subscription.
+ * @returns True for app source and data formats; never a correctness judgment.
+ */
+export function isPlaywrightFeedbackSource(path) {
+    return /\.(?:[cm]?[jt]sx?|vue|svelte|html?|css|json|mdx?)$/i.test(path);
+}
+/**
+ * Subscribe to writes without making them wait for browser work.
+ * @param options - Source loader, native runner and delivery callbacks.
+ * @returns A source-change subscription; settle/close are for tests and shutdown only.
+ */
+export function createPlaywrightFeedback(options) {
+    let revision = 0, timer, active;
+    let stopped = false;
+    const changed = new Set(), waiting = [];
+    const delivered = new Map();
+    const failing = new Set();
+    const start = () => {
+        if (active || stopped || changed.size === 0)
+            return;
+        const version = revision, paths = [...changed];
+        changed.clear();
+        active = (async () => {
+            let project;
+            try {
+                project = await options.load();
+            }
+            catch (_error) {
+                return;
+            }
+            if (stopped || version !== revision)
+                return;
+            const sourcePaths = project.root ? paths.map((p) => posix.resolve(project.root, p)) : paths;
+            // The native failures already name the files to rerun first after an edit.
+            const selected = selectFeedbackSpecs(project, sourcePaths).sort((a, b) => Number(failing.has(b.spec.path)) - Number(failing.has(a.spec.path)));
+            for (const { spec, sourceFiles } of selected) {
+                if (stopped || version !== revision)
+                    break;
+                const emit = (result) => {
+                    if (stopped || version !== revision || result.status !== 'failed')
+                        return;
+                    failing.add(spec.path);
+                    const identities = delivered.get(spec.path) ?? new Set();
+                    const failures = result.failures.filter((f) => {
+                        const identity = JSON.stringify(f);
+                        if (identities.has(identity))
+                            return false;
+                        identities.add(identity);
+                        return true;
+                    });
+                    delivered.set(spec.path, identities);
+                    if (!failures.length)
+                        return;
+                    const fresh = { ...result, failures };
+                    waiting.push(fresh);
+                    options.onFailures?.(fresh);
+                };
+                let result;
+                try {
+                    result = await options.run(spec, sourceFiles, version, emit);
+                }
+                catch (_error) {
+                    continue;
+                } // runner availability is not a markup defect
+                if (stopped || version !== revision)
+                    break;
+                options.onResult?.(result);
+                if (result.status === 'passed')
+                    failing.delete(spec.path);
+                if (result.status !== 'failed')
+                    delivered.delete(spec.path);
+                emit(result);
+            }
+        })().finally(() => {
+            active = undefined;
+            if (!stopped && changed.size && !timer)
+                schedule();
+        });
+    };
+    const schedule = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            start();
+        }, options.debounceMs ?? 250);
+        timer.unref?.();
+    };
+    const settled = async () => {
+        while (timer || active || (!stopped && changed.size)) {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+                start();
+            }
+            if (active)
+                await active;
+            else if (!stopped && changed.size)
+                start();
+        }
+    };
+    return {
+        changed(paths) {
+            if (stopped || paths.length === 0)
+                return;
+            revision++;
+            for (const path of paths)
+                changed.add(path);
+            waiting.length = 0;
+            // A queued diagnosis can be invalidated before its host delivers it. A
+            // new revision must be allowed to report the same still-failing locator.
+            delivered.clear();
+            schedule();
+        },
+        takeFailures() {
+            return waiting.splice(0).filter((r) => r.revision === revision);
+        },
+        settled,
+        async close() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+            changed.clear();
+            waiting.length = 0;
+            if (active)
+                await active;
+        },
+    };
+}
+/**
+ * Read explicit source roots and supplied helper/spec paths in one backend round trip.
+ * The standard filesystem and TypeScript parser own traversal/syntax; this is transport batching.
+ * @param backend - Local or sandbox execution backend.
+ * @param sourceRoots - App source directories, absolute.
+ * @param suiteFiles - Supplied spec/helper paths, absolute.
+ * @returns Existing, bounded text sources. Missing/unsupported files are ignored.
+ */
+export async function readFeedbackSources(backend, sourceRoots, suiteFiles) {
+    if (sourceRoots.length === 0 && suiteFiles.length === 0)
+        return [];
+    const program = `const fs=require('node:fs'),p=require('node:path');const seen=new Set(),out=[];let bytes=0;
+const read=f=>{if(seen.has(f)||out.length>=1000||bytes>=4000000)return;seen.add(f);try{const s=fs.lstatSync(f);if(s.isSymbolicLink())return;if(s.isDirectory()){for(const n of fs.readdirSync(f))if(!['node_modules','.git','dist','build'].includes(n))read(p.join(f,n));}else if(/\\.[cm]?[jt]sx?$/.test(f)&&s.size<=250000){const content=fs.readFileSync(f,'utf8');bytes+=content.length;out.push({path:f,content});}}catch{}};
+for(const f of ${JSON.stringify([...sourceRoots, ...suiteFiles])})read(f);process.stdout.write(JSON.stringify(out));`;
+    const result = await backend.run(`node -e ${shellQuote(program)}`, { timeout: 10_000 });
+    if (result.exitCode !== 0)
+        return [];
+    try {
+        const value = JSON.parse(result.stdout);
+        return Array.isArray(value)
+            ? value.filter((f) => f && typeof f.path === 'string' && typeof f.content === 'string')
+            : [];
+    }
+    catch (_error) {
+        return [];
+    }
+}
+/**
+ * Run ONE spec's native command. Callers supply the correctly configured local command and
+ * append these runner flags at composition time (rather than modifying shell text here).
+ * Native failures are diagnosis, never proof that a complete supplied suite passed.
+ * @param backend - Existing execution backend.
+ * @param spec - The supplied spec and its normal per-file command.
+ * @param sourceFiles - Triggering component files, known to the write/index.
+ * @param revision - Source revision the scheduler will validate before delivery.
+ * @param options - Output location, command composition and a bounded backend budget.
+ * @returns The actual native outcome and actionable failures only.
+ */
+export async function runPlaywrightFeedback(backend, spec, sourceFiles, revision, options) {
+    const started = Date.now();
+    const dir = posix.join(options.scratchRoot ?? posix.join(backend.projectRoot, '.mol', 'test-feedback'), randomUUID());
+    const reportPath = posix.join(dir, 'report.json');
+    const reporterPath = posix.join(dir, 'feedback-reporter.cjs');
+    const eventsPath = posix.join(dir, 'failures.jsonl');
+    const timeout = options.timeoutMs ?? 120_000;
+    const base = { spec: spec.path, revision, failures: [] };
+    const unavailable = (reason) => ({
+        ...base,
+        status: 'unavailable',
+        durationMs: Date.now() - started,
+        reason,
+    });
+    const native = options.command([
+        `--reporter=${shellQuote(reporterPath + ',json')}`,
+        '--workers=1',
+        '--retries=0',
+        `--global-timeout=${timeout}`,
+        `--output=${shellQuote(posix.join(dir, 'results'))}`,
+    ]);
+    // The standard OS priority keeps background diagnosis behind the dev server
+    // and builds when they share one CPU. Playwright owns its global deadline.
+    const command = `export PLAYWRIGHT_JSON_OUTPUT_FILE=${shellQuote(reportPath)} MOL_TEST_FEEDBACK_EVENTS=${shellQuote(eventsPath)}; nice -n 10 sh -c ${shellQuote(native)}`;
+    let poll, reading, done = false;
+    const emitted = new Set();
+    const nativeFailures = new Map();
+    const readEvents = async () => {
+        try {
+            const text = await backend.readFile(eventsPath);
+            for (const failure of nativeFeedbackFailures(text, sourceFiles)) {
+                const identity = JSON.stringify(failure);
+                nativeFailures.set(identity, failure);
+                if (emitted.has(identity))
+                    continue;
+                emitted.add(identity);
+                options.emit?.({
+                    ...base,
+                    failures: [failure],
+                    status: 'failed',
+                    durationMs: Date.now() - started,
+                });
+            }
+        }
+        catch (_error) {
+            /* the first failure has not arrived yet */
+        }
+    };
+    const tick = () => {
+        if (done)
+            return;
+        reading = readEvents().finally(() => {
+            if (!done) {
+                poll = setTimeout(tick, options.pollMs ?? 1000);
+                poll.unref?.();
+            }
+        });
+    };
+    try {
+        await backend.writeFile(reporterPath, feedbackReporterSource());
+        if (options.emit)
+            tick();
+        const result = await backend.run(command, {
+            cwd: spec.cwd,
+            timeout: timeout + 10_000,
+            budgetMs: timeout + 5_000,
+        });
+        done = true;
+        if (poll)
+            clearTimeout(poll);
+        if (reading)
+            await reading;
+        await readEvents();
+        let reportText;
+        try {
+            reportText = await backend.readFile(reportPath);
+        }
+        catch (_error) {
+            return unavailable(`the native runner produced no JSON report: ${redactSecrets((result.stderr || result.stdout).trim().slice(0, 2000))}`);
+        }
+        const report = summarizePlaywrightReport(reportText, {
+            path: reportPath,
+            sanitize: redactSecrets,
+        });
+        if (report.status !== 'complete' ||
+            !report.stats ||
+            report.stats.expected + report.stats.unexpected + report.stats.flaky === 0 ||
+            report.stats.skipped > 0) {
+            let errors = [];
+            try {
+                errors = JSON.parse(reportText).errors ?? [];
+            }
+            catch (_error) {
+                /* the native summary already records malformed JSON */
+            }
+            const detail = errors.map((e) => e.message ?? '').join('\n') ||
+                result.stderr ||
+                report.reason ||
+                'zero executed tests or skipped tests';
+            return {
+                ...unavailable(`the native runner did not complete every selected test: ${redactSecrets(detail.slice(0, 2000))}`),
+                ...(report.stats ? { nativeStats: report.stats } : {}),
+            };
+        }
+        base.failures = [...nativeFailures.values()];
+        if (base.failures.length)
+            return {
+                ...base,
+                nativeStats: report.stats,
+                status: 'failed',
+                durationMs: Date.now() - started,
+            };
+        if (result.exitCode !== 0 || report.stats.unexpected || report.stats.flaky)
+            return unavailable('the native run failed outside a locator assertion');
+        return {
+            ...base,
+            nativeStats: report.stats,
+            status: 'passed',
+            durationMs: Date.now() - started,
+        };
+    }
+    finally {
+        done = true;
+        if (poll)
+            clearTimeout(poll);
+        if (reading)
+            await reading;
+        // Only this run's private generated files; the supplied suite and its outputs stay untouched.
+        await backend
+            .run(`node -e ${shellQuote(`require('node:fs').rmSync(${JSON.stringify(dir)},{recursive:true,force:true})`)}`, { timeout: 5_000 })
+            .catch(() => undefined);
+    }
+}

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AA4B9C,OAAO,EAIL,KAAK,mBAAmB,EAEzB,MAAM,wBAAwB,CAAA;AAsC/B;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,KAAK,CAAC,EACnD,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAmB9B;AAyLD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAkeD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAkInE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AA0DlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGtE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAoBpF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,GACxE,qBAAqB,CAkBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AA2GD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAwuGxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AA4B9C,OAAO,EAIL,KAAK,mBAAmB,EAEzB,MAAM,wBAAwB,CAAA;AAsC/B;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,KAAK,CAAC,EACnD,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAmB9B;AA4LD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAkeD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAkInE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AA0DlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGtE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAoBpF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,GACxE,qBAAqB,CAkBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AA2GD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAmvGxF"}