@rightkit/qa 0.3.0 → 0.3.1

package/dist/index.d.ts

@@ -8,3 +8,4 @@ export * from './paint.js';
 export * from './panes.js';
 export * from './process.js';
 export * from './workspace.js';
+export * from './storage.js';

package/dist/index.js

@@ -8,3 +8,4 @@ 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,6 +1,6 @@
 {
   "name": "@rightkit/qa",
-  "version": "0.3.0",
+  "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",
@@ -24,7 +24,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@rightkit/qa-chrome": "0.1.2"
+    "@rightkit/qa-chrome": "0.1.3"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -43,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"
   }
 }