@rightkit/qa 0.3.1 → 0.3.2

package/README.md

@@ -6,6 +6,14 @@ Shared QA primitives for Right Suite desktop apps. The package owns run locking,
 
 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.
 
+## Run storage
+
+Run roots, harness evidence, captures & summaries remain under `<managed>/runs/<app>/<run-id>`. App homes, profiles, service/port files, live logs & app-provided output paths use an owned internal system-temp companion recorded as `appRoot` in `.rightkit-run.json`. On macOS, companions always use `/private/tmp/rightkit-qa/<app-prefix>-<random>` with short names so launchd can open app files & control socket paths fit `sockaddr_un`.
+
+Finish copies app logs to managed `evidence/`, app-written evidence to `evidence/app/` & app captures to `captures/` before releasing ownership. Disposal removes temp companions; failed copies or cleanup preserve ownership metadata for recovery. Retention & orphan pruning validate companion bindings & protect live runs.
+
+Workspace env sets `RIGHTKIT_RUN_ROOT`, `HOME` & `USERPROFILE` to `home`; `RIGHTKIT_SUITE_ROOT` to `home/suite`; data/profile keys to `home/data`; `XDG_CACHE_HOME` to `home/cache`; `TMPDIR`, `TMP` & `TEMP` to `home/tmp`. `RIGHTKIT_QA_EVIDENCE_DIR` & `RIGHTKIT_QA_CAPTURE_DIR` use `home/evidence` & `home/captures`. The JS package supplies workspace env; native UI bundle staging & unique per-launch suite/service identity belong to Rust `control::launch`.
+
 ## 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.

package/dist/storage.d.ts

@@ -10,6 +10,8 @@ export interface RunMarker {
     ownerPid: number;
     leaseUntil: number;
     completedAt?: number;
+    /** Owned internal-temp companion; validated against its binding before cleanup. */
+    appRoot?: string;
 }
 export interface ManagedRun {
     root: string;
@@ -48,3 +50,7 @@ export declare function createManagedRun(options: {
 }): ManagedRun;
 export declare function finishManagedRun(run: ManagedRun | string): RunMarker | undefined;
 export declare function pruneManagedRuns(managedRoot: string, app: string, policy?: RetentionPolicy): RetentionReport;
+/** Short internal paths keep launchd files accessible & service sockets within sockaddr_un. */
+export declare function appTempDir(): string;
+export declare function createManagedAppRoot(run: ManagedRun): string;
+export declare function removeManagedAppRoot(root: string, marker: RunMarker): void;

package/dist/storage.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 export const RUN_MARKER = '.rightkit-run.json';
 export const DEFAULT_RETENTION_BYTES = 20_000_000_000;
@@ -10,9 +11,12 @@ export function resolveManagedRoot(explicit) {
         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';
+    const [workstation, volume] = process.platform === 'win32' ? ['D:\\.rightkit-managed', 'D:\\'] : ['/Volumes/D/.rightkit-managed', '/Volumes/D'];
+    if (fs.existsSync(volume))
+        return path.resolve(workstation);
+    // Hosted CI and other machines: runner temp, then the system temp dir.
+    const runnerTemp = process.env.RUNNER_TEMP?.trim();
+    return path.join(runnerTemp && fs.existsSync(runnerTemp) ? runnerTemp : os.tmpdir(), 'rightkit-managed');
 }
 export function safeKey(value, name) {
     const v = String(value ?? '').trim();
@@ -69,6 +73,14 @@ export function finishManagedRun(run) {
     const marker = readMarker(markerPath);
     if (!marker)
         return undefined;
+    const home = ownedAppRoot(root, marker);
+    if (home) {
+        copyAppTree(path.join(home, 'evidence'), path.join(root, 'evidence', 'app'));
+        copyAppTree(path.join(home, 'captures'), path.join(root, 'captures'));
+        for (const name of fs.readdirSync(home))
+            if (name.endsWith('.log'))
+                copyAppTree(path.join(home, name), path.join(root, 'evidence', name));
+    }
     const finished = { ...marker, ownerPid: 0, leaseUntil: 0, completedAt: Date.now() };
     writeMarker(root, finished);
     return finished;
@@ -149,6 +161,7 @@ function pruneUnlocked(appRoot, app, policy, report) {
         if (!safeDirectory(item.root))
             continue;
         try {
+            removeManagedAppRoot(item.root, item.marker);
             fs.rmSync(item.root, { recursive: true, force: false });
             report.removed.push(item.root);
             removed.add(item.marker.runId);
@@ -226,6 +239,8 @@ function readMarker(file) {
             return undefined;
         if (x.completedAt !== undefined && (typeof x.completedAt !== 'number' || !Number.isFinite(x.completedAt) || x.completedAt < 0))
             return undefined;
+        if (x.appRoot !== undefined && typeof x.appRoot !== 'string')
+            return undefined;
         return x;
     }
     catch {
@@ -313,3 +328,53 @@ function describeError(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)}`; }
+/** Short internal paths keep launchd files accessible & service sockets within sockaddr_un. */
+export function appTempDir() {
+    return process.platform === 'darwin' ? '/private/tmp' : fs.realpathSync(os.tmpdir());
+}
+export function createManagedAppRoot(run) {
+    const parent = path.join(appTempDir(), 'rightkit-qa');
+    ensureSafeDirectory(parent);
+    const home = fs.mkdtempSync(path.join(parent, `${run.app.slice(0, 16)}-`));
+    fs.writeFileSync(path.join(home, '.rightkit-app.json'), JSON.stringify({ runRoot: fs.realpathSync(run.root), app: run.app, runId: run.runId }), { flag: 'wx' });
+    run.marker.appRoot = home;
+    writeMarker(run.root, run.marker);
+    return home;
+}
+function ownedAppRoot(root, marker) {
+    const home = marker.appRoot;
+    if (!home || !fs.existsSync(home))
+        return undefined;
+    const parent = path.dirname(home);
+    const temp = path.dirname(parent);
+    const allowedTemp = temp === appTempDir() || process.platform === 'darwin' && (temp === '/private/tmp' || isInside('/private/var/folders', temp) && path.basename(temp) === 'T');
+    if (path.basename(parent) !== 'rightkit-qa' || !allowedTemp || fs.realpathSync(home) !== home || !safeDirectory(home))
+        throw new Error('invalid QA app temp root');
+    const binding = JSON.parse(fs.readFileSync(path.join(home, '.rightkit-app.json'), 'utf8'));
+    if (binding.runRoot !== fs.realpathSync(root) || binding.app !== marker.app || binding.runId !== marker.runId)
+        throw new Error('QA app temp ownership mismatch');
+    return home;
+}
+export function removeManagedAppRoot(root, marker) {
+    const home = ownedAppRoot(root, marker);
+    if (home)
+        fs.rmSync(home, { recursive: true, force: false });
+}
+function copyAppTree(source, target) {
+    const meta = fs.lstatSync(source);
+    if (meta.isSymbolicLink())
+        throw new Error('symlink in QA app evidence');
+    if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink())
+        throw new Error('symlink in managed QA evidence');
+    if (meta.isDirectory()) {
+        ensureSafeDirectory(target);
+        for (const name of fs.readdirSync(source))
+            copyAppTree(path.join(source, name), path.join(target, name));
+    }
+    else if (meta.isFile()) {
+        ensureSafeDirectory(path.dirname(target));
+        fs.copyFileSync(source, target);
+    }
+    else
+        throw new Error('unsupported QA app evidence file');
+}

package/dist/workspace.d.ts

@@ -4,6 +4,8 @@ export interface QaWorkspace {
     appKey: string;
     managedRoot: string;
     root: string;
+    /** Owned app home on internal system temp storage. */
+    home: 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. */

package/dist/workspace.js

@@ -17,35 +17,49 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { createManagedRun, finishManagedRun, pruneManagedRuns, resolveManagedRoot, } from './storage.js';
+import { createManagedRun, createManagedAppRoot, finishManagedRun, pruneManagedRuns, resolveManagedRoot, } from './storage.js';
 export function createQaWorkspace(options) {
     const appKey = requireText(options.appKey, 'appKey');
     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 home = createManagedAppRoot(managed);
+    const dataDir = path.join(home, 'data');
     const evidenceDir = path.join(root, 'evidence');
     const captureDir = path.join(root, 'captures');
-    const tmpDir = path.join(root, 'tmp');
+    const tmpDir = path.join(home, 'tmp');
+    const cacheDir = path.join(home, 'cache');
+    const appEvidenceDir = path.join(home, 'evidence');
+    const appCaptureDir = path.join(home, 'captures');
+    fs.mkdirSync(appEvidenceDir, { recursive: true });
+    fs.mkdirSync(appCaptureDir, { recursive: true });
     fs.mkdirSync(dataDir, { recursive: true });
     fs.mkdirSync(evidenceDir, { recursive: true });
     fs.mkdirSync(captureDir, { recursive: true });
     fs.mkdirSync(tmpDir, { recursive: true });
+    fs.mkdirSync(cacheDir, { recursive: true });
     return {
         runId,
         appKey,
         managedRoot: path.resolve(options.root ? requireText(options.root, 'root') : resolveManagedRoot()),
         root,
+        home,
         dataDir,
         evidenceDir,
         captureDir,
         env: {
             RIGHTKIT_QA_NATIVE: '1',
             RIGHTKIT_QA_RUN_ID: runId,
-            RIGHTKIT_RUN_ROOT: root,
+            RIGHTKIT_RUN_ROOT: home,
+            RIGHTKIT_SUITE_ROOT: path.join(home, 'suite'),
+            HOME: home,
+            USERPROFILE: home,
+            APPDATA: dataDir,
+            LOCALAPPDATA: dataDir,
+            XDG_CACHE_HOME: cacheDir,
             RIGHTKIT_QA_DATA_DIR: dataDir,
-            RIGHTKIT_QA_EVIDENCE_DIR: evidenceDir,
-            RIGHTKIT_QA_CAPTURE_DIR: captureDir,
+            RIGHTKIT_QA_EVIDENCE_DIR: appEvidenceDir,
+            RIGHTKIT_QA_CAPTURE_DIR: appCaptureDir,
             TMPDIR: tmpDir,
             TMP: tmpDir,
             TEMP: tmpDir,
@@ -68,13 +82,19 @@ export function disposeQaWorkspace(workspace, options = {}) {
     const attempts = Math.max(1, options.attempts ?? 5);
     const retryDelayMs = options.retryDelayMs ?? 200;
     const sleep = options.sleep ?? sleepSync;
-    const targets = options.keepEvidence ? [workspace.dataDir] : [workspace.root];
+    const targets = options.keepEvidence ? [workspace.home] : [workspace.home, workspace.root];
     const report = { removed: [], retained: [] };
-    finishManagedRun(workspace.root);
+    try {
+        finishManagedRun(workspace.root);
+    }
+    catch (error) {
+        report.retained.push({ path: workspace.root, reason: describeError(error) });
+        return report;
+    }
     for (const target of targets) {
-        // Only ever remove inside the workspace root we created.
+        // Only remove the managed run or its registered temp companion.
         const resolved = path.resolve(target);
-        if (resolved !== path.resolve(workspace.root) && !isInside(workspace.root, resolved)) {
+        if (resolved !== path.resolve(workspace.root) && resolved !== path.resolve(workspace.home)) {
             report.retained.push({ path: resolved, reason: 'outside the QA workspace root' });
             continue;
         }
@@ -97,8 +117,14 @@ export function disposeQaWorkspace(workspace, options = {}) {
         }
         if (lastError === undefined && !fs.existsSync(resolved))
             report.removed.push(resolved);
-        else
+        else {
             report.retained.push({ path: resolved, reason: describeError(lastError) });
+            if (resolved === path.resolve(workspace.home)) {
+                if (!options.keepEvidence)
+                    report.retained.push({ path: workspace.root, reason: 'app temp cleanup pending' });
+                break;
+            }
+        }
     }
     return report;
 }
@@ -130,10 +156,6 @@ export function pruneAbandonedWorkspaces(root, { olderThanMs, now = Date.now(),
     }
     return report;
 }
-function isInside(root, candidate) {
-    const relative = path.relative(path.resolve(root), path.resolve(candidate));
-    return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
-}
 function describeError(error) {
     if (error === undefined)
         return 'still present after removal reported success';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/qa",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Shared QA evidence, ownership, browser helpers, and release-backdoor guards for Right Suite apps.",
   "license": "MIT OR Apache-2.0",
   "type": "module",