session-orchestrator 3.16.0

package/scripts/lib/playwright-driver/runner.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+/**
+ * playwright-driver/runner.mjs — Phase 2 entry-point for the /test command.
+ *
+ * Spawns `npx playwright test` in the target repo directory, pipes output to
+ * ${RUN_DIR}/console.log, and exits with a deterministic exit code per the
+ * Composability Contract in skills/playwright-driver/SKILL.md.
+ *
+ * Exit codes:
+ *   0 — all tests passed
+ *   1 — at least one test failed (Playwright exit 1)
+ *   2 — framework error, timeout, spawn failure, or invalid profile
+ *
+ * CLI args (all also accepted via env vars as fallback):
+ *   --run-dir <path>   absolute path to artifact dir  (env: RUN_DIR)
+ *   --profile <name>   profile name, e.g. "web-gate"  (env: PROFILE)
+ *   --target <path>    absolute path to target repo    (env: TARGET)
+ *   --dry-run          print resolved command, skip subprocess, exit 0
+ *
+ * DI seams for testability (all optional, accepted via opts object):
+ *   opts.spawn   — override node:child_process spawn
+ *   opts.fs      — override node:fs (sync subset: mkdirSync, createWriteStream, readFileSync, existsSync, writeFileSync)
+ *
+ * Issue: #385 — web-gate end-to-end proof against an EspoCRM web target
+ */
+
+import { spawn as realSpawn } from 'node:child_process';
+import realFs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { getProfile, loadProfiles, validateProfile } from '../profiles/registry.mjs';
+import { validatePathInsideProject } from '../path-utils.mjs';
+
+// ---------------------------------------------------------------------------
+// Path resolution helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Expand a leading `~` to $HOME; absolute paths pass through verbatim;
+ * relative paths are resolved against process.cwd().
+ * @param {string} p
+ * @returns {string}
+ */
+function resolvePath(p) {
+  if (!p) return process.cwd();
+  if (p.startsWith('~/') || p === '~') {
+    return path.join(os.homedir(), p.slice(1));
+  }
+  if (path.isAbsolute(p)) return p;
+  return path.resolve(process.cwd(), p);
+}
+
+// ---------------------------------------------------------------------------
+// axe-core presence check
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether @axe-core/playwright is listed in the target's package.json.
+ * Returns true if present (or if package.json cannot be read — fail-open).
+ * @param {string} targetPath
+ * @param {{ readFileSync: Function, existsSync: Function }} fsImpl
+ * @returns {{ present: boolean, skipped: boolean }}
+ */
+function checkAxeCore(targetPath, fsImpl) {
+  const pkgPath = path.join(targetPath, 'package.json');
+  if (!fsImpl.existsSync(pkgPath)) {
+    return { present: false, skipped: true };
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(fsImpl.readFileSync(pkgPath, 'utf8'));
+  } catch {
+    return { present: false, skipped: true };
+  }
+  const deps = pkg.dependencies ?? {};
+  const devDeps = pkg.devDependencies ?? {};
+  const present = '@axe-core/playwright' in deps || '@axe-core/playwright' in devDeps;
+  return { present, skipped: false };
+}
+
+// ---------------------------------------------------------------------------
+// Main run() function
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {object} [opts]
+ * @param {Function} [opts.spawn]
+ * @param {object}   [opts.fs]
+ * @returns {Promise<void>}
+ */
+export default async function run(opts = {}) {
+  const spawnFn = opts.spawn ?? realSpawn;
+  const fsImpl = opts.fs ?? realFs;
+
+  // -------------------------------------------------------------------------
+  // Parse CLI args + env fallbacks
+  // -------------------------------------------------------------------------
+
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      'run-dir': { type: 'string' },
+      'profile': { type: 'string' },
+      'target': { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    strict: false,
+  });
+
+  const runDir = resolvePath(values['run-dir'] ?? process.env.RUN_DIR ?? '');
+  const profileName = values['profile'] ?? process.env.PROFILE ?? '';
+  const targetRaw = values['target'] ?? process.env.TARGET ?? '';
+  const dryRun = values['dry-run'] ?? false;
+
+  if (!runDir) {
+    console.error('runner: --run-dir (or env RUN_DIR) is required');
+    process.exit(2);
+  }
+
+  // SEC-PD-MED-2: reject runDir values containing commas or colons as defensive
+  // path-sanitization (original rationale: reporter comma+colon split is now obsolete
+  // after the 2026-05-14 deep-3 reporter fix — paths flow via env vars, not CLI string).
+  // Kept as belt-and-braces against pathological run-dirs; revisit alongside #390 path-traversal.
+  if (/[,:]/.test(runDir)) {
+    console.error('runner: --run-dir must not contain commas or colons');
+    process.exit(2);
+  }
+
+  // #398 / #402: path-traversal guard — runDir must be strictly inside
+  // .orchestrator/metrics/test-runs/ relative to cwd (CWE-22).
+  // Delegated to validatePathInsideProject (two-phase: lexical + realpath).
+  const testRunsRoot = path.resolve(process.cwd(), '.orchestrator/metrics/test-runs');
+  const result = validatePathInsideProject(runDir, testRunsRoot);
+  if (!result.ok) {
+    if (result.reason === 'symlink') {
+      console.error('runner: --run-dir resolves (via symlink) outside .orchestrator/metrics/test-runs');
+    } else {
+      console.error(`runner: --run-dir must be inside .orchestrator/metrics/test-runs/ (got: ${runDir})`);
+    }
+    process.exit(2);
+  }
+
+  if (!profileName) {
+    console.error('runner: --profile (or env PROFILE) is required');
+    process.exit(2);
+  }
+
+  // -------------------------------------------------------------------------
+  // Load + validate profile
+  // -------------------------------------------------------------------------
+
+  const loadResult = await loadProfiles();
+  if (!loadResult.ok) {
+    console.error(`runner: failed to load profiles — ${loadResult.error.message}`);
+    process.exit(2);
+  }
+
+  const getResult = getProfile(loadResult.profiles, profileName);
+  if (!getResult.ok) {
+    console.error(`runner: ${getResult.error.message}`);
+    process.exit(2);
+  }
+
+  const validateResult = validateProfile(getResult.profile);
+  if (!validateResult.ok) {
+    console.error(`runner: profile '${profileName}' is invalid — ${validateResult.error.message}`);
+    process.exit(2);
+  }
+
+  const profile = validateResult.value;
+
+  // -------------------------------------------------------------------------
+  // Resolve target path
+  // -------------------------------------------------------------------------
+
+  const targetPath = resolvePath(targetRaw || profile.target || process.cwd());
+
+  // -------------------------------------------------------------------------
+  // axe-core presence check
+  // -------------------------------------------------------------------------
+
+  const axe = checkAxeCore(targetPath, fsImpl);
+  if (!axe.present && !axe.skipped) {
+    console.log('axe-violations: skipped — @axe-core/playwright not installed in target');
+  }
+
+  // -------------------------------------------------------------------------
+  // Build Playwright args
+  // -------------------------------------------------------------------------
+
+  // Playwright reporter syntax: comma-separated reporter NAMES, paths via env vars.
+  // Canonical: https://playwright.dev/docs/test-reporters#html-reporter (PLAYWRIGHT_HTML_OUTPUT_DIR)
+  // and #json-reporter (PLAYWRIGHT_JSON_OUTPUT_FILE). The previous `html:<path>` form
+  // was Jest/Vitest syntax — Playwright rejected it as `Cannot find module 'html:<path>'`.
+  const playwrightArgs = [
+    'playwright',
+    'test',
+    '--output', path.join(runDir, 'test-results'),
+    '--reporter', 'html,json',
+    '--trace', 'on',
+  ];
+
+  if (profile.mode === 'headed') {
+    playwrightArgs.push('--headed');
+  }
+
+  if (dryRun) {
+    console.log('runner: dry-run mode — resolved command:');
+    console.log(`  npx ${playwrightArgs.join(' ')}`);
+    console.log(`  cwd: ${targetPath}`);
+    process.exit(0);
+  }
+
+  // -------------------------------------------------------------------------
+  // Create artifact directories
+  // -------------------------------------------------------------------------
+
+  fsImpl.mkdirSync(path.join(runDir, 'test-results'), { recursive: true });
+
+  // #396: pre-create artifact namespace directories so test fixtures don't fail
+  // on missing parent paths. `test-results/` is created by Playwright via --output.
+  // `console.log` is created by createWriteStream below. AX + screenshots dirs are
+  // written by fixtures — pre-creating ensures a clean artifact layout on every run.
+  fsImpl.mkdirSync(path.join(runDir, 'ax-snapshots'), { recursive: true });
+  fsImpl.mkdirSync(path.join(runDir, 'screenshots'), { recursive: true });
+
+  // -------------------------------------------------------------------------
+  // Spawn Playwright
+  // -------------------------------------------------------------------------
+
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(
+    () => controller.abort(),
+    profile.timeout_ms,
+  );
+
+  const logStream = fsImpl.createWriteStream(path.join(runDir, 'console.log'), { flags: 'a' });
+
+  const proc = spawnFn('npx', playwrightArgs, {
+    cwd: targetPath,
+    signal: controller.signal,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: {
+      ...process.env,
+      PLAYWRIGHT_HTML_OUTPUT_DIR: path.join(runDir, 'report'),
+      PLAYWRIGHT_JSON_OUTPUT_FILE: path.join(runDir, 'results.json'),
+      PLAYWRIGHT_HTML_OPEN: 'never',
+    },
+  });
+
+  proc.stdout.pipe(logStream, { end: false });
+  proc.stderr.pipe(logStream, { end: false });
+
+  // -------------------------------------------------------------------------
+  // Exit-code resolution
+  // -------------------------------------------------------------------------
+
+  /**
+   * @param {number} mapped
+   */
+  function finish(mapped) {
+    clearTimeout(timeoutHandle);
+    logStream.end(() => {
+      fsImpl.writeFileSync(path.join(runDir, 'exit_code'), String(mapped));
+      process.exit(mapped);
+    });
+  }
+
+  proc.on('error', (err) => {
+    console.error(`runner: spawn error — ${err.message}`);
+    finish(2);
+  });
+
+  proc.on('close', (code, signal) => {
+    if (signal === 'SIGTERM' || code === null) {
+      finish(2);
+    } else if (code === 0) {
+      finish(0);
+    } else if (code === 1) {
+      finish(1);
+    } else {
+      finish(2);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry-point
+// ---------------------------------------------------------------------------
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run().catch((err) => {
+    console.error(`runner: unhandled error — ${err.message}`);
+    process.exit(2);
+  });
+}

package/scripts/lib/plugin-root.mjs

@@ -0,0 +1,210 @@
+/**
+ * plugin-root.mjs — Robust plugin root resolution with layered fallback.
+ *
+ * Issue #212: manual installs may not have CLAUDE_PLUGIN_ROOT set. This module
+ * provides a deterministic, testable resolution strategy so hook handlers and
+ * scripts never silently fall back to an empty path or wrong directory.
+ *
+ * Fallback order (stops at first success):
+ *   1. PLUGIN_ROOT native env var
+ *   2. Compatibility root matching explicit SO_PLATFORM
+ *   3. Remaining Claude, Codex, Cursor, and Pi compatibility roots
+ *   4. Walk up from import.meta.url looking for package.json whose name === "session-orchestrator"
+ *   5. Walk up from process.cwd() looking for the same marker
+ *
+ * Throws PluginRootResolutionError when all resolution levels fail.
+ *
+ * Backward compat: without native or explicit platform inputs, compatibility
+ * roots retain their legacy Claude → Codex → Cursor → Pi order.
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const COMPATIBILITY_ROOTS = [
+  ['claude', 'CLAUDE_PLUGIN_ROOT'],
+  ['codex', 'CODEX_PLUGIN_ROOT'],
+  ['cursor', 'CURSOR_RULES_DIR'],
+  ['pi', 'PI_PLUGIN_ROOT'],
+];
+const VALID_PLATFORMS = new Set(COMPATIBILITY_ROOTS.map(([platform]) => platform));
+
+// ---------------------------------------------------------------------------
+// PluginRootResolutionError
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when all resolution levels fail. Callers may inspect
+ * `error.triedPaths` to understand what was attempted.
+ */
+export class PluginRootResolutionError extends Error {
+  /**
+   * @param {string} message
+   * @param {string[]} triedPaths  Directories / env vars that were checked
+   */
+  constructor(message, triedPaths = []) {
+    super(message);
+    this.name = 'PluginRootResolutionError';
+    this.triedPaths = triedPaths;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true when `dir` is an existing directory.
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function _isDir(dir) {
+  try { return statSync(dir).isDirectory(); } catch { return false; }
+}
+
+/**
+ * Return a trimmed allowlisted platform or null.
+ * @param {string|undefined} value
+ * @returns {"claude"|"codex"|"cursor"|"pi"|null}
+ */
+function _validPlatform(value) {
+  const platform = (value || '').trim();
+  if (!VALID_PLATFORMS.has(platform)) return null;
+  return /** @type {"claude"|"codex"|"cursor"|"pi"} */ (platform);
+}
+
+/**
+ * Resolve one environment path, recording why it was skipped.
+ * @param {string} envName
+ * @param {string[]} tried
+ * @returns {string|null}
+ */
+function _envDirectory(envName, tried) {
+  const rawValue = process.env[envName];
+  const value = (rawValue || '').trim();
+
+  if (!value) {
+    tried.push(rawValue === undefined
+      ? `${envName} (not set)`
+      : `${envName} (empty after trim)`);
+    return null;
+  }
+
+  if (_isDir(value)) return value;
+  tried.push(`${envName}=${value} (not a directory)`);
+  return null;
+}
+
+/**
+ * Order compatibility roots by explicit platform, then an optional caller hint,
+ * while retaining the legacy Claude → Codex → Cursor → Pi order for the rest.
+ * @param {string|undefined} platformHint
+ * @returns {Array<[string, string]>}
+ */
+function _orderedCompatibilityRoots(platformHint) {
+  const preferredPlatform = _validPlatform(process.env.SO_PLATFORM) ?? _validPlatform(platformHint);
+  if (!preferredPlatform) return COMPATIBILITY_ROOTS;
+
+  const matching = COMPATIBILITY_ROOTS.filter(([platform]) => platform === preferredPlatform);
+  const remaining = COMPATIBILITY_ROOTS.filter(([platform]) => platform !== preferredPlatform);
+  return [...matching, ...remaining];
+}
+
+/**
+ * Return true when `dir` contains a package.json whose `name` field equals
+ * `"session-orchestrator"`. Silently returns false on any read/parse error.
+ *
+ * @param {string} dir  Candidate directory to inspect
+ * @returns {boolean}
+ */
+function _isPluginRoot(dir) {
+  try {
+    const pkgPath = path.join(dir, 'package.json');
+    if (!existsSync(pkgPath)) return false;
+    const raw = readFileSync(pkgPath, 'utf8');
+    const pkg = JSON.parse(raw);
+    return pkg.name === 'session-orchestrator';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Walk up the directory tree from `startDir`, testing each directory with
+ * `_isPluginRoot`. Returns the matching directory path or `null`.
+ *
+ * Terminates at the filesystem root ("/", "C:\\", etc.) or when the parent
+ * path stops changing (guard against edge cases).
+ *
+ * @param {string} startDir  Absolute directory to begin walking from
+ * @returns {string|null}
+ */
+function _walkUp(startDir) {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    if (_isPluginRoot(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // safety guard
+    dir = parent;
+  }
+
+  // Check root itself
+  if (_isPluginRoot(root)) return root;
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// resolvePluginRoot
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the absolute path to the session-orchestrator plugin directory.
+ *
+ * Fallback order:
+ *   1. Trimmed native PLUGIN_ROOT when it is an existing directory
+ *   2. Compatibility root matching a valid explicit SO_PLATFORM
+ *   3. Remaining compatibility roots in legacy order
+ *   4. Walk up from import.meta.url (the location of this file) looking for a
+ *      package.json with name "session-orchestrator"
+ *   5. Walk up from process.cwd() looking for the same marker
+ *
+ * @param {string} [platformHint] Optional compatibility hint for wrapper callers
+ * @returns {string} Absolute path to the plugin root
+ * @throws {PluginRootResolutionError} When all resolution levels fail
+ */
+export function resolvePluginRoot(platformHint) {
+  const tried = [];
+
+  // Level 1: native root identifies location only; platform detection is separate.
+  const nativeRoot = _envDirectory('PLUGIN_ROOT', tried);
+  if (nativeRoot) return nativeRoot;
+
+  // Levels 2-5: prefer the compatibility root matching explicit SO_PLATFORM.
+  for (const [, envName] of _orderedCompatibilityRoots(platformHint)) {
+    const compatibilityRoot = _envDirectory(envName, tried);
+    if (compatibilityRoot) return compatibilityRoot;
+  }
+
+  // Level 6: walk up from this file's location
+  const thisDir = path.dirname(fileURLToPath(import.meta.url));
+  const byImportMeta = _walkUp(thisDir);
+  if (byImportMeta) return byImportMeta;
+  tried.push(`walk from import.meta.url (${thisDir}) — no package.json{name:session-orchestrator} found`);
+
+  // Level 7: walk up from cwd
+  const byCwd = _walkUp(process.cwd());
+  if (byCwd) return byCwd;
+  tried.push(`walk from cwd (${process.cwd()}) — no package.json{name:session-orchestrator} found`);
+
+  throw new PluginRootResolutionError(
+    'Could not resolve session-orchestrator plugin root. ' +
+    'Set PLUGIN_ROOT, CLAUDE_PLUGIN_ROOT, CODEX_PLUGIN_ROOT, CURSOR_RULES_DIR, or PI_PLUGIN_ROOT ' +
+    'to the plugin directory, or ensure a package.json with name "session-orchestrator" exists in an ' +
+    'ancestor of the cwd or this script. Attempted: ' + tried.join('; '),
+    tried,
+  );
+}

package/scripts/lib/pre-dispatch-check.mjs

@@ -0,0 +1,126 @@
+/**
+ * pre-dispatch-check.mjs — guard against untracked-file data loss when
+ * Claude Code's Agent tool runs with `isolation: "worktree"`.
+ *
+ * Background (issue #180): the Agent tool's built-in worktree isolation
+ * syncs directories back to the coordinator's working tree when the agent
+ * completes. If the coordinator holds untracked files that overlap with
+ * the agent's scope, the sync silently overwrites them. This helper lets
+ * the coordinator detect the overlap before dispatching, and either warn
+ * or hard-refuse per the caller's policy.
+ *
+ * Stdlib-only, cross-platform, no zx.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { pathMatchesPattern } from './hardening.mjs';
+
+/**
+ * @typedef {Object} OverlapResult
+ * @property {string[]} overlapping        relative paths of untracked files overlapping the scope
+ * @property {string[]} untracked          full list of untracked files discovered
+ * @property {'ok'|'warn'|'block'} decision
+ * @property {string} message              human-readable summary
+ */
+
+/**
+ * Detect untracked coordinator files that overlap a planned agent scope.
+ *
+ * @param {Object} opts
+ * @param {string[]} opts.scope        agent file scope (paths, directories, or globs)
+ * @param {string}   [opts.cwd]        project root (defaults to process.cwd())
+ * @param {'warn'|'block'|'off'} [opts.mode='warn']
+ *   - `warn`  — return decision:'warn' when overlap found
+ *   - `block` — return decision:'block' when overlap found
+ *   - `off`   — never flag (short-circuit, decision:'ok')
+ * @returns {OverlapResult}
+ */
+export function checkUntrackedOverlap({ scope, cwd = process.cwd(), mode = 'warn' } = {}) {
+  if (mode === 'off') {
+    return { overlapping: [], untracked: [], decision: 'ok', message: 'pre-dispatch check disabled' };
+  }
+
+  if (!Array.isArray(scope) || scope.length === 0) {
+    return { overlapping: [], untracked: [], decision: 'ok', message: 'empty scope — no overlap possible' };
+  }
+
+  const untracked = listUntracked(cwd);
+
+  const overlapping = untracked.filter((file) => scope.some((pat) => pathMatchesPattern(file, pat)));
+
+  if (overlapping.length === 0) {
+    return { overlapping: [], untracked, decision: 'ok', message: 'no overlap between untracked files and agent scope' };
+  }
+
+  const decision = mode === 'block' ? 'block' : 'warn';
+  const verb = decision === 'block' ? 'REFUSING' : 'WARNING';
+  const action =
+    decision === 'block'
+      ? 'commit or stash them before dispatching, or rerun with mode=warn to acknowledge the risk'
+      : 'the Agent tool\'s worktree isolation may overwrite these on merge-back (issue #180)';
+  const message =
+    `${verb}: ${overlapping.length} untracked coordinator file(s) overlap the agent scope — ${action}\n` +
+    overlapping.map((f) => `  - ${f}`).join('\n');
+
+  return { overlapping, untracked, decision, message };
+}
+
+/**
+ * Run `git status --porcelain` and extract untracked files (prefix "??").
+ * Returns paths relative to `cwd`. Returns [] on any git failure.
+ *
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+export function listUntracked(cwd) {
+  let stdout;
+  try {
+    stdout = execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8' });
+  } catch {
+    return [];
+  }
+
+  const files = [];
+  for (const rawLine of stdout.split('\n')) {
+    if (!rawLine.startsWith('?? ')) continue;
+    // Porcelain v1 wraps paths in quotes when they contain special chars. Strip them.
+    let rel = rawLine.slice(3);
+    if (rel.startsWith('"') && rel.endsWith('"')) {
+      rel = rel.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+    }
+    // Directory entries end with `/` in porcelain output — expand to file list for fidelity.
+    if (rel.endsWith('/')) {
+      files.push(...expandDirectory(cwd, rel));
+    } else {
+      files.push(rel);
+    }
+  }
+  return files;
+}
+
+/**
+ * Enumerate untracked files under a directory via `git ls-files --others`.
+ * Runs in the given cwd and resolves the directory relative to that root.
+ * Returns repo-relative paths. Best-effort — swallows errors and falls back
+ * to the directory entry itself so callers still see something.
+ *
+ * @param {string} cwd
+ * @param {string} relDir  repo-relative directory with trailing `/`
+ * @returns {string[]}
+ */
+function expandDirectory(cwd, relDir) {
+  try {
+    const stdout = execFileSync(
+      'git',
+      ['ls-files', '--others', '--exclude-standard', '--', relDir],
+      { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }
+    );
+    const lines = stdout
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+    return lines.length > 0 ? lines : [relDir];
+  } catch {
+    return [relDir];
+  }
+}