playwright-intelligence-engine 0.0.0-stage → 2.0.1

package/src/sandbox/worktree-manager.ts

@@ -0,0 +1,287 @@
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { WorktreeOperationError } from '../core/errors/engine-errors.js';
+import { DependencyStrategyResolver, IsolationLevel } from './dependency-strategy.js';
+
+const execFileAsync = promisify(execFile);
+
+export interface WorktreeInfo {
+  id: string;
+  worktreePath: string;
+  branch: string;
+  createdAt: number;
+  ownerPid: number;
+  isolationLevel: IsolationLevel;
+  strategy: string;
+}
+
+export interface WorktreeRegistry {
+  worktrees: Record<string, WorktreeInfo>;
+}
+
+export class WorktreeManager {
+  private readonly rootDir: string;
+  private readonly baseWorktreeDir: string;
+  private readonly registryPath: string;
+
+  constructor(rootDir: string) {
+    this.rootDir = path.resolve(rootDir);
+    this.baseWorktreeDir = path.resolve(this.rootDir, '.pw-intelligence', 'worktrees');
+    this.registryPath = path.resolve(this.baseWorktreeDir, 'registry.json');
+  }
+
+  private static readonly VALID_ID_REGEX = /^[a-zA-Z0-9_-]{1,64}$/;
+
+  /**
+   * Checks whether a given process ID is currently alive on the host system.
+   */
+  public static isProcessAlive(pid: number): boolean {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Asserts that a worktree ID is valid and that the resolved path is strictly contained
+   * within the base worktree directory using canonical real paths (AUDIT-05 / AUDIT-06).
+   * Prevents symlink/junction escape, directory traversal, and recursive host deletion.
+   */
+  private assertWorktreeContainment(id: string): string {
+    if (!WorktreeManager.VALID_ID_REGEX.test(id)) {
+      throw new WorktreeOperationError(
+        'validate-id',
+        `Security Violation: Invalid worktree ID '${id}'. Must match /^[a-zA-Z0-9_-]{1,64}$/`
+      );
+    }
+
+    fsSync.mkdirSync(this.baseWorktreeDir, { recursive: true });
+    let canonicalBase: string;
+    try {
+      canonicalBase = fsSync.realpathSync(this.baseWorktreeDir);
+    } catch (err: any) {
+      throw new WorktreeOperationError(
+        'containment',
+        `Security Violation: Failed to resolve canonical realpath of base worktree directory '${this.baseWorktreeDir}': ${err.message}`
+      );
+    }
+
+    const worktreePath = path.resolve(canonicalBase, id);
+    const rel = path.relative(canonicalBase, worktreePath);
+
+    if (rel.startsWith('..') || path.isAbsolute(rel) || rel === '') {
+      throw new WorktreeOperationError(
+        'containment',
+        `Security Violation: Worktree path '${worktreePath}' escapes base worktree directory '${canonicalBase}'.`
+      );
+    }
+
+    if (fsSync.existsSync(worktreePath)) {
+      try {
+        const canonicalWorktree = fsSync.realpathSync(worktreePath);
+        const relWorktree = path.relative(canonicalBase, canonicalWorktree);
+        if (relWorktree.startsWith('..') || path.isAbsolute(relWorktree)) {
+          throw new WorktreeOperationError(
+            'containment',
+            `Security Violation: Canonical worktree '${canonicalWorktree}' escapes base worktree directory '${canonicalBase}'.`
+          );
+        }
+        return canonicalWorktree;
+      } catch (err: any) {
+        if (err instanceof WorktreeOperationError) throw err;
+        throw new WorktreeOperationError(
+          'containment',
+          `Security Violation: Failed to resolve canonical realpath of worktree '${worktreePath}': ${err.message}`
+        );
+      }
+    }
+
+    return worktreePath;
+  }
+
+  /**
+   * Creates an isolated detached Git worktree using the appropriate DependencyStrategy.
+   * Enforces fail-closed dependency validation (AUDIT-16).
+   */
+  public async createWorktree(worktreeId?: string): Promise<WorktreeInfo> {
+    const id = worktreeId ?? `repair-${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 7)}`;
+    const worktreePath = this.assertWorktreeContainment(id);
+    const branch = `pw-repair/${id}`;
+
+    await fs.mkdir(this.baseWorktreeDir, { recursive: true });
+
+    // Step 1: Detect dirty workspace state and create snapshot if uncommitted changes exist
+    let baseRef = 'HEAD';
+    let untrackedFiles: string[] = [];
+
+    try {
+      const { stdout: statusOut } = await execFileAsync('git', ['status', '--porcelain'], { cwd: this.rootDir });
+      const isDirty = statusOut.trim().length > 0;
+
+      if (isDirty) {
+        // Create an in-memory commit representing the exact staged and unstaged state without touching workspace
+        const { stdout: stashSha } = await execFileAsync('git', ['stash', 'create'], { cwd: this.rootDir });
+        const trimmedSha = stashSha.trim();
+        if (trimmedSha) {
+          baseRef = trimmedSha;
+        }
+
+        // Identify untracked, non-ignored files to mirror
+        const { stdout: untrackedOut } = await execFileAsync('git', ['ls-files', '--others', '--exclude-standard'], { cwd: this.rootDir });
+        untrackedFiles = untrackedOut.split('\n').map((f) => f.trim()).filter(Boolean);
+      }
+    } catch {
+      // Fall back to HEAD if status check encounters a non-git environment
+      baseRef = 'HEAD';
+    }
+
+    // Step 2: Create Git worktree
+    try {
+      await execFileAsync('git', ['worktree', 'add', '-b', branch, worktreePath, baseRef], {
+        cwd: this.rootDir,
+      });
+    } catch (err: any) {
+      throw new WorktreeOperationError('create', `Git worktree add failed: ${err.message}`);
+    }
+
+    // Step 3: Mirror untracked files into worktree
+    if (untrackedFiles.length > 0) {
+      for (const relFile of untrackedFiles) {
+        try {
+          const src = path.resolve(this.rootDir, relFile);
+          const dest = path.resolve(worktreePath, relFile);
+          await fs.mkdir(path.dirname(dest), { recursive: true });
+          await fs.copyFile(src, dest);
+        } catch {
+          // Non-critical file copy failure
+        }
+      }
+    }
+
+    // Step 2: Prepare dependencies via DependencyStrategy and enforce validation (AUDIT-16)
+    const strategy = await DependencyStrategyResolver.resolve(this.rootDir);
+    let prepResult;
+    try {
+      prepResult = await strategy.prepare(this.rootDir, worktreePath);
+      // Validate dependency strategy isolation
+      const validation = await strategy.validate(worktreePath);
+      if (!validation.isValid) {
+        throw new Error(
+          `Dependency validation failed for '${prepResult.strategy}' (isolation: ${prepResult.isolationLevel}): ${validation.error ?? 'Unmet dependency requirements'}`
+        );
+      }
+    } catch (err: any) {
+      await this.destroyWorktree(id).catch(() => {});
+      throw new WorktreeOperationError('prepare-dependencies', err.message);
+    }
+
+    const info: WorktreeInfo = {
+      id,
+      worktreePath,
+      branch,
+      createdAt: Date.now(),
+      ownerPid: process.pid,
+      isolationLevel: prepResult.isolationLevel,
+      strategy: prepResult.strategy,
+    };
+
+    await this.registerWorktree(info);
+    return info;
+  }
+
+  /**
+   * Destroys an isolated worktree safely:
+   * 1. Unlinks the dependency junction/symlink FIRST (CRITICAL: prevents wiping root dependencies)
+   * 2. Runs git worktree remove
+   * 3. Deletes leftover branch
+   * 4. Cleans up registry
+   */
+  public async destroyWorktree(id: string): Promise<void> {
+    const worktreePath = this.assertWorktreeContainment(id);
+    const branch = `pw-repair/${id}`;
+
+    // Step 1: Cleanup dependency links via strategy
+    const strategy = await DependencyStrategyResolver.resolve(this.rootDir);
+    await strategy.cleanup(worktreePath).catch(() => {});
+
+    // Step 2: Git worktree remove
+    try {
+      await execFileAsync('git', ['worktree', 'remove', '--force', worktreePath], {
+        cwd: this.rootDir,
+      });
+    } catch {
+      // Fallback: prune if removal failed
+      await execFileAsync('git', ['worktree', 'prune'], { cwd: this.rootDir }).catch(() => {});
+    }
+
+    // Step 3: Resilient directory cleanup with backoff for Windows file locks
+    await this.resilientRemove(worktreePath).catch(() => {});
+
+    // Step 4: Delete temporary branch
+    try {
+      await execFileAsync('git', ['branch', '-D', branch], { cwd: this.rootDir });
+    } catch {
+      // Ignore if branch was already deleted
+    }
+
+    await this.unregisterWorktree(id);
+  }
+
+  /**
+   * Robust directory removal with exponential backoff to handle temporary
+   * Windows anti-virus or search indexer file locks.
+   */
+  private async resilientRemove(targetPath: string, maxRetries = 5): Promise<void> {
+    let delayMs = 100;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        await fs.rm(targetPath, { recursive: true, force: true });
+        return;
+      } catch (err: any) {
+        if (err.code === 'ENOENT') {
+          return;
+        }
+        if (attempt === maxRetries - 1) {
+          // Fallback: attempt sync removal or log warning
+          try {
+            fsSync.rmSync(targetPath, { recursive: true, force: true });
+            return;
+          } catch {
+            return;
+          }
+        }
+        await new Promise((res) => setTimeout(res, delayMs));
+        delayMs *= 2;
+      }
+    }
+  }
+
+  private async registerWorktree(info: WorktreeInfo): Promise<void> {
+    let reg: WorktreeRegistry = { worktrees: {} };
+    try {
+      const data = await fs.readFile(this.registryPath, 'utf-8');
+      reg = JSON.parse(data);
+    } catch {
+      // Default to empty registry if unreadable
+    }
+
+    reg.worktrees[info.id] = info;
+    await fs.writeFile(this.registryPath, JSON.stringify(reg, null, 2), 'utf-8');
+  }
+
+  private async unregisterWorktree(id: string): Promise<void> {
+    try {
+      const data = await fs.readFile(this.registryPath, 'utf-8');
+      const reg: WorktreeRegistry = JSON.parse(data);
+      delete reg.worktrees[id];
+      await fs.writeFile(this.registryPath, JSON.stringify(reg, null, 2), 'utf-8');
+    } catch {
+      // Ignore registry read errors
+    }
+  }
+}

package/src/selector/abstention-policy.ts

@@ -0,0 +1,175 @@
+import { ScoreBreakdown } from './selector-scorer.js';
+import { ResolvedElement } from '../trace/snapshot-resolver.js';
+
+export interface ScoredCandidate {
+  element: ResolvedElement;
+  breakdown: ScoreBreakdown;
+  locatorExpression?: string | undefined;
+  originalSelector?: string | undefined;
+  intendedAction?: string | undefined; // e.g. "click", "fill"
+  parentScopeVerified?: boolean | undefined;
+  disambiguationStrategy?: string | undefined;
+  disambiguationExplanation?: string | undefined;
+}
+
+export type DecisionStage =
+  | 'SUPPORTED_ELEMENT'
+  | 'TARGET_IDENTITY'
+  | 'STRICT_UNIQUENESS'
+  | 'ACTION_SEMANTICS'
+  | 'SCORE_CONFIDENCE'
+  | 'AMBIGUITY_DELTA'
+  | 'AUTHORIZED';
+
+export interface AbstentionDecision {
+  shouldAbstain: boolean;
+  stage: DecisionStage;
+  selectedCandidate?: ScoredCandidate | undefined;
+  reason?: string | undefined;
+}
+
+export class AbstentionPolicy {
+  public static readonly MINIMUM_CONFIDENCE_THRESHOLD = 0.70;
+  public static readonly AMBIGUITY_DELTA_THRESHOLD = 0.08;
+
+  /**
+   * Applies the formal Multi-Stage Decision Pipeline to candidate locators:
+   * 1. Supported Element? (Must be recognized interactive element)
+   * 2. Target Identity Verified? (Affinity to intended business entity)
+   * 3. Exactly One Scoped Match? (Strict Uniqueness: matchCount === 1, unless parentScopeVerified)
+   * 4. Action Semantics Preserved? (e.g. click -> clickable element, fill -> input/textarea)
+   * 5. Score & Calibrated Threshold Pass? (rawScore >= 0.70)
+   * 6. Ambiguity Delta Pass? (top.score - runnerUp.score >= 0.08)
+   */
+  public static evaluate(candidates: ScoredCandidate[]): AbstentionDecision {
+    if (candidates.length === 0) {
+      return {
+        shouldAbstain: true,
+        stage: 'SUPPORTED_ELEMENT',
+        reason: 'Zero matching candidate elements found in DOM snapshot',
+      };
+    }
+
+    // Sort descending by score
+    const sorted = [...candidates].sort((a, b) => b.breakdown.score - a.breakdown.score);
+    const top = sorted[0]!;
+
+    // Stage 1: Supported Element Check
+    const supportedTags = new Set([
+      'button',
+      'a',
+      'input',
+      'select',
+      'textarea',
+      'option',
+      'div',
+      'span',
+      'li',
+      'td',
+      'th',
+      'p',
+      'h1',
+      'h2',
+      'h3',
+      'h4',
+      'label',
+      'img',
+      'form',
+    ]);
+    if (!supportedTags.has(top.element.tag) && !top.element.role) {
+      return {
+        shouldAbstain: true,
+        stage: 'SUPPORTED_ELEMENT',
+        reason: `Unsupported DOM tag '<${top.element.tag}>' without ARIA role cannot be safely automated.`,
+      };
+    }
+
+    // Stage 2: Target Identity Verification
+    if (top.breakdown.identityMatch < 0.4) {
+      return {
+        shouldAbstain: true,
+        stage: 'TARGET_IDENTITY',
+        reason: `Target identity mismatch: candidate accessible name '${top.element.accessibleName ?? 'unnamed'}' does not align with original selector intent.`,
+      };
+    }
+
+    // Stage 3: Strict Uniqueness Gate (CRITICAL: matchCount !== 1 triggers ABSTAIN)
+    // Exactly 2 or more matches fail the uniqueness requirement unless parentScopeVerified is true
+    if (top.breakdown.matchCount !== 1 && !top.parentScopeVerified) {
+      return {
+        shouldAbstain: true,
+        stage: 'STRICT_UNIQUENESS',
+        reason: `NON_UNIQUE_CANDIDATE: Candidate element matches ${top.breakdown.matchCount} elements in DOM. Strict uniqueness requires exactly 1 match (U = 1.0) unless scoped by a verified parent container.`,
+      };
+    }
+
+    // Stage 4: Action Semantics Check
+    if (top.intendedAction) {
+      const action = top.intendedAction.toLowerCase();
+      if (action.includes('click')) {
+        const isClickable =
+          top.element.tag === 'button' ||
+          top.element.tag === 'a' ||
+          top.element.role === 'button' ||
+          top.element.role === 'link' ||
+          top.element.role === 'tab' ||
+          top.element.role === 'menuitem' ||
+          Boolean(top.element.attributes?.['onclick']) ||
+          Boolean(top.element.attributes?.['href']);
+
+        if (!isClickable && top.element.tag !== 'div' && top.element.tag !== 'span' && top.element.tag !== 'td') {
+          return {
+            shouldAbstain: true,
+            stage: 'ACTION_SEMANTICS',
+            reason: `Action semantics violation: action '${top.intendedAction}' cannot be safely dispatched to non-clickable element <${top.element.tag}>.`,
+          };
+        }
+      } else if (action.includes('fill') || action.includes('type')) {
+        const isInput =
+          top.element.tag === 'input' ||
+          top.element.tag === 'textarea' ||
+          top.element.role === 'textbox' ||
+          top.element.attributes['contenteditable'] === 'true';
+
+        if (!isInput) {
+          return {
+            shouldAbstain: true,
+            stage: 'ACTION_SEMANTICS',
+            reason: `Action semantics violation: fill/type action requires input or textbox element, but found <${top.element.tag}>.`,
+          };
+        }
+      }
+    }
+
+    // Stage 5: Confidence Threshold Gate
+    if (top.breakdown.score < AbstentionPolicy.MINIMUM_CONFIDENCE_THRESHOLD) {
+      return {
+        shouldAbstain: true,
+        stage: 'SCORE_CONFIDENCE',
+        reason: `Highest candidate confidence (${(top.breakdown.score * 100).toFixed(1)}%) is below minimum safety threshold (${(AbstentionPolicy.MINIMUM_CONFIDENCE_THRESHOLD * 100).toFixed(1)}%)`,
+      };
+    }
+
+    // Stage 6: Ambiguity Delta Gate (if top two candidates are neck and neck, guess is unsafe)
+    if (sorted.length > 1) {
+      const runnerUp = sorted[1]!;
+      const delta = parseFloat((top.breakdown.score - runnerUp.breakdown.score).toFixed(3));
+      const identitySeparation = top.breakdown.identityMatch - runnerUp.breakdown.identityMatch;
+      const hasStrongIdentitySeparation = top.breakdown.identityMatch >= 0.9 && identitySeparation >= 0.12;
+      if (delta < AbstentionPolicy.AMBIGUITY_DELTA_THRESHOLD && !hasStrongIdentitySeparation) {
+        return {
+          shouldAbstain: true,
+          stage: 'AMBIGUITY_DELTA',
+          reason: `Ambiguous match: top two candidate elements have nearly identical scores (${top.breakdown.score} vs ${runnerUp.breakdown.score}, delta: ${delta.toFixed(3)} < threshold ${AbstentionPolicy.AMBIGUITY_DELTA_THRESHOLD}). Abstaining to prevent incorrect action dispatch.`,
+        };
+      }
+    }
+
+    return {
+      shouldAbstain: false,
+      stage: 'AUTHORIZED',
+      selectedCandidate: top,
+    };
+  }
+}
+