@bo-agent/pwsh-local 0.0.2

package/src/resolve.ts

@@ -0,0 +1,79 @@
+/**
+ * PowerShell executable resolution, dependency-free so non-package consumers
+ * (the repository's coverage-gate probe in `vitest.config.ts`) can share the
+ * ONE resolution definition with the executor and its suites — a probe that
+ * resolved differently from the code under test could exempt a file whose
+ * suites actually run.
+ *
+ * @module @bo-agent/pwsh-local/resolve
+ */
+
+import { lstatSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Well-known Windows PowerShell install locations plus PATH entries, newest
+ * first. Explicitly parameterized (env) so resolution is a pure function of
+ * its inputs on every platform.
+ * @param env - the environment to probe; defaults to the process environment.
+ * @returns candidate `pwsh` executable paths in resolution order.
+ */
+export function candidatePwshPaths(env: NodeJS.ProcessEnv = process.env): string[] {
+  const programFiles = env.ProgramFiles ?? 'C:\\Program Files'
+  const systemRoot = env.SystemRoot ?? 'C:\\Windows'
+  const candidates = [
+    join(programFiles, 'PowerShell', '7', 'pwsh.exe'),
+  ]
+  // Microsoft Store installs (and any user-added location) live on PATH;
+  // entries may carry surrounding quotes from `setx`-style definitions.
+  for (const entry of (env.PATH ?? '').split(';')) {
+    const trimmed = entry.trim().replace(/^"|"$/g, '')
+    if (trimmed.length === 0) continue
+    candidates.push(join(trimmed, 'pwsh.exe'))
+  }
+  // Windows PowerShell 5.1 remains the last-resort fallback on legacy hosts.
+  candidates.push(join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'))
+  return candidates
+}
+
+/**
+ * Whether a candidate can be spawned. lstat opens the entry itself instead of
+ * following reparse points, so it sees the Store app execution alias where
+ * stat hits the target's ACL (EACCES); Node reports that alias as a symlink
+ * on current releases and as a plain file on older ones, and CreateProcess
+ * resolves either shape. A real directory never matches.
+ */
+function candidateExists(candidate: string): boolean {
+  try {
+    const stat = lstatSync(candidate)
+    return stat.isFile() || stat.isSymbolicLink()
+  } catch {
+    // ENOENT (the candidate vanished between listing and probing) is the only
+    // expected failure; any other error names an unspawnable path, so false
+    // is the safe answer for it too.
+    return false
+  }
+}
+
+/**
+ * Resolve the pwsh executable this executor spawns.
+ * @param configured - an explicit `pwshPath` config value, trusted as-is.
+ * @param env - the environment to probe on Windows; defaults to the process environment.
+ * @param platform - the platform to resolve for; defaults to the process platform.
+ * @returns the first existing well-known location on Windows (PowerShell 7
+ *   install, a PATH entry such as the Microsoft Store install, then Windows
+ *   PowerShell 5.1), else `pwsh` for PATH resolution.
+ */
+export function resolvePwshPath(
+  configured?: string,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  if (configured !== undefined && configured.length > 0) return configured
+  if (platform === 'win32') {
+    for (const candidate of candidatePwshPaths(env)) {
+      if (candidateExists(candidate)) return candidate
+    }
+  }
+  return 'pwsh'
+}

package/src/timeout.ts

@@ -0,0 +1,112 @@
+/**
+ * Minimal timeout + deadline primitives used by the pwsh-local executor.
+ * Inlined here (rather than imported from a separate `@bo-agent/timeout`
+ * package) to keep the dependency surface small — same pattern as
+ * `@bo-agent/bash-local`.
+ *
+ * @module @bo-agent/pwsh-local/timeout
+ */
+
+/**
+ * Largest value `setTimeout` can express as a 32-bit signed milliseconds
+ * delay. Anything larger would wrap to a near-immediate fire. Inlined to
+ * mirror Node's `TIMEOUT_MAX` and to keep the dependency surface small.
+ */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647
+
+/**
+ * Clamp a per-call value against a configured range. The default applies
+ * first; the maximum caps any explicit caller-supplied value.
+ * @param value - the requested value (may be undefined).
+ * @param defaultValue - the value used when none is requested.
+ * @param maxValue - the upper bound for explicit values.
+ * @param name - label prefixed to thrown errors.
+ * @returns a positive finite value within [1, maxValue].
+ * @throws Error when neither default nor requested value is a positive finite
+ *   number, or when maxValue itself is invalid.
+ */
+export function clampTimeout(
+  value: number | undefined,
+  defaultValue: number,
+  maxValue: number,
+  name: string,
+): number {
+  if (!Number.isFinite(maxValue) || maxValue <= 0) {
+    throw new Error(`${name}: maxValue must be a positive finite number`)
+  }
+  const candidate = value ?? defaultValue
+  if (!Number.isFinite(candidate) || candidate <= 0) {
+    throw new Error(`${name}: value must be a positive finite number`)
+  }
+  return Math.min(candidate, maxValue)
+}
+
+/** A symbol tagged on the AbortSignal's reason so the timeout reason is identifiable. */
+export const TIMEOUT_REASON = Symbol.for('@bo-agent/pwsh-local/TIMEOUT_REASON')
+
+/**
+ * Combine a caller's optional AbortSignal with a millisecond timeout into a
+ * single controller. Either side aborts the controller; disposal clears the
+ * timer and removes the upstream listener, so the result is safe to discard
+ * at end of scope via the `using` declaration.
+ */
+export interface DeadlineHandle {
+  readonly signal: AbortSignal
+  [Symbol.dispose](): void
+}
+
+/**
+ * Build a deadline fused from the caller's signal and the executor's
+ * timeout. The returned controller aborts on whichever fires first; a
+ * successful command observes `signal.aborted === false`. The timeout
+ * reason is tagged so callers can tell timeout apart from upstream
+ * cancellation.
+ * @param signal - caller's upstream signal; may be undefined.
+ * @param timeoutMs - milliseconds until the timeout branch aborts.
+ * @param reason - human-readable label for the timeout reason; only used
+ *   for tagging, never surfaced to the user.
+ */
+export function deadline(
+  signal: AbortSignal | undefined,
+  timeoutMs: number,
+  reason: string,
+): DeadlineHandle {
+  const controller = new AbortController()
+  const onAbort = (): void => controller.abort(signal?.reason)
+  if (signal !== undefined) {
+    if (signal.aborted) {
+      controller.abort(signal.reason)
+    } else {
+      signal.addEventListener('abort', onAbort, { once: true })
+    }
+  }
+  // `setTimeout` cannot express delays above MAX_TIMER_DELAY_MS without
+  // wrapping; cap the request so the timeout branch actually fires when
+  // promised.
+  const safeTimeout = Math.min(timeoutMs, MAX_TIMER_DELAY_MS)
+  const timer = setTimeout(() => {
+    controller.abort(TIMEOUT_REASON)
+  }, safeTimeout)
+  return {
+    signal: controller.signal,
+    [Symbol.dispose](): void {
+      clearTimeout(timer)
+      if (signal !== undefined) signal.removeEventListener('abort', onAbort)
+    },
+  }
+}
+
+/**
+ * Return the tagged reason if the controller aborted because of the timeout
+ * branch (or upstream cancellation that mirrored it). Other abort reasons
+ * resolve as the caller's own cancellation; undefined means the controller
+ * is still live.
+ * @param signal - a controller's signal after a wait.
+ * @param expected - the label passed to {@link deadline}; matched against
+ *   the symbol tag, so the timeout reason identifies itself.
+ */
+export function timeoutOf(signal: AbortSignal, _expected: string): symbol | undefined {
+  if (!signal.aborted) return undefined
+  if (signal.reason === TIMEOUT_REASON) return TIMEOUT_REASON
+  return undefined
+}

package/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "compilerOptions": {
+    "target": "es2024",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "sourceMap": true,
+    "declarationMap": true,
+    "composite": true,
+    "incremental": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true,
+    "verbatimModuleSyntax": false,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "types": ["node"],
+    "outDir": "lib",
+    "rootDir": "src",
+    "tsBuildInfoFile": "lib/.tsbuildinfo",
+    "paths": {
+      "@bo-agent/inline": ["../inline/src"],
+      "@bo-agent/shell": ["../shell/src"],
+      "@bo-agent/subprocess": ["../subprocess/src"]
+    }
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../inline" },
+    { "path": "../subprocess" },
+    { "path": "../shell" }
+  ]
+}