@pi-chamber/web 0.1.8

package/server/lib/terminal/shells.test.js

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+
+import { createTerminalShellResolver, getTerminalShellLoginArgs } from './shells.js';
+
+const createResolver = ({ platform = 'linux', env = {}, augmentedPath = '/augmented/bin', executables = [] } = {}) => {
+  const available = new Set(executables);
+  const path = {
+    delimiter: platform === 'win32' ? ';' : ':',
+    extname: (value) => /\.[^./\\]+$/.exec(value)?.[0] ?? '',
+    join: (...parts) => parts.join(platform === 'win32' ? '\\' : '/'),
+  };
+  const searches = [];
+  return {
+    searches,
+    resolver: createTerminalShellResolver({
+      fs: { promises: { readFile: async () => '' } },
+      path,
+      platform,
+      env,
+      buildAugmentedPath: () => augmentedPath,
+      searchPathFor: (name, searchPath) => {
+        searches.push([name, searchPath]);
+        const suffixes = platform === 'win32' ? ['', '.exe'] : [''];
+        for (const suffix of suffixes) {
+          const match = [...available].find((candidate) => candidate.toLowerCase().endsWith(`${platform === 'win32' ? '\\' : '/'}${name}${suffix}`.toLowerCase()));
+          if (match) return match;
+        }
+        return null;
+      },
+      isExecutable: (candidate) => available.has(candidate),
+    }),
+  };
+};
+
+describe('terminal shell resolver', () => {
+  it('discovers shells from the augmented PTY PATH', async () => {
+    const { resolver, searches } = createResolver({ executables: ['/augmented/bin/fish'] });
+
+    await expect(resolver.list()).resolves.toContainEqual({ id: 'fish', name: 'fish', executable: '/augmented/bin/fish', supportsLogin: true });
+    expect(searches).toContainEqual(['fish', '/augmented/bin']);
+  });
+
+  it('discovers supported PATH-installed shells on Windows', async () => {
+    const { resolver } = createResolver({
+      platform: 'win32',
+      augmentedPath: 'C:\\Tools',
+      executables: ['C:\\Tools\\bash.exe', 'C:\\Tools\\nu.exe'],
+    });
+
+    await expect(resolver.list()).resolves.toEqual(expect.arrayContaining([
+      { id: 'bash', name: 'bash', executable: 'C:\\Tools\\bash.exe', supportsLogin: true },
+      { id: 'nu', name: 'nu', executable: 'C:\\Tools\\nu.exe', supportsLogin: true },
+    ]));
+  });
+
+  it('uses environment overrides before platform defaults for auto', async () => {
+    const { resolver } = createResolver({
+      env: { PICHAMBER_TERMINAL_SHELL: '/custom/zsh', SHELL: '/bin/bash' },
+      executables: ['/custom/zsh', '/bin/bash'],
+    });
+
+    await expect(resolver.resolve('auto')).resolves.toEqual({ id: 'auto', executables: ['/custom/zsh', '/bin/bash'] });
+  });
+
+  it('uses only known platform-safe login arguments', () => {
+    expect(getTerminalShellLoginArgs('/bin/bash', 'linux')).toEqual(['-l']);
+    expect(getTerminalShellLoginArgs('/opt/homebrew/bin/fish', 'darwin')).toEqual(['--login']);
+    expect(getTerminalShellLoginArgs('/usr/bin/nu', 'linux')).toEqual(['--login']);
+    expect(getTerminalShellLoginArgs('/usr/bin/pwsh', 'linux')).toEqual(['-Login']);
+    expect(getTerminalShellLoginArgs('C:\\Program Files\\PowerShell\\7\\pwsh.exe', 'win32')).toBeNull();
+    expect(getTerminalShellLoginArgs('/bin/dash', 'linux')).toBeNull();
+  });
+});

package/server/lib/terminal/terminal-ws-protocol.js

@@ -0,0 +1,68 @@
+export const TERMINAL_WS_PATH = '/api/terminal/ws';
+export const TERMINAL_WS_CONTROL_TAG_JSON = 0x01;
+export const TERMINAL_WS_MAX_PAYLOAD_BYTES = 64 * 1024;
+
+export const parseRequestPathname = (requestUrl) => {
+  if (typeof requestUrl !== 'string' || requestUrl.length === 0) {
+    return '';
+  }
+
+  try {
+    return new URL(requestUrl, 'http://localhost').pathname;
+  } catch {
+    return '';
+  }
+};
+
+export const isTerminalWsPathname = (pathname) => pathname === TERMINAL_WS_PATH;
+
+export const normalizeTerminalWsMessageToBuffer = (rawData) => {
+  if (Buffer.isBuffer(rawData)) {
+    return rawData;
+  }
+
+  if (Array.isArray(rawData)) {
+    return Buffer.concat(rawData.map((chunk) => (Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))));
+  }
+
+  return Buffer.from(rawData);
+};
+
+export const normalizeTerminalWsMessageToText = (rawData) => {
+  if (typeof rawData === 'string') {
+    return rawData;
+  }
+
+  return normalizeTerminalWsMessageToBuffer(rawData).toString('utf8');
+};
+
+export const readTerminalWsControlFrame = (rawData) => {
+  if (!rawData) {
+    return null;
+  }
+
+  const buffer = normalizeTerminalWsMessageToBuffer(rawData);
+  if (buffer.length < 2 || buffer[0] !== TERMINAL_WS_CONTROL_TAG_JSON) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(buffer.subarray(1).toString('utf8'));
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+};
+
+export const createTerminalWsControlFrame = (payload) => {
+  const jsonBytes = Buffer.from(JSON.stringify(payload), 'utf8');
+  return Buffer.concat([Buffer.from([TERMINAL_WS_CONTROL_TAG_JSON]), jsonBytes]);
+};
+
+export const pruneRebindTimestamps = (timestamps, now, windowMs) =>
+  timestamps.filter((timestamp) => now - timestamp < windowMs);
+
+export const isRebindRateLimited = (timestamps, maxPerWindow) => timestamps.length >= maxPerWindow;

package/server/lib/terminal/terminal-ws-protocol.test.js

@@ -0,0 +1,145 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  TERMINAL_WS_PATH,
+  TERMINAL_WS_CONTROL_TAG_JSON,
+  createTerminalWsControlFrame,
+  isTerminalWsPathname,
+  isRebindRateLimited,
+  normalizeTerminalWsMessageToBuffer,
+  normalizeTerminalWsMessageToText,
+  parseRequestPathname,
+  pruneRebindTimestamps,
+  readTerminalWsControlFrame,
+} from './terminal-ws-protocol.js';
+
+describe('terminal websocket protocol', () => {
+  it('uses fixed websocket paths', () => {
+    expect(TERMINAL_WS_PATH).toBe('/api/terminal/ws');
+  });
+
+  it('matches supported websocket pathnames', () => {
+    expect(isTerminalWsPathname('/api/terminal/ws')).toBe(true);
+    expect(isTerminalWsPathname('/api/terminal/input-ws')).toBe(false);
+    expect(isTerminalWsPathname('/api/terminal/other')).toBe(false);
+  });
+
+  it('encodes control frames with control tag prefix', () => {
+    const frame = createTerminalWsControlFrame({ t: 'ok', v: 1 });
+    expect(frame[0]).toBe(TERMINAL_WS_CONTROL_TAG_JSON);
+  });
+
+  it('roundtrips control frame payload', () => {
+    const payload = { t: 'b', s: 'abc123', v: 1 };
+    const frame = createTerminalWsControlFrame(payload);
+    expect(readTerminalWsControlFrame(frame)).toEqual(payload);
+  });
+
+  it('rejects control frame without protocol tag', () => {
+    const frame = Buffer.from(JSON.stringify({ t: 'b', s: 'abc123' }), 'utf8');
+    expect(readTerminalWsControlFrame(frame)).toBeNull();
+  });
+
+  it('rejects malformed control json', () => {
+    const frame = Buffer.concat([
+      Buffer.from([TERMINAL_WS_CONTROL_TAG_JSON]),
+      Buffer.from('{not json', 'utf8'),
+    ]);
+    expect(readTerminalWsControlFrame(frame)).toBeNull();
+  });
+
+  it('rejects empty control payloads', () => {
+    expect(readTerminalWsControlFrame(null)).toBeNull();
+    expect(readTerminalWsControlFrame(undefined)).toBeNull();
+    expect(readTerminalWsControlFrame(Buffer.alloc(0))).toBeNull();
+  });
+
+  it('rejects control json that is not object', () => {
+    const frame = Buffer.concat([
+      Buffer.from([TERMINAL_WS_CONTROL_TAG_JSON]),
+      Buffer.from('"str"', 'utf8'),
+    ]);
+    expect(readTerminalWsControlFrame(frame)).toBeNull();
+  });
+
+  it('parses control frame from chunk arrays', () => {
+    const frame = createTerminalWsControlFrame({ t: 'bok', v: 1 });
+    const chunks = [frame.subarray(0, 2), frame.subarray(2)];
+    expect(readTerminalWsControlFrame(chunks)).toEqual({ t: 'bok', v: 1 });
+  });
+
+  it('normalizes buffer passthrough', () => {
+    const raw = Buffer.from('abc', 'utf8');
+    const normalized = normalizeTerminalWsMessageToBuffer(raw);
+    expect(normalized).toBe(raw);
+    expect(normalized.toString('utf8')).toBe('abc');
+  });
+
+  it('normalizes uint8 arrays', () => {
+    const normalized = normalizeTerminalWsMessageToBuffer(new Uint8Array([97, 98, 99]));
+    expect(normalized.toString('utf8')).toBe('abc');
+  });
+
+  it('normalizes array buffer payloads', () => {
+    const source = new Uint8Array([97, 98, 99]).buffer;
+    const normalized = normalizeTerminalWsMessageToBuffer(source);
+    expect(normalized.toString('utf8')).toBe('abc');
+  });
+
+  it('normalizes chunk array payloads', () => {
+    const normalized = normalizeTerminalWsMessageToBuffer([
+      Buffer.from('ab', 'utf8'),
+      Buffer.from('c', 'utf8'),
+    ]);
+    expect(normalized.toString('utf8')).toBe('abc');
+  });
+
+  it('normalizes text payload from string', () => {
+    expect(normalizeTerminalWsMessageToText('\u001b[A')).toBe('\u001b[A');
+  });
+
+  it('normalizes text payload from binary data', () => {
+    expect(normalizeTerminalWsMessageToText(Buffer.from('\r', 'utf8'))).toBe('\r');
+  });
+
+  it('parses relative request pathname', () => {
+    expect(parseRequestPathname('/api/terminal/ws?x=1')).toBe('/api/terminal/ws');
+  });
+
+  it('parses absolute request pathname', () => {
+    expect(parseRequestPathname('http://localhost:3000/api/terminal/ws')).toBe('/api/terminal/ws');
+  });
+
+  it('returns empty pathname for non-string request url', () => {
+    expect(parseRequestPathname(null)).toBe('');
+  });
+
+  it('returns empty pathname for invalid request url', () => {
+    expect(parseRequestPathname('http://')).toBe('');
+    expect(parseRequestPathname('')).toBe('');
+  });
+
+  it('prunes stale rebind timestamps', () => {
+    const now = 1_000;
+    const pruned = pruneRebindTimestamps([100, 200, 950, 999], now, 100);
+    expect(pruned).toEqual([950, 999]);
+  });
+
+  it('keeps rebind timestamps within active window', () => {
+    const now = 1_000;
+    const pruned = pruneRebindTimestamps([920, 950, 999], now, 100);
+    expect(pruned).toEqual([920, 950, 999]);
+  });
+
+  it('does not rate limit below threshold', () => {
+    expect(isRebindRateLimited([1, 2, 3], 4)).toBe(false);
+  });
+
+  it('does not rate limit empty window', () => {
+    expect(isRebindRateLimited([], 1)).toBe(false);
+  });
+
+  it('rate limits at threshold', () => {
+    expect(isRebindRateLimited([1, 2, 3, 4], 4)).toBe(true);
+  });
+});

package/server/lib/terminal/theme-response.js

@@ -0,0 +1,98 @@
+const MODE_SET = '\u001b[?2031h';
+const MODE_RESET = '\u001b[?2031l';
+const CAPABILITY_QUERY = '\u001b[?2031$p';
+const MODE_QUERIES = ['\u001b[?996n', '\u001b[?997n'];
+// Fish asks this before an unattached browser terminal can reply.
+const PRIMARY_DEVICE_ATTRIBUTE_QUERIES = ['\u001b[c', '\u001b[0c'];
+const PRIMARY_DEVICE_ATTRIBUTE_RESPONSE = '\u001b[?1;2c';
+const OSC_QUERIES = [10, 11].flatMap((code) => [
+  { sequence: `\u001b]${code};?\u0007`, code },
+  { sequence: `\u001b]${code};?\u001b\\`, code },
+]);
+const CONTROL_SEQUENCES = [
+  MODE_SET,
+  MODE_RESET,
+  CAPABILITY_QUERY,
+  ...MODE_QUERIES,
+  ...PRIMARY_DEVICE_ATTRIBUTE_QUERIES,
+  ...OSC_QUERIES.map(({ sequence }) => sequence),
+];
+
+const parseColor = (value) => {
+  if (typeof value !== 'string') return null;
+  const hex = value.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i)?.[1];
+  if (hex) {
+    const expanded = hex.length === 3 ? [...hex].map((part) => part + part).join('') : hex;
+    return [0, 2, 4].map((offset) => Number.parseInt(expanded.slice(offset, offset + 2), 16));
+  }
+  const rgb = value.match(/^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i);
+  return rgb ? rgb.slice(1, 4).map((part) => Math.min(255, Number(part))) : null;
+};
+
+const colorReport = (code, color) => {
+  const rgb = parseColor(color);
+  if (!rgb) return null;
+  const channels = rgb.map((channel) => channel.toString(16).padStart(2, '0').repeat(2));
+  return `\u001b]${code};rgb:${channels.join('/')}\u001b\\`;
+};
+
+export const terminalThemeModeReport = (themeMode) => `\u001b[?997;${themeMode === 'light' ? 2 : 1}n`;
+
+export const consumeTerminalThemeQueries = (
+  pending,
+  data,
+  appearance,
+  { respondToPrimaryDeviceAttributes = false } = {},
+) => {
+  if (!pending && !data.includes('\u001b')) return { pending: '', responses: [], modeEnabled: appearance.modeEnabled === true };
+  const input = `${pending}${data}`;
+  const responses = [];
+  let modeEnabled = appearance.modeEnabled === true;
+
+  for (let index = 0; index < input.length; index += 1) {
+    if (input.startsWith(MODE_SET, index)) {
+      modeEnabled = true;
+      index += MODE_SET.length - 1;
+      continue;
+    }
+    if (input.startsWith(MODE_RESET, index)) {
+      modeEnabled = false;
+      index += MODE_RESET.length - 1;
+      continue;
+    }
+    if (input.startsWith(CAPABILITY_QUERY, index)) {
+      responses.push(`\u001b[?2031;${modeEnabled ? 1 : 2}$y`);
+      index += CAPABILITY_QUERY.length - 1;
+      continue;
+    }
+    const modeQuery = MODE_QUERIES.find((query) => input.startsWith(query, index));
+    if (modeQuery) {
+      responses.push(terminalThemeModeReport(appearance.themeMode));
+      index += modeQuery.length - 1;
+      continue;
+    }
+    const primaryDeviceAttributeQuery = PRIMARY_DEVICE_ATTRIBUTE_QUERIES.find((query) => input.startsWith(query, index));
+    if (primaryDeviceAttributeQuery && respondToPrimaryDeviceAttributes) {
+      // A shell can ask before any browser terminal is attached. Answer with a
+      // conservative VT100 DA1 response so Fish does not block startup for its
+      // ten-second query timeout while waiting for a renderer that cannot see it.
+      responses.push(PRIMARY_DEVICE_ATTRIBUTE_RESPONSE);
+      index += primaryDeviceAttributeQuery.length - 1;
+      continue;
+    }
+    const oscQuery = OSC_QUERIES.find(({ sequence }) => input.startsWith(sequence, index));
+    if (oscQuery) {
+      const response = colorReport(oscQuery.code, oscQuery.code === 10 ? appearance.foreground : appearance.background);
+      if (response) responses.push(response);
+      index += oscQuery.sequence.length - 1;
+    }
+  }
+
+  let nextPending = '';
+  const maxLength = Math.max(...CONTROL_SEQUENCES.map((sequence) => sequence.length));
+  for (let length = 1; length < Math.min(input.length + 1, maxLength); length += 1) {
+    const suffix = input.slice(-length);
+    if (CONTROL_SEQUENCES.some((sequence) => sequence.length > length && sequence.startsWith(suffix))) nextPending = suffix;
+  }
+  return { pending: nextPending, responses, modeEnabled };
+};

package/server/lib/terminal/theme-response.test.js

@@ -0,0 +1,70 @@
+import { describe, expect, test } from 'vitest';
+import { consumeTerminalThemeQueries } from './theme-response.js';
+
+const lightAppearance = {
+  themeMode: 'light',
+  foreground: '#1b1b1b',
+  background: '#faf8f0',
+  modeEnabled: false,
+};
+
+describe('terminal theme responses', () => {
+  test('answers the complete OpenTUI startup handshake', () => {
+    const result = consumeTerminalThemeQueries(
+      '',
+      '\u001b[?2031h\u001b]10;?\u001b\\\u001b]11;?\u001b\\\u001b[?2031$p',
+      lightAppearance,
+    );
+    expect(result).toEqual({
+      pending: '',
+      modeEnabled: true,
+      responses: [
+        '\u001b]10;rgb:1b1b/1b1b/1b1b\u001b\\',
+        '\u001b]11;rgb:fafa/f8f8/f0f0\u001b\\',
+        '\u001b[?2031;1$y',
+      ],
+    });
+  });
+
+  test('handles a query split across PTY output chunks without duplicating it', () => {
+    const first = consumeTerminalThemeQueries('', '\u001b]11;', { ...lightAppearance, themeMode: 'dark' });
+    const second = consumeTerminalThemeQueries(first.pending, '?\u001b\\', { ...lightAppearance, themeMode: 'dark', modeEnabled: first.modeEnabled });
+    const third = consumeTerminalThemeQueries(second.pending, 'x', { ...lightAppearance, themeMode: 'dark', modeEnabled: second.modeEnabled });
+    expect(second.responses).toEqual(['\u001b]11;rgb:fafa/f8f8/f0f0\u001b\\']);
+    expect(second.pending).toBe('');
+    expect(third.responses).toEqual([]);
+  });
+
+  test('answers every repeated query in wire order', () => {
+    const result = consumeTerminalThemeQueries('', '\u001b[?996n\u001b[?996n\u001b]10;?\u0007\u001b]10;?\u0007', lightAppearance);
+    expect(result.responses).toEqual([
+      '\u001b[?997;2n',
+      '\u001b[?997;2n',
+      '\u001b]10;rgb:1b1b/1b1b/1b1b\u001b\\',
+      '\u001b]10;rgb:1b1b/1b1b/1b1b\u001b\\',
+    ]);
+  });
+
+  test('answers a primary device attribute query when the fallback is enabled', () => {
+    const attached = consumeTerminalThemeQueries('', '\u001b[0c', lightAppearance);
+    const unattached = consumeTerminalThemeQueries('', '\u001b[0c', lightAppearance, {
+      respondToPrimaryDeviceAttributes: true,
+    });
+
+    expect(attached.responses).toEqual([]);
+    expect(unattached.responses).toEqual(['\u001b[?1;2c']);
+  });
+
+  test('answers a primary device attribute query split across PTY chunks', () => {
+    const first = consumeTerminalThemeQueries('', '\u001b[0', lightAppearance, {
+      respondToPrimaryDeviceAttributes: true,
+    });
+    const second = consumeTerminalThemeQueries(first.pending, 'c', {
+      ...lightAppearance,
+      modeEnabled: first.modeEnabled,
+    }, { respondToPrimaryDeviceAttributes: true });
+
+    expect(first.pending).toBe('\u001b[0');
+    expect(second.responses).toEqual(['\u001b[?1;2c']);
+  });
+});

package/server/lib/tunnels/DOCUMENTATION.md

@@ -0,0 +1,33 @@
+# Tunnels Module Documentation
+
+## Purpose
+This module contains the shared tunnel support surface for PiChamber: provider
+capability metadata, tunnel types/normalization helpers, cross-platform
+executable discovery, and dependency install-help metadata.
+
+The actual tunnel start implementations live in
+`packages/web/server/lib/cloudflare-tunnel.js` and
+`packages/web/server/lib/ngrok-tunnel.js`; CLI orchestration lives in
+`packages/web/bin/lib/commands-tunnel.js`.
+
+> Wiring note: the previous service orchestration entrypoint
+> (`tunnels/index.js`, `createTunnelService`) was removed as dead code — no
+> runtime entrypoint registered tunnel routes or started a tunnel service.
+> The remaining files are consumed by the CLI capability surface and by the
+> tunnel provider implementations, not by a tunnel orchestration runtime.
+
+## Entrypoints and structure
+- `packages/web/server/lib/tunnels/executable-search.js`: cross-platform executable discovery, including Windows Store app aliases. Consumed by the tunnel providers and `packages/web/server/lib/workspace/host.js`.
+- `packages/web/server/lib/tunnels/install-help.js`: provider/platform install command metadata (`getTunnelDependencyInstallInfo`) for missing tunnel dependencies.
+- `packages/web/server/lib/tunnels/types.js`: shared tunnel provider, mode, and intent constants plus the shared `TunnelServiceError` class.
+
+## Public exports
+- `install-help.js` → `getTunnelDependencyInstallInfo(provider, platform)`
+- `executable-search.js` → `getExecutableSearchDirectories`, `createExecutableSearchEnv`, `findExecutableOnPath`, `resolveExecutableLaunchTarget`
+- `types.js` → `TUNNEL_PROVIDER_CLOUDFLARE`, `TUNNEL_PROVIDER_NGROK`, `TUNNEL_MODE_QUICK`, `TUNNEL_MODE_MANAGED_REMOTE`, `TUNNEL_MODE_MANAGED_LOCAL`, `TUNNEL_INTENT_EPHEMERAL_PUBLIC`, `TUNNEL_INTENT_PERSISTENT_PUBLIC`, `TunnelServiceError`
+
+## Consumers
+- `packages/web/bin/lib/cli-tunnel-capabilities.js`: provider capability metadata for CLI tunnel commands.
+- `packages/web/server/lib/cloudflare-tunnel.js` / `packages/web/server/lib/ngrok-tunnel.js`: executable discovery, install-help metadata, and provider constants.
+- `packages/web/server/lib/workspace/host.js`: executable discovery.
+

package/server/lib/tunnels/executable-search.js

@@ -0,0 +1,140 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+const getEnvValue = (env, keys) => {
+  for (const key of keys) {
+    const value = env?.[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value;
+    }
+  }
+  return '';
+};
+
+const normalizeSearchDirectoryKey = (directory, platform) => {
+  const trimmed = typeof directory === 'string' ? directory.trim() : '';
+  return platform === 'win32' ? trimmed.toLowerCase() : trimmed;
+};
+
+const getWindowsAppsDirectory = (env) => {
+  const localAppData = getEnvValue(env, ['LOCALAPPDATA', 'LocalAppData', 'localappdata']);
+  if (localAppData) {
+    return path.win32.join(localAppData, 'Microsoft', 'WindowsApps');
+  }
+
+  const userProfile = getEnvValue(env, ['USERPROFILE', 'UserProfile', 'userprofile']);
+  if (userProfile) {
+    return path.win32.join(userProfile, 'AppData', 'Local', 'Microsoft', 'WindowsApps');
+  }
+
+  return path.win32.join(os.homedir(), 'AppData', 'Local', 'Microsoft', 'WindowsApps');
+};
+
+export function getExecutableSearchDirectories({ env = process.env, platform = process.platform } = {}) {
+  const delimiter = platform === 'win32' ? ';' : ':';
+  const pathValue = getEnvValue(env, ['PATH', 'Path', 'path']);
+  const directories = pathValue.split(delimiter).map((entry) => entry.trim()).filter(Boolean);
+
+  if (platform === 'win32') {
+    directories.push(getWindowsAppsDirectory(env));
+  }
+
+  const seen = new Set();
+  const unique = [];
+  for (const directory of directories) {
+    const key = normalizeSearchDirectoryKey(directory, platform);
+    if (!key || seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    unique.push(directory);
+  }
+
+  return unique;
+}
+
+export function createExecutableSearchEnv({ env = process.env, platform = process.platform } = {}) {
+  const delimiter = platform === 'win32' ? ';' : ':';
+  const pathValue = getExecutableSearchDirectories({ env, platform }).join(delimiter);
+  const nextEnv = { ...env };
+
+  if (platform === 'win32') {
+    nextEnv.PATH = pathValue;
+    nextEnv.Path = pathValue;
+    nextEnv.path = pathValue;
+  } else {
+    nextEnv.PATH = pathValue;
+  }
+
+  return nextEnv;
+}
+
+const getExecutableExtensions = ({ env = process.env, platform = process.platform } = {}) => {
+  if (platform !== 'win32') {
+    return [''];
+  }
+
+  return (env.PATHEXT || env.PathExt || env.pathext || '.EXE;.CMD;.BAT;.COM')
+    .split(';')
+    .map((ext) => ext.trim().toLowerCase())
+    .filter(Boolean)
+    .map((ext) => (ext.startsWith('.') ? ext : `.${ext}`));
+};
+
+export function findExecutableOnPath(command, {
+  env = process.env,
+  platform = process.platform,
+  fsLike = fs,
+} = {}) {
+  if (typeof command !== 'string' || command.trim().length === 0) {
+    return null;
+  }
+
+  const pathApi = platform === 'win32' ? path.win32 : path;
+  const directories = getExecutableSearchDirectories({ env, platform });
+  const extensions = getExecutableExtensions({ env, platform });
+  const commandName = command.trim();
+
+  for (const directory of directories) {
+    for (const extension of extensions) {
+      const fileName = platform === 'win32' ? `${commandName}${extension}` : commandName;
+      const candidate = pathApi.join(directory, fileName);
+      try {
+        const stats = fsLike.statSync(candidate);
+        if (!stats.isFile()) {
+          continue;
+        }
+        if (platform !== 'win32') {
+          try {
+            fsLike.accessSync(candidate, fs.constants.X_OK);
+          } catch {
+            continue;
+          }
+        }
+        return candidate;
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  return null;
+}
+
+export function resolveExecutableLaunchTarget(command, options = {}) {
+  const platform = options.platform || process.platform;
+  const resolvedPath = findExecutableOnPath(command, { ...options, platform });
+  const env = createExecutableSearchEnv({ env: options.env || process.env, platform });
+  if (resolvedPath) {
+    return { command: resolvedPath, env };
+  }
+
+  // Windows Store app execution aliases are launchable through CreateProcess
+  // but can reject fs.stat/fs.access with EACCES. Let the version probe decide.
+  if (platform === 'win32' && typeof command === 'string' && command.trim().length > 0) {
+    return { command: command.trim(), env };
+  }
+
+  return null;
+}