session-orchestrator 3.16.0

package/scripts/lib/pi-hook-bridge.mjs

@@ -0,0 +1,328 @@
+/**
+ * pi-hook-bridge.mjs — map Pi extension events onto the existing hook handlers.
+ *
+ * Pi exposes native extension events such as `tool_call` and `session_start`.
+ * The session-orchestrator hooks already speak the Claude/Codex stdin contract:
+ * `{ hook_event_name, tool_name, tool_input, ... }`. This bridge keeps that
+ * contract stable by normalising Pi payloads before spawning the existing
+ * `hooks/*.mjs` commands listed in hooks/hooks-pi.json.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { resolvePluginRoot } from './plugin-root.mjs';
+
+export const PI_TO_CANONICAL_EVENT = Object.freeze({
+  session_start: 'SessionStart',
+  session_shutdown: 'SessionEnd',
+  tool_call: 'PreToolUse',
+  tool_result: 'PostToolUse',
+  agent_end: 'Stop',
+});
+
+const TOOL_NAME_MAP = Object.freeze({
+  bash: 'Bash',
+  edit: 'Edit',
+  write: 'Write',
+  multiedit: 'MultiEdit',
+  multi_edit: 'MultiEdit',
+  read: 'Read',
+  grep: 'Grep',
+  find: 'Find',
+  ls: 'LS',
+});
+
+/**
+ * @param {string|undefined} toolName
+ * @returns {string|undefined}
+ */
+export function mapPiToolName(toolName) {
+  if (typeof toolName !== 'string' || toolName.length === 0) return undefined;
+  const key = toolName.toLowerCase();
+  return TOOL_NAME_MAP[key] ?? toolName;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {Record<string, unknown>}
+ */
+function objectOrEmpty(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+/**
+ * Pi built-in tools use their native argument names (`path`, `oldText`,
+ * `newText`). Existing Session Orchestrator hooks expect the Claude/Codex
+ * shape (`file_path`, `old_string`, `new_string`). Normalize only by adding
+ * canonical aliases; keep the original Pi fields intact for diagnostics.
+ *
+ * @param {string|undefined} toolName
+ * @param {Record<string, unknown>} input
+ * @returns {{ toolName: string|undefined, toolInput: Record<string, unknown> }}
+ */
+function normalizePiToolInput(toolName, input) {
+  const next = { ...input };
+  const lowerToolName = typeof toolName === 'string' ? toolName.toLowerCase() : '';
+
+  if (typeof next.file_path !== 'string' && typeof next.path === 'string') {
+    next.file_path = next.path;
+  }
+
+  if (lowerToolName === 'write') {
+    return { toolName: 'Write', toolInput: next };
+  }
+
+  if (lowerToolName === 'edit') {
+    if (Array.isArray(next.edits)) {
+      const edits = next.edits.map((edit) => {
+        const e = objectOrEmpty(edit);
+        return {
+          ...e,
+          old_string: typeof e.old_string === 'string' ? e.old_string : e.oldText,
+          new_string: typeof e.new_string === 'string' ? e.new_string : e.newText,
+        };
+      });
+      next.edits = edits;
+      if (edits.length === 1) {
+        next.old_string = next.old_string ?? edits[0].old_string;
+        next.new_string = next.new_string ?? edits[0].new_string;
+        return { toolName: 'Edit', toolInput: next };
+      }
+      return { toolName: 'MultiEdit', toolInput: next };
+    }
+
+    next.old_string = typeof next.old_string === 'string' ? next.old_string : next.oldText;
+    next.new_string = typeof next.new_string === 'string' ? next.new_string : next.newText;
+    return { toolName: 'Edit', toolInput: next };
+  }
+
+  return { toolName: mapPiToolName(toolName), toolInput: next };
+}
+
+/**
+ * Build the hook stdin payload expected by existing session-orchestrator hooks.
+ *
+ * @param {string} piEventName
+ * @param {Record<string, unknown>} [event]
+ * @param {Record<string, unknown>} [ctx]
+ * @returns {Record<string, unknown>}
+ */
+export function normalizePiHookPayload(piEventName, event = {}, ctx = {}) {
+  const eventObject = objectOrEmpty(event);
+  const ctxObject = objectOrEmpty(ctx);
+  const rawToolName = eventObject.toolName ?? eventObject.tool_name;
+  const mappedToolName = mapPiToolName(typeof rawToolName === 'string' ? rawToolName : undefined);
+  const rawToolInput = objectOrEmpty(eventObject.input ?? eventObject.args ?? eventObject.tool_input);
+  const { toolName, toolInput } = normalizePiToolInput(
+    typeof rawToolName === 'string' ? rawToolName : mappedToolName,
+    rawToolInput,
+  );
+  const cwd = typeof ctxObject.cwd === 'string'
+    ? ctxObject.cwd
+    : (typeof eventObject.cwd === 'string' ? eventObject.cwd : process.cwd());
+
+  return {
+    hook_event_name: PI_TO_CANONICAL_EVENT[piEventName] ?? piEventName,
+    pi_event_name: piEventName,
+    session_id: eventObject.sessionId ?? eventObject.session_id ?? ctxObject.sessionId,
+    cwd,
+    reason: eventObject.reason,
+    tool_name: toolName,
+    tool_input: toolInput,
+    tool_call_id: eventObject.toolCallId ?? eventObject.tool_call_id,
+    tool_response: eventObject.result ?? eventObject.toolResult ?? eventObject.tool_response,
+    is_error: eventObject.isError ?? eventObject.is_error,
+    timestamp: eventObject.timestamp ?? new Date().toISOString(),
+  };
+}
+
+/**
+ * @param {string} pluginRoot
+ * @returns {Record<string, unknown>}
+ */
+export function loadPiHookManifest(pluginRoot = resolvePluginRoot()) {
+  const manifestPath = path.join(pluginRoot, 'hooks', 'hooks-pi.json');
+  if (!existsSync(manifestPath)) {
+    throw new Error(`Pi hook manifest not found at ${manifestPath}`);
+  }
+  return JSON.parse(readFileSync(manifestPath, 'utf8'));
+}
+
+/**
+ * @param {string} matcher
+ * @param {string[]} targets
+ * @returns {boolean}
+ */
+export function matcherMatches(matcher, targets) {
+  if (!matcher || matcher === '*') return true;
+  const normalizedTargets = targets.filter(Boolean).map((t) => t.toLowerCase());
+  const alternatives = matcher.split('|').map((p) => p.trim().toLowerCase()).filter(Boolean);
+  return alternatives.some((part) => normalizedTargets.includes(part));
+}
+
+/**
+ * @param {string} piEventName
+ * @param {Record<string, unknown>} event
+ * @returns {string[]}
+ */
+function matcherTargets(piEventName, event) {
+  const rawToolName = event.toolName ?? event.tool_name;
+  const canonicalToolName = mapPiToolName(typeof rawToolName === 'string' ? rawToolName : undefined);
+  const reason = typeof event.reason === 'string' ? event.reason : '';
+  return [
+    piEventName,
+    reason,
+    typeof rawToolName === 'string' ? rawToolName : '',
+    canonicalToolName ?? '',
+  ].map((v) => v.toLowerCase());
+}
+
+/**
+ * @param {Record<string, unknown>} manifest
+ * @param {string} piEventName
+ * @param {Record<string, unknown>} [event]
+ * @returns {Array<Record<string, unknown>>}
+ */
+export function selectPiHooks(manifest, piEventName, event = {}) {
+  const hooksByEvent = objectOrEmpty(manifest.hooks);
+  const matchers = Array.isArray(hooksByEvent[piEventName]) ? hooksByEvent[piEventName] : [];
+  const targets = matcherTargets(piEventName, objectOrEmpty(event));
+  const selected = [];
+
+  for (const matcherConfig of matchers) {
+    const config = objectOrEmpty(matcherConfig);
+    const matcher = typeof config.matcher === 'string' ? config.matcher : '';
+    if (!matcherMatches(matcher, targets)) continue;
+    const hooks = Array.isArray(config.hooks) ? config.hooks : [];
+    for (const hook of hooks) {
+      selected.push(objectOrEmpty(hook));
+    }
+  }
+
+  return selected;
+}
+
+/**
+ * @param {string} stdout
+ * @returns {Record<string, unknown>|null}
+ */
+function parseLastJsonLine(stdout) {
+  const lines = stdout.split('\n').map((l) => l.trim()).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      const parsed = JSON.parse(lines[i]);
+      if (parsed && typeof parsed === 'object') return parsed;
+    } catch {
+      // Try the previous line.
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {Record<string, unknown>} hook
+ * @param {Record<string, unknown>} payload
+ * @param {{ pluginRoot: string, cwd?: string, env?: NodeJS.ProcessEnv }} options
+ * @returns {{ command: string, status: number|null, stdout: string, stderr: string, blocked: boolean, reason: string|null }}
+ */
+export function runPiHookCommand(hook, payload, options) {
+  const command = typeof hook.command === 'string' ? hook.command : '';
+  if (!command) {
+    return { command, status: 0, stdout: '', stderr: '', blocked: false, reason: null };
+  }
+
+  const timeoutSeconds = Number.isFinite(hook.timeout) ? Number(hook.timeout) : 5;
+  const cwd = options.cwd || (typeof payload.cwd === 'string' ? payload.cwd : process.cwd());
+  const env = {
+    ...process.env,
+    ...options.env,
+  };
+  delete env.CLAUDE_PLUGIN_ROOT;
+  delete env.CODEX_PLUGIN_ROOT;
+  delete env.CURSOR_RULES_DIR;
+  delete env.CLAUDE_PROJECT_DIR;
+  delete env.CODEX_PROJECT_DIR;
+  delete env.CURSOR_PROJECT_DIR;
+  env.PI_PLUGIN_ROOT = options.pluginRoot;
+  env.PLUGIN_ROOT = options.pluginRoot;
+  env.SO_PLATFORM = 'pi';
+  if (typeof payload.cwd === 'string') env.PI_PROJECT_DIR = payload.cwd;
+
+  const result = spawnSync(command, {
+    shell: true,
+    cwd,
+    env,
+    input: JSON.stringify(payload) + '\n',
+    encoding: 'utf8',
+    timeout: timeoutSeconds * 1000,
+  });
+
+  const stdout = result.stdout ?? '';
+  const stderr = result.stderr ?? '';
+  const parsed = parseLastJsonLine(stdout);
+  const isPreToolUse = payload.hook_event_name === 'PreToolUse';
+  const infraFailure = Boolean(result.error) ||
+    result.status === null ||
+    (result.status !== 0 && result.status !== 2);
+  const blocked = result.status === 2 ||
+    parsed?.permissionDecision === 'deny' ||
+    (isPreToolUse && infraFailure);
+  const reason = typeof parsed?.reason === 'string'
+    ? parsed.reason
+    : (blocked
+        ? (result.error?.message || stdout.trim() || stderr.trim() || `Hook command blocked: ${command}`)
+        : null);
+
+  return {
+    command,
+    status: result.status,
+    stdout,
+    stderr,
+    blocked,
+    reason,
+  };
+}
+
+/**
+ * Run all hooks configured for one Pi event. For `tool_call`, a blocking hook
+ * returns a Pi-compatible `{ block, reason }` response to the extension.
+ *
+ * @param {string} piEventName
+ * @param {Record<string, unknown>} [event]
+ * @param {Record<string, unknown>} [ctx]
+ * @param {{ pluginRoot?: string, manifest?: Record<string, unknown>, env?: NodeJS.ProcessEnv }} [options]
+ * @returns {Promise<{ block: boolean, reason: string|null, payload: Record<string, unknown>, results: Array<object> }>}
+ */
+export async function runPiHookEvent(piEventName, event = {}, ctx = {}, options = {}) {
+  const pluginRoot = options.pluginRoot ?? resolvePluginRoot();
+  const manifest = options.manifest ?? loadPiHookManifest(pluginRoot);
+  const payload = normalizePiHookPayload(piEventName, event, ctx);
+  const hooks = selectPiHooks(manifest, piEventName, event);
+  const results = [];
+
+  for (const hook of hooks) {
+    const result = runPiHookCommand(hook, payload, {
+      pluginRoot,
+      cwd: typeof payload.cwd === 'string' ? payload.cwd : process.cwd(),
+      env: options.env,
+    });
+    results.push(result);
+    if (result.blocked) {
+      return {
+        block: true,
+        reason: result.reason,
+        payload,
+        results,
+      };
+    }
+  }
+
+  return {
+    block: false,
+    reason: null,
+    payload,
+    results,
+  };
+}

package/scripts/lib/platform.mjs

@@ -0,0 +1,266 @@
+/**
+ * platform.mjs — platform detection for session-orchestrator (Node.js port of platform.sh)
+ * ESM-importable. Uses only Node built-ins. No external dependencies.
+ *
+ * Exports 10 constants + 5 named helper functions:
+ *   SO_PLATFORM, SO_PLUGIN_ROOT, SO_PROJECT_DIR, SO_STATE_DIR, SO_CONFIG_FILE,
+ *   SO_SHARED_DIR, SO_OS, SO_IS_WINDOWS, SO_IS_WSL, SO_PATH_SEP
+ *   detectPlatform, resolvePluginRoot, resolveProjectDir, resolveStateDir, resolveConfigFile
+ */
+
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { resolvePluginRoot as _resolvePluginRootRobust } from './plugin-root.mjs';
+
+const VALID_PLATFORMS = new Set(['claude', 'codex', 'cursor', 'pi']);
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function _isFile(p) {
+  try { return statSync(p).isFile(); } catch { return false; }
+}
+
+function _isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+/**
+ * @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);
+}
+
+/** @param {string} envName */
+function _hasEnvValue(envName) {
+  return (process.env[envName] || '').trim() !== '';
+}
+
+/**
+ * Walk up the directory tree from startDir looking for marker.
+ * Uses path.parse(dir).root so it terminates correctly on Windows ("C:\\")
+ * and POSIX ("/").
+ *
+ * @param {string} startDir   Absolute directory to begin walking from
+ * @param {string} marker     Relative sub-path to look for inside each candidate dir
+ * @param {'file'|'dir'|'any'} kind  What to check for existence
+ * @returns {string|null}  The directory that contains marker, or null
+ */
+function walkUpFor(startDir, marker, kind) {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root; // "/" on POSIX, "C:\\" on Windows
+
+  const check = (candidate) => {
+    if (!existsSync(candidate)) return false;
+    if (kind === 'file') return _isFile(candidate);
+    if (kind === 'dir')  return _isDir(candidate);
+    return true; // 'any'
+  };
+
+  while (dir !== root) {
+    if (check(path.join(dir, marker))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // safety guard — should not happen but protects against edge cases
+    dir = parent;
+  }
+
+  // Check root itself
+  if (check(path.join(root, marker))) return root;
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// detectPlatform
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect the host IDE/CLI platform.
+ *
+ * Detection order:
+ * 1. Trimmed allowlisted SO_PLATFORM explicit override
+ * 2. Compatibility env vars: CLAUDE_PLUGIN_ROOT → "claude", CODEX_PLUGIN_ROOT → "codex",
+ *    CURSOR_RULES_DIR → "cursor", PI_PLUGIN_ROOT → "pi"
+ * 3. Filesystem walk from CWD looking for marker dirs:
+ *    .claude-plugin → "claude", .codex-plugin → "codex", .cursor/rules → "cursor",
+ *    .pi → "pi"
+ * 4. Default: "claude"
+ *
+ * @returns {"claude"|"codex"|"cursor"|"pi"}
+ */
+export function detectPlatform() {
+  const explicitPlatform = _validPlatform(process.env.SO_PLATFORM);
+  if (explicitPlatform) return explicitPlatform;
+
+  if (_hasEnvValue('CLAUDE_PLUGIN_ROOT')) return 'claude';
+  if (_hasEnvValue('CODEX_PLUGIN_ROOT')) return 'codex';
+  if (_hasEnvValue('CURSOR_RULES_DIR')) return 'cursor';
+  if (_hasEnvValue('PI_PLUGIN_ROOT')) return 'pi';
+
+  const cwd = process.cwd();
+
+  if (walkUpFor(cwd, '.claude-plugin',               'dir')) return 'claude';
+  if (walkUpFor(cwd, '.codex-plugin',                'dir')) return 'codex';
+  if (walkUpFor(cwd, path.join('.cursor', 'rules'),  'dir')) return 'cursor';
+  if (walkUpFor(cwd, '.pi',                           'dir')) return 'pi';
+
+  return 'claude';
+}
+
+// ---------------------------------------------------------------------------
+// resolvePluginRoot
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the absolute path to the session-orchestrator plugin directory.
+ *
+ * Delegates to `scripts/lib/plugin-root.mjs` which implements native PLUGIN_ROOT,
+ * explicit-platform compatibility precedence, remaining compatibility roots, and
+ * import-meta/cwd walking. The optional platform argument retains the legacy Cursor fast path.
+ *
+ * Returns empty string (never throws) to preserve backward compat with callers
+ * that check for a falsy return value.
+ *
+ * @param {"claude"|"codex"|"cursor"|"pi"} [platform]
+ * @returns {string}  Absolute path, or empty string if nothing found
+ */
+export function resolvePluginRoot(platform) {
+  const plt = platform ?? detectPlatform();
+
+  // Preserve the legacy explicit Cursor fast path without changing Claude/Codex/Pi ordering.
+  const compatibilityHint = plt === 'cursor' ? plt : undefined;
+
+  try {
+    return _resolvePluginRootRobust(compatibilityHint);
+  } catch {
+    return '';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// resolveProjectDir
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the absolute path to the current project root.
+ *
+ * Detection order (mirrors platform.sh):
+ * 1. CLAUDE_PROJECT_DIR → CODEX_PROJECT_DIR → CURSOR_PROJECT_DIR → PI_PROJECT_DIR env vars
+ *    (CLAUDE wins when multiple are set — matches .sh order)
+ * 2. Walk CWD up looking for platform config file (CLAUDE.md / AGENTS.md) or .git
+ * 3. Default: process.cwd()
+ *
+ * @param {"claude"|"codex"|"cursor"|"pi"} [platform]
+ * @returns {string}  Absolute path
+ */
+export function resolveProjectDir(platform) {
+  const plt = platform ?? detectPlatform();
+
+  // 1. Env-var fast path
+  if (process.env.CLAUDE_PROJECT_DIR)  return process.env.CLAUDE_PROJECT_DIR;
+  if (process.env.CODEX_PROJECT_DIR)   return process.env.CODEX_PROJECT_DIR;
+  if (process.env.CURSOR_PROJECT_DIR)  return process.env.CURSOR_PROJECT_DIR;
+  if (process.env.PI_PROJECT_DIR)      return process.env.PI_PROJECT_DIR;
+
+  // 2. Walk up from CWD
+  const cwd = process.cwd();
+  const configFile = (plt === 'codex' || plt === 'pi') ? 'AGENTS.md' : 'CLAUDE.md';
+
+  const byConfig = walkUpFor(cwd, configFile, 'file');
+  if (byConfig) return byConfig;
+
+  const byGit = walkUpFor(cwd, '.git', 'any');
+  if (byGit) return byGit;
+
+  // 3. Default
+  return cwd;
+}
+
+// ---------------------------------------------------------------------------
+// resolveStateDir
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the platform-native transient state directory name.
+ *
+ * | Platform | Result   |
+ * |----------|----------|
+ * | claude   | .claude  |
+ * | codex    | .codex   |
+ * | cursor   | .cursor  |
+ * | pi       | .pi      |
+ *
+ * @param {"claude"|"codex"|"cursor"|"pi"} [platform]
+ * @returns {".claude"|".codex"|".cursor"|".pi"}
+ */
+export function resolveStateDir(platform) {
+  const plt = platform ?? detectPlatform();
+  switch (plt) {
+    case 'codex':  return '.codex';
+    case 'cursor': return '.cursor';
+    case 'pi':     return '.pi';
+    default:       return '.claude';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// resolveConfigFile
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the platform config file name.
+ *
+ * | Platform | Result    |
+ * |----------|-----------|
+ * | codex    | AGENTS.md |
+ * | pi       | AGENTS.md |
+ * | others   | CLAUDE.md |
+ *
+ * @param {"claude"|"codex"|"cursor"|"pi"} [platform]
+ * @returns {"CLAUDE.md"|"AGENTS.md"}
+ */
+export function resolveConfigFile(platform) {
+  const plt = platform ?? detectPlatform();
+  return (plt === 'codex' || plt === 'pi') ? 'AGENTS.md' : 'CLAUDE.md';
+}
+
+// ---------------------------------------------------------------------------
+// Auto-initialise — compute all exported constants at module load
+// ---------------------------------------------------------------------------
+
+/** @type {"claude"|"codex"|"cursor"|"pi"} */
+export const SO_PLATFORM = detectPlatform();
+
+/** Absolute path to the session-orchestrator plugin directory (empty string if unresolvable) */
+export const SO_PLUGIN_ROOT = resolvePluginRoot(SO_PLATFORM);
+
+/** Absolute path to the current project root */
+export const SO_PROJECT_DIR = resolveProjectDir(SO_PLATFORM);
+
+/** Platform-native state directory name */
+export const SO_STATE_DIR = resolveStateDir(SO_PLATFORM);
+
+/** Platform config file name */
+export const SO_CONFIG_FILE = resolveConfigFile(SO_PLATFORM);
+
+/** Shared orchestrator directory name — always ".orchestrator" */
+export const SO_SHARED_DIR = '.orchestrator';
+
+// --- v3 OS / Windows exports ---
+
+/** Current OS identifier: process.platform ("darwin" | "linux" | "win32" | ...) */
+export const SO_OS = process.platform;
+
+/** True when running on Windows (native) */
+export const SO_IS_WINDOWS = process.platform === 'win32';
+
+/** True when running inside WSL (Windows Subsystem for Linux) */
+export const SO_IS_WSL = process.env.WSL_DISTRO_NAME !== undefined;
+
+/** Native path segment separator ("/" on POSIX, "\\" on Windows) */
+export const SO_PATH_SEP = path.sep;