@rightkit/qa 0.2.4 → 0.3.1

package/README.md

@@ -1,14 +1,14 @@
 # `@rightkit/qa`
 
-> **Which QA tool?** To drive a Right Suite desktop app under test, use the Rust **`rightkit-qa`** crate with **`rightkit-control`**; that is the one supported engine. For a test browser only, use the zero-dependency **`@rightkit/qa-chrome`**. For an agent driving an installed app, use **`right-ctl`**. This package's WebdriverIO native lane is deprecated and will be removed once its last consumer (Cockpit hub) has moved; do not adopt it in new apps.
+> **Which QA tool?** To drive a Right Suite desktop app under test, use the Rust **`rightkit-qa`** crate with **`rightkit-control`**; that is the one supported engine. For a test browser only, use the zero-dependency **`@rightkit/qa-chrome`**. For an agent driving an installed app, use **`right-ctl`**. This package's WebdriverIO native lane & `right-qa` CLI were removed in 0.3.0.
 
-Shared native QA primitives for Right Suite desktop apps. The package owns run locking, bearer-authenticated loopback control, deterministic evidence bundles, exact owned-process cleanup, and the guard that keeps development WebDriver access out of production builds.
+Shared QA primitives for Right Suite desktop apps. The package owns run locking, bearer-authenticated loopback control, deterministic evidence bundles, exact owned-process cleanup, and the guard that keeps development WebDriver access out of production builds.
 
 This package is intentionally private until the Windows and macOS phase gate passes. App repositories must never consume it through a Git, path, `file:`, `link:`, or `workspace:` dependency; adoption happens only after a registry version is published.
 
 ## Chrome for Testing (`@rightkit/qa/chrome`)
 
-Web/CDP harnesses launch Chrome for Testing, never regular Google Chrome: on macOS each regular Chrome instance clones its app bundle under `<DARWIN_USER_TEMP_DIR>/../X/com.google.Chrome.code_sign_clone/`, and a killed instance leaks that clone. The native lane (`native.ts`, Tauri WebDriver) is unaffected.
+Web/CDP harnesses launch Chrome for Testing, never regular Google Chrome: on macOS each regular Chrome instance clones its app bundle under `<DARWIN_USER_TEMP_DIR>/../X/com.google.Chrome.code_sign_clone/`, and a killed instance leaks that clone.
 
 - `resolveChromeForTesting({ executablePath? })` resolves the explicit option, then `RIGHTKIT_CHROME_FOR_TESTING`, then `/Applications` and `~/Applications` app installs, then the newest Puppeteer (`~/.cache/puppeteer`, `PUPPETEER_CACHE_DIR`) and Playwright (`~/Library/Caches/ms-playwright`, `PLAYWRIGHT_BROWSERS_PATH`) builds. It throws `ChromeForTestingNotFoundError` with install instructions; it never falls back. `findChromeForTesting()` returns `{ path }` or `{ reason }` for test skips.
 - `launchChromeForTesting(options)` starts it in its own process group with a temp profile and returns `{ wsEndpoint, port, pid, profileDir, close() }`. Launch one browser per suite and open targets per test.

package/dist/index.d.ts

@@ -3,9 +3,9 @@ export * from './evidence.js';
 export * from './frames.js';
 export * from './guard.js';
 export * from './loopback.js';
-export * from './native.js';
 export * from './ownership.js';
 export * from './paint.js';
 export * from './panes.js';
 export * from './process.js';
 export * from './workspace.js';
+export * from './storage.js';

package/dist/index.js

@@ -3,9 +3,9 @@ export * from './evidence.js';
 export * from './frames.js';
 export * from './guard.js';
 export * from './loopback.js';
-export * from './native.js';
 export * from './ownership.js';
 export * from './paint.js';
 export * from './panes.js';
 export * from './process.js';
 export * from './workspace.js';
+export * from './storage.js';

package/dist/storage.d.ts

@@ -0,0 +1,50 @@
+export declare const RUN_MARKER = ".rightkit-run.json";
+export declare const DEFAULT_RETENTION_BYTES = 20000000000;
+export declare const DEFAULT_YOUNG_MS: number;
+export declare const DEFAULT_KEEP_COUNT = 5;
+export interface RunMarker {
+    schemaVersion: 1;
+    app: string;
+    runId: string;
+    createdAt: number;
+    ownerPid: number;
+    leaseUntil: number;
+    completedAt?: number;
+}
+export interface ManagedRun {
+    root: string;
+    app: string;
+    runId: string;
+    marker: RunMarker;
+}
+export interface RetentionPolicy {
+    maxBytes?: number;
+    keepCount?: number;
+    youngMs?: number;
+    now?: number;
+    keepRunIds?: string[];
+}
+export interface RetentionReport {
+    removed: string[];
+    retained: Array<{
+        path: string;
+        reason: string;
+    }>;
+    totalBytes: number;
+    capBytes: number;
+    overCapBytes: number;
+    blockedBytes: number;
+    unknownBytes: number;
+}
+export declare function resolveManagedRoot(explicit?: string): string;
+export declare function safeKey(value: string, name: string): string;
+export declare function runRoot(managedRoot: string, app: string, runId: string): string;
+export declare function createManagedRun(options: {
+    managedRoot?: string;
+    app: string;
+    runId?: string;
+    leaseMs?: number;
+    retention?: RetentionPolicy;
+}): ManagedRun;
+export declare function finishManagedRun(run: ManagedRun | string): RunMarker | undefined;
+export declare function pruneManagedRuns(managedRoot: string, app: string, policy?: RetentionPolicy): RetentionReport;

package/dist/storage.js

@@ -0,0 +1,315 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const RUN_MARKER = '.rightkit-run.json';
+export const DEFAULT_RETENTION_BYTES = 20_000_000_000;
+export const DEFAULT_YOUNG_MS = 24 * 60 * 60_000;
+export const DEFAULT_KEEP_COUNT = 5;
+const LOCK_WAIT_MS = 5_000;
+export function resolveManagedRoot(explicit) {
+    if (explicit?.trim())
+        return path.resolve(explicit);
+    if (process.env.RIGHTKIT_MANAGED_ROOT?.trim())
+        return path.resolve(process.env.RIGHTKIT_MANAGED_ROOT);
+    if (process.platform === 'win32')
+        return path.resolve('D:\\.rightkit-managed');
+    return '/Volumes/D/.rightkit-managed';
+}
+export function safeKey(value, name) {
+    const v = String(value ?? '').trim();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(v))
+        throw new Error(`unsafe QA ${name}: ${value}`);
+    return v;
+}
+export function runRoot(managedRoot, app, runId) {
+    const root = path.resolve(managedRoot);
+    const appKey = safeKey(app, 'app');
+    const id = safeKey(runId, 'run id');
+    const result = path.join(root, 'runs', appKey, id);
+    if (!isInside(path.join(root, 'runs', appKey), result))
+        throw new Error('QA run path escapes managed root');
+    return result;
+}
+export function createManagedRun(options) {
+    const managedRoot = resolveManagedRoot(options.managedRoot);
+    const app = safeKey(options.app, 'app');
+    const runId = safeKey(options.runId ?? cryptoRandomId(), 'run id');
+    const appRoot = path.join(managedRoot, 'runs', app);
+    withRetentionLock(appRoot, () => {
+        ensureSafeDirectory(managedRoot);
+        ensureSafeDirectory(path.join(managedRoot, 'runs'));
+        ensureSafeDirectory(appRoot);
+        const retention = { now: Date.now(), ...(options.retention ?? {}) };
+        const report = { removed: [], retained: [], totalBytes: 0, capBytes: DEFAULT_RETENTION_BYTES, overCapBytes: 0, blockedBytes: 0, unknownBytes: 0 };
+        pruneUnlocked(appRoot, app, retention, report);
+        if (report.overCapBytes > 0)
+            throw new Error(`QA retention cap is blocked by ${report.overCapBytes} bytes of protected or unknown data`);
+        const root = runRoot(managedRoot, app, runId);
+        if (fs.existsSync(root))
+            throw new Error(`QA run already exists: ${root}`);
+        fs.mkdirSync(root, { recursive: true });
+        const marker = {
+            schemaVersion: 1,
+            app,
+            runId,
+            createdAt: Date.now(),
+            ownerPid: process.pid,
+            leaseUntil: Date.now() + Math.max(1, options.leaseMs ?? DEFAULT_YOUNG_MS),
+        };
+        writeMarker(root, marker);
+    });
+    const root = runRoot(managedRoot, app, runId);
+    const marker = readMarker(path.join(root, RUN_MARKER));
+    if (!marker)
+        throw new Error(`QA run marker was not created: ${root}`);
+    return { root, app, runId, marker };
+}
+export function finishManagedRun(run) {
+    const root = typeof run === 'string' ? run : run.root;
+    const markerPath = path.join(path.resolve(root), RUN_MARKER);
+    const marker = readMarker(markerPath);
+    if (!marker)
+        return undefined;
+    const finished = { ...marker, ownerPid: 0, leaseUntil: 0, completedAt: Date.now() };
+    writeMarker(root, finished);
+    return finished;
+}
+export function pruneManagedRuns(managedRoot, app, policy = {}) {
+    const root = resolveManagedRoot(managedRoot);
+    const appKey = safeKey(app, 'app');
+    const appRoot = path.join(root, 'runs', appKey);
+    const cap = Number.isFinite(policy.maxBytes) && policy.maxBytes >= 0 ? policy.maxBytes : DEFAULT_RETENTION_BYTES;
+    const report = { removed: [], retained: [], totalBytes: 0, capBytes: cap, overCapBytes: 0, blockedBytes: 0, unknownBytes: 0 };
+    if (!safeDirectory(appRoot))
+        return report;
+    return withRetentionLock(appRoot, () => pruneUnlocked(appRoot, appKey, policy, report));
+}
+function pruneUnlocked(appRoot, app, policy, report) {
+    const now = policy.now ?? Date.now();
+    const cap = Number.isFinite(policy.maxBytes) && policy.maxBytes >= 0 ? policy.maxBytes : DEFAULT_RETENTION_BYTES;
+    report.capBytes = cap;
+    const keepCount = Math.max(0, Math.floor(policy.keepCount ?? DEFAULT_KEEP_COUNT));
+    const youngMs = Math.max(0, policy.youngMs ?? DEFAULT_YOUNG_MS);
+    const candidates = [];
+    let total = 0;
+    let entries;
+    try {
+        entries = fs.readdirSync(appRoot, { withFileTypes: true });
+    }
+    catch {
+        return report;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        if (entry.isSymbolicLink()) {
+            report.retained.push({ path: path.join(appRoot, entry.name), reason: 'symlink skipped' });
+            continue;
+        }
+        if (!entry.isDirectory())
+            continue;
+        const runPath = path.join(appRoot, entry.name);
+        if (!isInside(appRoot, runPath))
+            continue;
+        const marker = readMarker(path.join(runPath, RUN_MARKER));
+        if (!marker || marker.app !== app || marker.runId !== entry.name) {
+            const bytes = directoryBytes(runPath);
+            if (bytes !== undefined)
+                report.unknownBytes += bytes;
+            report.retained.push({ path: runPath, reason: 'unknown or malformed run metadata' });
+            continue;
+        }
+        const bytes = directoryBytes(runPath);
+        if (bytes === undefined) {
+            report.retained.push({ path: runPath, reason: 'symlink or unreadable content skipped' });
+            continue;
+        }
+        const active = marker.ownerPid > 0 && isProcessLive(marker.ownerPid) || marker.leaseUntil > now;
+        total += bytes;
+        candidates.push({ root: runPath, marker, bytes, active });
+    }
+    candidates.sort((a, b) => b.marker.createdAt - a.marker.createdAt || a.marker.runId.localeCompare(b.marker.runId));
+    const countProtected = new Set(candidates.slice(0, keepCount).map((x) => x.marker.runId));
+    const protectedIds = new Set();
+    const callerProtected = new Set(policy.keepRunIds ?? []);
+    for (const item of candidates) {
+        if (now - item.marker.createdAt < youngMs)
+            protectedIds.add(item.marker.runId);
+        if (item.active)
+            protectedIds.add(item.marker.runId);
+        if (callerProtected.has(item.marker.runId))
+            protectedIds.add(item.marker.runId);
+    }
+    const old = candidates
+        .filter((x) => !protectedIds.has(x.marker.runId) && (total > cap || !countProtected.has(x.marker.runId)))
+        .sort((a, b) => a.marker.createdAt - b.marker.createdAt || a.marker.runId.localeCompare(b.marker.runId));
+    const removed = new Set();
+    for (const item of old) {
+        if (total <= cap && countProtected.has(item.marker.runId))
+            continue;
+        if (!safeDirectory(item.root))
+            continue;
+        try {
+            fs.rmSync(item.root, { recursive: true, force: false });
+            report.removed.push(item.root);
+            removed.add(item.marker.runId);
+            total -= item.bytes;
+        }
+        catch (error) {
+            report.retained.push({ path: item.root, reason: describeError(error) });
+        }
+    }
+    for (const item of candidates) {
+        if (!removed.has(item.marker.runId) && (protectedIds.has(item.marker.runId) || (total <= cap && countProtected.has(item.marker.runId))))
+            report.retained.push({ path: item.root, reason: callerProtected.has(item.marker.runId) ? 'caller protected run' : item.active ? 'active run; may belong to a live run' : (now - item.marker.createdAt < youngMs ? 'younger than retention window' : 'newest protected run') });
+    }
+    report.blockedBytes = candidates.filter((item) => !removed.has(item.marker.runId) && (protectedIds.has(item.marker.runId) || (total <= cap && countProtected.has(item.marker.runId)))).reduce((sum, item) => sum + item.bytes, 0);
+    report.totalBytes = total + report.unknownBytes;
+    report.overCapBytes = Math.max(0, report.totalBytes - report.capBytes);
+    return report;
+}
+function withRetentionLock(appRoot, body) {
+    ensureSafeDirectory(path.dirname(appRoot));
+    ensureSafeDirectory(appRoot);
+    const lock = path.join(appRoot, '.retention-lock');
+    const owner = path.join(lock, 'owner.json');
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    while (true) {
+        try {
+            fs.mkdirSync(lock);
+            fs.writeFileSync(owner, JSON.stringify({ pid: process.pid, createdAt: Date.now() }), 'utf8');
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let pid;
+            try {
+                pid = JSON.parse(fs.readFileSync(owner, 'utf8')).pid;
+            }
+            catch { /* uncertain owner: wait */ }
+            if (typeof pid === 'number' && pid > 0 && !isProcessLive(pid)) {
+                try {
+                    fs.rmSync(lock, { recursive: true, force: true });
+                }
+                catch { /* retry */ }
+            }
+            else if (Date.now() >= deadline) {
+                throw new Error(`QA retention lock is held: ${lock}`);
+            }
+            if (Date.now() < deadline)
+                sleepSync(20);
+        }
+    }
+    try {
+        return body();
+    }
+    finally {
+        try {
+            fs.rmSync(lock, { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+    }
+}
+function writeMarker(root, marker) {
+    const target = path.join(root, RUN_MARKER);
+    const temp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temp, `${JSON.stringify(marker)}\n`, { encoding: 'utf8', flag: 'wx' });
+    fs.renameSync(temp, target);
+}
+function readMarker(file) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!raw || typeof raw !== 'object')
+            return undefined;
+        const x = raw;
+        if (x.schemaVersion !== 1 || typeof x.app !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(x.app) || typeof x.runId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(x.runId) || typeof x.createdAt !== 'number' || !Number.isFinite(x.createdAt) || x.createdAt <= 0 || typeof x.ownerPid !== 'number' || !Number.isInteger(x.ownerPid) || x.ownerPid < 0 || typeof x.leaseUntil !== 'number' || !Number.isFinite(x.leaseUntil) || x.leaseUntil < 0)
+            return undefined;
+        if (x.completedAt !== undefined && (typeof x.completedAt !== 'number' || !Number.isFinite(x.completedAt) || x.completedAt < 0))
+            return undefined;
+        return x;
+    }
+    catch {
+        return undefined;
+    }
+}
+function directoryBytes(root) {
+    let total = 0;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const entry of entries) {
+            const p = path.join(dir, entry.name);
+            if (entry.isSymbolicLink())
+                return false;
+            if (entry.isDirectory()) {
+                if (!walk(p))
+                    return false;
+            }
+            else if (entry.isFile()) {
+                try {
+                    total += fs.statSync(p).size;
+                }
+                catch {
+                    return false;
+                }
+            }
+            else
+                return false;
+        }
+        return true;
+    };
+    return walk(root) ? total : undefined;
+}
+function safeDirectory(dir) {
+    try {
+        return fs.lstatSync(dir).isDirectory() && !fs.lstatSync(dir).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function ensureSafeDirectory(dir) {
+    const absolute = path.resolve(dir);
+    const parts = absolute.split(path.sep);
+    let current = parts[0] || path.sep;
+    for (const part of parts.slice(1)) {
+        if (!part)
+            continue;
+        current = path.join(current, part);
+        try {
+            if (fs.lstatSync(current).isSymbolicLink())
+                throw new Error(`refusing symlink in managed path: ${current}`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    fs.mkdirSync(absolute, { recursive: true });
+}
+function isInside(root, candidate) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+function isProcessLive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function describeError(error) {
+    const x = error;
+    return x?.code ? `${x.code}: ${x.message}` : String(error?.message ?? error);
+}
+function sleepSync(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+function cryptoRandomId() { return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`; }

package/dist/workspace.d.ts

@@ -1,12 +1,18 @@
+import { type ManagedRun } from './storage.js';
 export interface QaWorkspace {
     runId: string;
+    appKey: string;
+    managedRoot: string;
     root: string;
     /** Isolated user-data directory; pass to the app so it takes its own lock. */
     dataDir: string;
     /** Somewhere for screenshots, logs, and other recorded evidence. */
     evidenceDir: string;
+    /** Managed capture output directory. */
+    captureDir: string;
     /** Environment overrides that point the app at this workspace. */
     env: Record<string, string>;
+    marker: ManagedRun['marker'];
 }
 export interface DisposeReport {
     removed: string[];
@@ -16,9 +22,12 @@ export interface DisposeReport {
     }>;
 }
 export interface CreateQaWorkspaceOptions {
-    root: string;
+    /** Managed root override; tests may provide a temporary directory. */
+    root?: string;
     runId?: string;
     appKey: string;
+    leaseMs?: number;
+    retention?: import('./storage.js').RetentionPolicy;
 }
 export declare function createQaWorkspace(options: CreateQaWorkspaceOptions): QaWorkspace;
 export interface DisposeOptions {

package/dist/workspace.js

@@ -17,26 +17,38 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { createManagedRun, finishManagedRun, pruneManagedRuns, resolveManagedRoot, } from './storage.js';
 export function createQaWorkspace(options) {
     const appKey = requireText(options.appKey, 'appKey');
-    const runId = options.runId ?? crypto.randomUUID();
-    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId))
-        throw new Error(`unsafe QA run id: ${runId}`);
-    const root = path.resolve(requireText(options.root, 'root'), 'runs', runId);
+    const managed = createManagedRun({ managedRoot: options.root ? requireText(options.root, 'root') : resolveManagedRoot(), app: appKey, runId: options.runId ?? crypto.randomUUID(), leaseMs: options.leaseMs, retention: options.retention });
+    const runId = managed.runId;
+    const root = managed.root;
     const dataDir = path.join(root, 'data');
     const evidenceDir = path.join(root, 'evidence');
+    const captureDir = path.join(root, 'captures');
+    const tmpDir = path.join(root, 'tmp');
     fs.mkdirSync(dataDir, { recursive: true });
     fs.mkdirSync(evidenceDir, { recursive: true });
+    fs.mkdirSync(captureDir, { recursive: true });
+    fs.mkdirSync(tmpDir, { recursive: true });
     return {
         runId,
+        appKey,
+        managedRoot: path.resolve(options.root ? requireText(options.root, 'root') : resolveManagedRoot()),
         root,
         dataDir,
         evidenceDir,
+        captureDir,
         env: {
             RIGHTKIT_QA_NATIVE: '1',
             RIGHTKIT_QA_RUN_ID: runId,
+            RIGHTKIT_RUN_ROOT: root,
             RIGHTKIT_QA_DATA_DIR: dataDir,
             RIGHTKIT_QA_EVIDENCE_DIR: evidenceDir,
+            RIGHTKIT_QA_CAPTURE_DIR: captureDir,
+            TMPDIR: tmpDir,
+            TMP: tmpDir,
+            TEMP: tmpDir,
             // Tauri/webview honour these for profile isolation; setting all three keeps
             // the run off the user's real profile regardless of which the app reads.
             XDG_DATA_HOME: dataDir,
@@ -44,6 +56,7 @@ export function createQaWorkspace(options) {
             WEBVIEW2_USER_DATA_FOLDER: path.join(dataDir, 'webview2'),
             [`${appKey.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_DATA_DIR`]: dataDir,
         },
+        marker: managed.marker,
     };
 }
 /**
@@ -57,6 +70,7 @@ export function disposeQaWorkspace(workspace, options = {}) {
     const sleep = options.sleep ?? sleepSync;
     const targets = options.keepEvidence ? [workspace.dataDir] : [workspace.root];
     const report = { removed: [], retained: [] };
+    finishManagedRun(workspace.root);
     for (const target of targets) {
         // Only ever remove inside the workspace root we created.
         const resolved = path.resolve(target);
@@ -93,39 +107,25 @@ export function disposeQaWorkspace(workspace, options = {}) {
  * workspace's own `runs` directory and to entries older than `olderThanMs`, so a
  * concurrent run is never removed out from under itself.
  */
-export function pruneAbandonedWorkspaces(root, { olderThanMs = 6 * 60 * 60_000, now = Date.now(), keep = [] } = {}) {
-    const runsRoot = path.resolve(root, 'runs');
+export function pruneAbandonedWorkspaces(root, { olderThanMs, now = Date.now(), keep = [] } = {}) {
+    const managedRoot = path.resolve(root);
     const report = { removed: [], retained: [] };
-    let entries;
+    const runsRoot = path.join(managedRoot, 'runs');
+    let apps;
     try {
-        entries = fs.readdirSync(runsRoot, { withFileTypes: true });
+        apps = fs.readdirSync(runsRoot, { withFileTypes: true });
     }
     catch {
         return report;
     }
-    for (const entry of entries) {
-        if (!entry.isDirectory() || entry.isSymbolicLink())
-            continue;
-        if (keep.includes(entry.name))
-            continue;
-        const target = path.join(runsRoot, entry.name);
-        let ageMs;
-        try {
-            ageMs = now - fs.statSync(target).mtimeMs;
-        }
-        catch {
-            continue;
-        }
-        if (ageMs < olderThanMs) {
-            report.retained.push({ path: target, reason: `only ${Math.round(ageMs / 1000)}s old; may belong to a live run` });
-            continue;
-        }
-        try {
-            fs.rmSync(target, { recursive: true, force: true });
-            report.removed.push(target);
-        }
-        catch (error) {
-            report.retained.push({ path: target, reason: describeError(error) });
+    for (const app of apps) {
+        if (app.isDirectory() && !app.isSymbolicLink()) {
+            const policy = olderThanMs === undefined
+                ? { now, keepRunIds: keep }
+                : { now, youngMs: olderThanMs, keepCount: 0, maxBytes: 0, keepRunIds: keep };
+            const sub = pruneManagedRuns(managedRoot, app.name, policy);
+            report.removed.push(...sub.removed);
+            report.retained.push(...sub.retained);
         }
     }
     return report;

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "@rightkit/qa",
-  "version": "0.2.4",
-  "description": "Shared native QA runner, evidence, ownership, and release-backdoor guards for Right Suite apps.",
+  "version": "0.3.1",
+  "description": "Shared QA evidence, ownership, browser helpers, and release-backdoor guards for Right Suite apps.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "bin": {
-    "right-qa": "dist/cli.js"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -27,14 +24,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@rightkit/qa-chrome": "0.1.2",
-    "@wdio/cli": "9.27.1",
-    "@wdio/local-runner": "9.27.1",
-    "@wdio/mocha-framework": "9.27.1",
-    "@wdio/spec-reporter": "9.27.1",
-    "@wdio/tauri-service": "1.2.0",
-    "undici": "6.27.0",
-    "webdriverio": "9.27.1"
+    "@rightkit/qa-chrome": "0.1.3"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -53,6 +43,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run"
+    "test": "vitest run && node --test public-storage.test.mjs"
   }
 }

package/dist/cli.d.ts

@@ -1,20 +0,0 @@
-#!/usr/bin/env node
-import type { NativeQaRuntimeOptions, RightQaConfig } from './native.js';
-import type { OwnedProcessResult } from './process.js';
-type RunProcess = (command: string, args: string[], options: {
-    cwd: string;
-    timeoutMs: number;
-    env: NodeJS.ProcessEnv;
-}) => Promise<OwnedProcessResult>;
-export interface NativeRunOptions extends NativeQaRuntimeOptions {
-    timeoutMs?: number;
-    wdioBin?: string;
-    runProcess?: RunProcess;
-}
-export interface NativeRunResult {
-    exitCode: number;
-    evidencePath: string;
-}
-export declare function runNativeQa(rawConfig: RightQaConfig, options?: NativeRunOptions): Promise<NativeRunResult>;
-export declare function loadRightQaConfig(configPath: string): Promise<RightQaConfig>;
-export {};

package/dist/cli.js

@@ -1,162 +0,0 @@
-#!/usr/bin/env node
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
-import { createRequire } from 'node:module';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { addEvidenceArtifact, addEvidenceCheck, createEvidenceBundle, finishEvidenceBundle, writeEvidenceBundle, } from './evidence.js';
-import { createQaWorkspace, pruneAbandonedWorkspaces } from './workspace.js';
-import { createWdioConfig, defineRightQaConfig } from './native.js';
-import { acquireRunOwnership } from './ownership.js';
-import { runOwnedProcess } from './process.js';
-export async function runNativeQa(rawConfig, options = {}) {
-    const app = defineRightQaConfig(rawConfig);
-    const platform = options.platform ?? requireDesktopPlatform();
-    const wdioConfig = createWdioConfig(app, { platform, embeddedPort: options.embeddedPort });
-    const binary = String(wdioConfig.capabilities[0]?.['tauri:options']?.application ?? '');
-    if (!fs.existsSync(binary))
-        throw new Error(`native QA binary not found: ${binary}`);
-    const cacheRoot = path.resolve(app.appRoot, app.evidenceDir ?? '.cache/rightkit-qa');
-    const runId = crypto.randomUUID();
-    // Earlier crashed runs left their directories behind; sweep them before adding
-    // one more, and never touch the run about to start.
-    pruneAbandonedWorkspaces(cacheRoot, { keep: [runId] });
-    const workspace = createQaWorkspace({ root: cacheRoot, runId, appKey: app.app });
-    const runRoot = workspace.root;
-    const generatedConfig = path.join(runRoot, 'wdio.generated.mjs');
-    const evidencePath = path.join(runRoot, 'evidence.json');
-    fs.writeFileSync(generatedConfig, [
-        `import { Agent, setGlobalDispatcher } from ${JSON.stringify(resolveUndiciEntry())};`,
-        'setGlobalDispatcher(new Agent());',
-        `const config = ${JSON.stringify(wdioConfig, null, 2)};`,
-        'config.beforeSession = () => { setGlobalDispatcher(new Agent()); };',
-        'export { config };',
-        '',
-    ].join('\n'), 'utf8');
-    const ownership = await acquireRunOwnership(path.join(cacheRoot, 'native.lock'), `${app.app}:native`);
-    const evidence = createEvidenceBundle({ app: app.app, platform, runId });
-    const runProcess = options.runProcess ?? runOwnedProcess;
-    try {
-        const result = await runProcess(process.execPath, [options.wdioBin ?? resolveWdioBin(), 'run', generatedConfig], {
-            cwd: app.appRoot,
-            timeoutMs: options.timeoutMs ?? 5 * 60_000,
-            env: {
-                ...process.env,
-                // The isolated data directory is what makes this a separate instance
-                // rather than a second claimant on the installed app's single-instance lock.
-                ...workspace.env,
-                RIGHTKIT_QA_HIDDEN: '1',
-                TAURI_WEBDRIVER_PORT: String(options.embeddedPort ?? 4445),
-            },
-        });
-        const passed = result.code === 0;
-        // Bind the receipt to the driver log actually produced, so "the run passed"
-        // is checkable against bytes rather than taken on trust.
-        const logArtifacts = recordRunArtifacts(evidence, path.join(runRoot, 'wdio'));
-        addEvidenceCheck(evidence, {
-            name: 'wdio.run',
-            status: passed ? 'passed' : 'failed',
-            artifacts: logArtifacts,
-            details: {
-                code: result.code,
-                signal: result.signal,
-                stdoutTail: tail(result.stdout),
-                stderrTail: tail(result.stderr),
-            },
-        });
-        finishEvidenceBundle(evidence, { status: passed ? 'passed' : 'failed' });
-        writeEvidenceBundle(evidencePath, evidence);
-        return { exitCode: passed ? 0 : 1, evidencePath };
-    }
-    catch (error) {
-        addEvidenceCheck(evidence, {
-            name: 'wdio.run',
-            status: 'failed',
-            details: { error: error instanceof Error ? error.message : String(error) },
-        });
-        finishEvidenceBundle(evidence, { status: 'failed' });
-        writeEvidenceBundle(evidencePath, evidence);
-        throw error;
-    }
-    finally {
-        ownership.release();
-    }
-}
-export async function loadRightQaConfig(configPath) {
-    const resolved = path.resolve(configPath);
-    const loaded = await import(`${pathToFileURL(resolved).href}?t=${Date.now()}`);
-    if (!loaded.default)
-        throw new Error(`${resolved} must export a default RightKit QA config`);
-    return defineRightQaConfig(loaded.default);
-}
-async function main(argv = process.argv.slice(2)) {
-    const command = argv[0];
-    const configArg = valueAfter(argv, '--config') ?? 'right-qa.config.mjs';
-    if (command === 'doctor') {
-        const config = await loadRightQaConfig(configArg);
-        process.stdout.write(`right-qa config valid: ${config.app}\n`);
-        return 0;
-    }
-    if (command === 'native') {
-        const config = await loadRightQaConfig(configArg);
-        const result = await runNativeQa(config);
-        process.stdout.write(`right-qa evidence: ${result.evidencePath}\n`);
-        return result.exitCode;
-    }
-    throw new Error('usage: right-qa <doctor|native> [--config right-qa.config.mjs]');
-}
-function resolveWdioBin() {
-    const require = createRequire(import.meta.url);
-    const entry = require.resolve('@wdio/cli');
-    return path.resolve(path.dirname(entry), '../bin/wdio.js');
-}
-function resolveUndiciEntry() {
-    const require = createRequire(import.meta.url);
-    return pathToFileURL(require.resolve('undici')).href;
-}
-function requireDesktopPlatform() {
-    if (process.platform === 'win32' || process.platform === 'darwin')
-        return process.platform;
-    throw new Error(`Right Suite native QA supports Windows and macOS, received ${process.platform}`);
-}
-function valueAfter(argv, flag) {
-    const index = argv.indexOf(flag);
-    return index >= 0 ? argv[index + 1] : undefined;
-}
-/**
- * Hash whatever the driver actually wrote. Missing logs are simply not recorded
- * — a check that references nothing is honest; a check that references a file
- * that was never hashed is refused by addEvidenceCheck.
- */
-function recordRunArtifacts(evidence, logDir) {
-    const names = [];
-    let entries;
-    try {
-        entries = fs.readdirSync(logDir);
-    }
-    catch {
-        return names;
-    }
-    for (const entry of entries.sort()) {
-        const file = path.join(logDir, entry);
-        try {
-            if (!fs.statSync(file).isFile())
-                continue;
-            addEvidenceArtifact(evidence, { name: `wdio/${entry}`, path: file });
-            names.push(`wdio/${entry}`);
-        }
-        catch {
-            // An unreadable log is not evidence; leaving it unreferenced is the point.
-        }
-    }
-    return names;
-}
-function tail(value, maxLength = 4_000) {
-    return value.length <= maxLength ? value : value.slice(-maxLength);
-}
-if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
-    main().then((code) => { process.exitCode = code; }, (error) => {
-        process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
-        process.exitCode = 1;
-    });
-}

package/dist/native.d.ts

@@ -1,37 +0,0 @@
-export interface RightQaConfig {
-    app: string;
-    appRoot: string;
-    windowLabel: string;
-    specs: string[];
-    binaries: {
-        win32: string;
-        darwin: string;
-    };
-    evidenceDir?: string;
-}
-export interface NativeQaRuntimeOptions {
-    platform?: 'win32' | 'darwin';
-    embeddedPort?: number;
-}
-export interface WdioNativeConfig {
-    runner: 'local';
-    specs: string[];
-    maxInstances: 1;
-    maxInstancesPerCapability: 1;
-    services: Array<[string, Record<string, unknown>]>;
-    capabilities: Array<Record<string, unknown>>;
-    framework: 'mocha';
-    reporters: string[];
-    mochaOpts: {
-        ui: 'bdd';
-        timeout: number;
-    };
-    logLevel: 'error';
-    bail: number;
-    waitforTimeout: number;
-    connectionRetryTimeout: number;
-    connectionRetryCount: number;
-    outputDir: string;
-}
-export declare function defineRightQaConfig(input: RightQaConfig): RightQaConfig;
-export declare function createWdioConfig(rawConfig: RightQaConfig, options?: NativeQaRuntimeOptions): WdioNativeConfig;

package/dist/native.js

@@ -1,78 +0,0 @@
-import path from 'node:path';
-export function defineRightQaConfig(input) {
-    const app = requireText(input.app, 'app');
-    if (!/^[a-z][a-z0-9-]*$/.test(app))
-        throw new Error('app must be a lowercase app key');
-    const appRoot = path.resolve(requireText(input.appRoot, 'appRoot'));
-    const specs = input.specs.map((spec) => requireText(spec, 'spec'));
-    if (specs.length === 0)
-        throw new Error('at least one native QA spec is required');
-    return Object.freeze({
-        ...input,
-        app,
-        appRoot,
-        windowLabel: requireText(input.windowLabel, 'windowLabel'),
-        specs: Object.freeze([...specs]),
-        binaries: Object.freeze({
-            win32: requireText(input.binaries.win32, 'win32 binary'),
-            darwin: requireText(input.binaries.darwin, 'darwin binary'),
-        }),
-    });
-}
-export function createWdioConfig(rawConfig, options = {}) {
-    const app = defineRightQaConfig(rawConfig);
-    const platform = options.platform ?? currentDesktopPlatform();
-    const embeddedPort = options.embeddedPort ?? 4445;
-    if (!Number.isInteger(embeddedPort) || embeddedPort < 1024 || embeddedPort > 65_535) {
-        throw new Error(`invalid embedded WebDriver port: ${embeddedPort}`);
-    }
-    const appBinaryPath = path.resolve(app.appRoot, app.binaries[platform]);
-    const evidenceRoot = path.resolve(app.appRoot, app.evidenceDir ?? '.cache/rightkit-qa');
-    return {
-        runner: 'local',
-        specs: app.specs.map((spec) => path.resolve(app.appRoot, spec)),
-        maxInstances: 1,
-        maxInstancesPerCapability: 1,
-        services: [[
-                '@wdio/tauri-service',
-                {
-                    appBinaryPath,
-                    driverProvider: 'embedded',
-                    embeddedPort,
-                    windowLabel: app.windowLabel,
-                    autoInstallTauriDriver: false,
-                    autoDownloadEdgeDriver: true,
-                    captureBackendLogs: false,
-                    captureFrontendLogs: false,
-                    startTimeout: 60_000,
-                    statusPollTimeout: 5_000,
-                    commandTimeout: 30_000,
-                    logDir: path.join(evidenceRoot, 'service'),
-                },
-            ]],
-        capabilities: [{
-                browserName: 'tauri',
-                'tauri:options': { application: appBinaryPath },
-            }],
-        framework: 'mocha',
-        reporters: ['spec'],
-        mochaOpts: { ui: 'bdd', timeout: 60_000 },
-        logLevel: 'error',
-        bail: 1,
-        waitforTimeout: 10_000,
-        connectionRetryTimeout: 90_000,
-        connectionRetryCount: 1,
-        outputDir: path.join(evidenceRoot, 'wdio'),
-    };
-}
-function currentDesktopPlatform() {
-    if (process.platform === 'win32' || process.platform === 'darwin')
-        return process.platform;
-    throw new Error(`Right Suite native QA currently supports Windows and macOS, received ${process.platform}`);
-}
-function requireText(value, name) {
-    const normalized = value.trim();
-    if (!normalized)
-        throw new Error(`${name} is required`);
-    return normalized;
-}