@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/src/adapters/emulated-services/provider.js

@@ -0,0 +1,282 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  EMULATED_SERVICES_ERROR_CODES,
+  EMULATED_SERVICES_ID,
+  EMULATED_SERVICES_PROCESS_LIMITS,
+  EMULATED_SERVICES_SUPPORTED_VERSION,
+} from "./constants.js";
+import {
+  emulatedServicesProcessError,
+  runBoundedEmulatedServicesCommand,
+  spawnManagedEmulatedServicesProcess,
+} from "./process.js";
+
+const FACTORY_KEYS = new Set([
+  "executablePath",
+  "expectedVersion",
+  "tempRoot",
+  "targetRoot",
+  "spawnImpl",
+  "fsImpl",
+  "mkdtempImpl",
+  "rmImpl",
+  "fetchImpl",
+  "sleepImpl",
+  "nowImpl",
+]);
+
+function providerError(code, message, cause) {
+  return emulatedServicesProcessError(code, message, cause);
+}
+
+function assertPortableString(value, label) {
+  if (typeof value !== "string" || value.length === 0 || /\p{Cc}/u.test(value)) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, `${label} must be a non-empty portable string`);
+  }
+  return value;
+}
+
+function assertAbsolutePath(value, label) {
+  assertPortableString(value, label);
+  if (!path.isAbsolute(value)) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, `${label} must be absolute`);
+  }
+  return value;
+}
+
+function assertRegularFile(filePath, label, fsImpl) {
+  assertAbsolutePath(filePath, label);
+  let stat;
+  try {
+    stat = fsImpl.lstatSync(filePath);
+  } catch (error) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, `${label} is unavailable`, error);
+  }
+  if (!stat.isFile() || stat.isSymbolicLink?.()) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, `${label} must be a regular non-symlink file`);
+  }
+  return filePath;
+}
+
+function isWithin(parent, candidate) {
+  const relative = path.relative(path.resolve(parent), path.resolve(candidate));
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function assertTempRootSafe(tempRoot, targetRoot) {
+  if (targetRoot && (isWithin(targetRoot, tempRoot) || isWithin(tempRoot, targetRoot))) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "Emulated Services temporary state must be outside the target root");
+  }
+}
+
+function filteredEnvironment() {
+  const allowed = new Set(["PATH", "HOME", "TMPDIR", "TEMP", "TMP", "SystemRoot", "ComSpec", "LANG", "LC_ALL", "NODE_PATH"]);
+  return Object.fromEntries(Object.entries(process.env).filter(([key]) => allowed.has(key)));
+}
+
+function parseVersion(stdout) {
+  if (typeof stdout !== "string") {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.OUTPUT_INVALID, "Emulated Services version output was not text");
+  }
+  const match = /^\s*(?:emulate(?:\s+|@))?v?(\d+\.\d+\.\d+)\s*$/iu.exec(stdout);
+  if (!match) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.OUTPUT_INVALID, "Emulated Services version output was malformed");
+  }
+  return match[1];
+}
+
+function normalizeServices(services) {
+  if (!Array.isArray(services) || services.length === 0 || services.length > EMULATED_SERVICES_PROCESS_LIMITS.maxServices) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "services must be a non-empty bounded array");
+  }
+  const normalized = services.map((service) => {
+    assertPortableString(service, "service");
+    if (!/^[a-z][a-z0-9-]*$/u.test(service)) {
+      throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "service identifiers must be portable lowercase names");
+    }
+    return service;
+  });
+  if (new Set(normalized).size !== normalized.length) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "services must not contain duplicates");
+  }
+  return normalized;
+}
+
+function normalizeRequest(request, { fsImpl, targetRoot }) {
+  if (!request || typeof request !== "object" || Array.isArray(request)) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "Emulated Services request must be an object");
+  }
+  const services = normalizeServices(request.services);
+  const basePort = request.basePort ?? 4000;
+  if (!Number.isSafeInteger(basePort) || basePort < 1 || basePort + services.length - 1 > 65535) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "basePort must provide a valid loopback port range");
+  }
+  const timeoutMs = request.timeoutMs ?? 30_000;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > EMULATED_SERVICES_PROCESS_LIMITS.maxTimeoutMs) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "timeoutMs is outside the supported bounded range");
+  }
+  let seedPath = null;
+  if (request.seedPath !== undefined && request.seedPath !== null) {
+    seedPath = assertRegularFile(request.seedPath, "seedPath", fsImpl);
+    if (targetRoot && isWithin(targetRoot, seedPath)) {
+      throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "seedPath must not be inside the target root");
+    }
+  }
+  return { services, basePort, timeoutMs, seedPath, signal: request.signal };
+}
+
+function validateSignal(signal) {
+  if (signal !== undefined && (!signal || typeof signal.aborted !== "boolean" || typeof signal.addEventListener !== "function")) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "signal must be an AbortSignal");
+  }
+}
+
+function assertNotCancelled(signal) {
+  if (signal?.aborted) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CANCELLED, "Emulated Services operation was cancelled");
+  }
+}
+
+function normalizeEndpoint(port) {
+  const endpoint = `http://127.0.0.1:${port}`;
+  const url = new URL(endpoint);
+  if (url.protocol !== "http:" || url.hostname !== "127.0.0.1") {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.ENDPOINT_INVALID, "Emulated Services endpoint was not loopback HTTP");
+  }
+  return endpoint;
+}
+
+async function waitForReady(endpoint, { fetchImpl, signal, deadline, sleepImpl, nowImpl }) {
+  while (nowImpl() < deadline) {
+    assertNotCancelled(signal);
+    try {
+      const response = await fetchImpl(endpoint, { method: "GET", redirect: "manual", signal });
+      const status = Number(response?.status);
+      if (Number.isInteger(status) && status >= 200 && status < 500) return;
+    } catch (error) {
+      if (signal?.aborted) throw providerError(EMULATED_SERVICES_ERROR_CODES.CANCELLED, "Emulated Services operation was cancelled", error);
+    }
+    const remaining = deadline - nowImpl();
+    if (remaining <= 0) break;
+    await sleepImpl(Math.min(EMULATED_SERVICES_PROCESS_LIMITS.readinessPollMs, remaining), signal);
+  }
+  throw providerError(EMULATED_SERVICES_ERROR_CODES.TIMEOUT, "Emulated Services did not become ready before the timeout");
+}
+
+function validateFactoryOptions(options) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "Emulated Services provider options must be an object");
+  }
+  for (const key of Object.keys(options)) {
+    if (!FACTORY_KEYS.has(key)) throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, `Unsupported Emulated Services option: ${key}`);
+  }
+}
+
+export function createEmulatedServicesProvider(options = {}) {
+  validateFactoryOptions(options);
+  const fsImpl = options.fsImpl ?? fs;
+  const executablePath = assertRegularFile(options.executablePath, "executablePath", fsImpl);
+  const expectedVersion = options.expectedVersion ?? EMULATED_SERVICES_SUPPORTED_VERSION;
+  if (expectedVersion !== EMULATED_SERVICES_SUPPORTED_VERSION) {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, `Only Emulated Services ${EMULATED_SERVICES_SUPPORTED_VERSION} is supported`);
+  }
+  const tempRoot = assertAbsolutePath(options.tempRoot ?? os.tmpdir(), "tempRoot");
+  const targetRoot = options.targetRoot === undefined ? null : assertAbsolutePath(options.targetRoot, "targetRoot");
+  assertTempRootSafe(tempRoot, targetRoot);
+  const mkdtempImpl = options.mkdtempImpl ?? fs.promises.mkdtemp;
+  const rmImpl = options.rmImpl ?? fs.promises.rm;
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const sleepImpl = options.sleepImpl ?? ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)));
+  const nowImpl = options.nowImpl ?? (() => Date.now());
+  if (typeof fetchImpl !== "function" || typeof mkdtempImpl !== "function" || typeof rmImpl !== "function") {
+    throw providerError(EMULATED_SERVICES_ERROR_CODES.CONFIG_INVALID, "Emulated Services host capabilities are incomplete");
+  }
+
+  return Object.freeze({
+    id: EMULATED_SERVICES_ID,
+    version: expectedVersion,
+    async start(request = {}) {
+      const normalized = normalizeRequest(request, { fsImpl, targetRoot });
+      validateSignal(normalized.signal);
+      assertNotCancelled(normalized.signal);
+      const tempPrefix = path.join(tempRoot, "forgeloop-emulated-");
+      let stateRoot = null;
+      let managed = null;
+      let result = null;
+      let operationError = null;
+      try {
+        stateRoot = await mkdtempImpl(tempPrefix);
+        assertAbsolutePath(stateRoot, "Emulated Services temporary state");
+        assertTempRootSafe(stateRoot, targetRoot);
+        const versionResult = await runBoundedEmulatedServicesCommand(executablePath, ["--version"], {
+          cwd: stateRoot,
+          env: filteredEnvironment(),
+          spawnImpl: options.spawnImpl,
+          timeoutMs: Math.min(normalized.timeoutMs, 10_000),
+        });
+        const actualVersion = parseVersion(versionResult.stdout);
+        if (actualVersion !== expectedVersion) {
+          throw providerError(EMULATED_SERVICES_ERROR_CODES.VERSION_UNSUPPORTED, `Unsupported Emulated Services version: ${actualVersion}`);
+        }
+
+        const args = ["--service", normalized.services.join(","), "--port", String(normalized.basePort)];
+        if (normalized.seedPath) args.push("--seed", normalized.seedPath);
+        managed = spawnManagedEmulatedServicesProcess(executablePath, args, {
+          cwd: stateRoot,
+          env: filteredEnvironment(),
+          spawnImpl: options.spawnImpl,
+        });
+        const deadline = nowImpl() + normalized.timeoutMs;
+        const endpoints = normalized.services.map((service, index) => ({
+          id: service,
+          endpoint: normalizeEndpoint(normalized.basePort + index),
+        }));
+        for (const service of endpoints) {
+          await waitForReady(service.endpoint, {
+            fetchImpl,
+            signal: normalized.signal,
+            deadline,
+            sleepImpl,
+            nowImpl,
+          });
+        }
+        result = {
+          provider: { id: EMULATED_SERVICES_ID, version: expectedVersion },
+          services: endpoints,
+          status: "READY",
+          diagnostics: ["Host-provided emulated services were observed on loopback"],
+          authority: "OBSERVATION",
+          evidenceAuthority: "NONE",
+          lifecycleAuthority: false,
+          completionAuthority: false,
+          persisted: false,
+          cleanup: { status: "PENDING" },
+        };
+      } catch (error) {
+        operationError = error;
+      } finally {
+        if (managed) {
+          managed.stop();
+          await managed.waitForClose();
+        }
+        if (stateRoot) {
+          try {
+            await rmImpl(stateRoot, { recursive: true, force: true });
+            if (result) result.cleanup = { status: "COMPLETED" };
+          } catch (error) {
+            const cleanupError = providerError(EMULATED_SERVICES_ERROR_CODES.CLEANUP_FAILED, "Emulated Services temporary state cleanup failed", error);
+            if (!operationError) operationError = cleanupError;
+            if (result) result.cleanup = { status: "FAILED" };
+          }
+        }
+      }
+      if (operationError) throw operationError;
+      return Object.freeze(result);
+    },
+  });
+}
+
+export { normalizeEndpoint, parseVersion };

package/src/adapters/opensrc/normalize.js

@@ -0,0 +1,90 @@
+import {
+  ADVISORY_CONTEXT_LIMITS,
+  normalizeAdvisoryRecallOptions,
+} from "../../core/advisory-context/constants.js";
+import {
+  E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+  E_ADVISORY_CONTEXT_RESULT_INVALID,
+} from "../../core/error-codes.js";
+
+function adapterError(code, message) {
+  const error = new Error(message);
+  error.name = "OpenSrcAdapterError";
+  error.code = code;
+  return error;
+}
+
+function fitText(value, maxLength) {
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, Math.max(1, maxLength - 1))}…`;
+}
+
+function lineRangeLabel(startLine, endLine) {
+  return startLine === endLine ? `L${startLine}` : `L${startLine}-L${endLine}`;
+}
+
+function normalizeMatch(match) {
+  if (!match || typeof match !== "object" || Array.isArray(match)) return null;
+  const { sourceSpec, relativePath, snippet, snippetStartLine, snippetEndLine } = match;
+  if (typeof sourceSpec !== "string" || sourceSpec === "") return null;
+  if (typeof relativePath !== "string" || relativePath === "" || relativePath.startsWith("/")) return null;
+  if (typeof snippet !== "string") return null;
+  if (!Number.isSafeInteger(snippetStartLine) || snippetStartLine < 1) return null;
+  if (!Number.isSafeInteger(snippetEndLine) || snippetEndLine < snippetStartLine) return null;
+  const range = lineRangeLabel(snippetStartLine, snippetEndLine);
+  const flatSnippet = snippet.replace(/\s+/gu, " ").trim();
+  return {
+    title: `${sourceSpec} — ${relativePath}`,
+    summary: flatSnippet === "" ? range : `${range} | ${flatSnippet}`,
+    sourceRef: `opensrc:${sourceSpec}:${relativePath}#${range}`,
+    identity: [sourceSpec, relativePath, range, snippet].join(" "),
+  };
+}
+
+/**
+ * Convert bounded deterministic search matches into ForgeLoop advisory items.
+ *
+ * Titles, summaries, and source references carry only portable relative
+ * paths; absolute cache locations never leave this boundary.
+ */
+export function normalizeOpenSrcResult(matches, {
+  limit,
+  maxItemChars,
+  maxTotalChars,
+  timeoutMs,
+} = {}) {
+  if (!Array.isArray(matches)) {
+    throw adapterError(E_ADVISORY_CONTEXT_RESULT_INVALID, "OpenSrc search matches must be an array");
+  }
+  if (matches.length > ADVISORY_CONTEXT_LIMITS.maxProviderReturnedItems) {
+    throw adapterError(
+      E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+      `OpenSrc returned ${matches.length} matches, exceeding the raw item ceiling of ${ADVISORY_CONTEXT_LIMITS.maxProviderReturnedItems}`,
+    );
+  }
+  const options = normalizeAdvisoryRecallOptions({ limit, maxItemChars, maxTotalChars, timeoutMs });
+  const prepared = [];
+  const seen = new Set();
+  for (const match of matches) {
+    const normalized = normalizeMatch(match);
+    if (!normalized) continue;
+    if (seen.has(normalized.identity)) continue;
+    seen.add(normalized.identity);
+    const summary = fitText(normalized.summary, options.maxItemChars);
+    prepared.push({ title: normalized.title, summary, sourceRef: normalized.sourceRef });
+  }
+
+  const items = [];
+  let totalChars = 0;
+  for (const candidate of prepared) {
+    if (items.length >= options.limit) break;
+    const chars = candidate.title.length + candidate.summary.length + candidate.sourceRef.length;
+    if (totalChars + chars > options.maxTotalChars) break;
+    totalChars += chars;
+    items.push(candidate);
+  }
+  if (items.length === 0 && prepared.length > 0) {
+    throw adapterError(E_ADVISORY_CONTEXT_OUTPUT_LIMIT, "OpenSrc matches cannot fit the requested output budget");
+  }
+  return { items };
+}

package/src/adapters/opensrc/process.js

@@ -0,0 +1,248 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import path from "node:path";
+
+import {
+  E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+  E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+  E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+  E_ADVISORY_CONTEXT_RESULT_INVALID,
+  E_ADVISORY_CONTEXT_TIMEOUT,
+} from "../../core/error-codes.js";
+
+export const OPENSRC_PROCESS_LIMITS = Object.freeze({
+  maxStdoutBytes: 64 * 1024,
+  maxStderrBytes: 64 * 1024,
+  terminationGraceMs: 250,
+});
+
+function processError(code, message) {
+  const error = new Error(message);
+  error.name = "OpenSrcProcessError";
+  error.code = code;
+  return error;
+}
+
+function assertSafeText(value, label) {
+  if (typeof value !== "string" || value.length === 0 || /\p{Cc}/u.test(value)) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, `${label} must be a non-empty portable string`);
+  }
+  return value;
+}
+
+function assertAbsolutePath(value, label) {
+  assertSafeText(value, label);
+  if (!path.isAbsolute(value)) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, `${label} must be an absolute path`);
+  }
+  return value;
+}
+
+function outputBytes(chunk) {
+  return Buffer.isBuffer(chunk) ? chunk.byteLength : Buffer.byteLength(String(chunk));
+}
+
+function terminateChild(child) {
+  if (!child || typeof child.kill !== "function") return;
+  try {
+    child.kill("SIGTERM");
+  } catch {
+    // The process may have exited between the limit check and kill.
+  }
+  setTimeout(() => {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      // Preserve the original timeout or output-limit error.
+    }
+  }, OPENSRC_PROCESS_LIMITS.terminationGraceMs).unref?.();
+}
+
+function waitForChildClose(child) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(fallbackTimer);
+      resolve();
+    };
+    const finishAfterClose = () => {
+      // Windows can retain a child working directory for a short interval
+      // after close; allow the OS to release it before the caller tears down
+      // a temporary project tree.
+      setTimeout(finish, 500);
+    };
+    child.once?.("close", finishAfterClose);
+    const fallbackTimer = setTimeout(finish, OPENSRC_PROCESS_LIMITS.terminationGraceMs + 1000);
+  });
+}
+
+function normalizeRunOptions({
+  cwd,
+  timeoutMs,
+  maxStdoutBytes,
+  maxStderrBytes,
+  spawnImpl,
+  env,
+} = {}) {
+  assertAbsolutePath(cwd, "OpenSrc project path");
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc timeout must be a positive integer");
+  }
+  if (!Number.isSafeInteger(maxStdoutBytes) || maxStdoutBytes < 1) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc stdout limit must be a positive integer");
+  }
+  if (!Number.isSafeInteger(maxStderrBytes) || maxStderrBytes < 1) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc stderr limit must be a positive integer");
+  }
+  if (typeof spawnImpl !== "function") {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc spawn implementation must be a function");
+  }
+  if (env !== undefined && (!env || typeof env !== "object" || Array.isArray(env))) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc process environment must be an object");
+  }
+  return {
+    cwd,
+    timeoutMs,
+    maxStdoutBytes,
+    maxStderrBytes,
+    spawnImpl,
+    env,
+  };
+}
+
+/**
+ * Run one explicitly constructed OpenSrc command.
+ *
+ * This helper is intentionally private to the adapter boundary: callers pass
+ * an absolute executable and an argv array, while this function always keeps
+ * shell execution disabled and never returns raw stderr in an error message.
+ */
+export function runOpenSrcCommand(executablePath, args, options = {}) {
+  assertAbsolutePath(executablePath, "OpenSrc executable path");
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string" || /\p{Cc}/u.test(arg))) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "OpenSrc arguments must be a portable string array");
+  }
+
+  const runOptions = normalizeRunOptions({
+    cwd: options.cwd,
+    timeoutMs: options.timeoutMs,
+    maxStdoutBytes: options.maxStdoutBytes ?? OPENSRC_PROCESS_LIMITS.maxStdoutBytes,
+    maxStderrBytes: options.maxStderrBytes ?? OPENSRC_PROCESS_LIMITS.maxStderrBytes,
+    spawnImpl: options.spawnImpl ?? nodeSpawn,
+    env: options.env,
+  });
+
+  const startedAt = Date.now();
+  let child;
+  try {
+    child = runOptions.spawnImpl(executablePath, [...args], {
+      cwd: runOptions.cwd,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+      ...(runOptions.env ? { env: { ...process.env, ...runOptions.env } } : {}),
+    });
+  } catch (error) {
+    throw processError(
+      E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+      error?.code === "ENOENT" ? "OpenSrc executable is unavailable" : "Unable to start OpenSrc",
+      error,
+    );
+  }
+
+  if (!child || !child.stdout || !child.stderr || typeof child.on !== "function") {
+    terminateChild(child);
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE, "OpenSrc process did not expose piped stdout and stderr");
+  }
+
+  return new Promise((resolve, reject) => {
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    const stdoutChunks = [];
+    let settled = false;
+    let timer = null;
+
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      child.stdout?.removeAllListeners?.("data");
+      child.stderr?.removeAllListeners?.("data");
+    };
+
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      terminateChild(child);
+      child.stdout?.resume?.();
+      child.stderr?.resume?.();
+      waitForChildClose(child).then(() => reject(error));
+    };
+
+    const succeed = (code, signal) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (code !== 0) {
+        reject(processError(
+          E_ADVISORY_CONTEXT_RESULT_INVALID,
+          `OpenSrc exited unsuccessfully (${code ?? "null"}/${signal ?? "none"})`,
+        ));
+        return;
+      }
+      resolve({
+        stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+        stderrBytes,
+        stdoutBytes,
+        durationMs: Math.max(0, Date.now() - startedAt),
+      });
+    };
+
+    child.stdout.on("data", (chunk) => {
+      stdoutBytes += outputBytes(chunk);
+      if (stdoutBytes > runOptions.maxStdoutBytes) {
+        fail(processError(
+          E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+          `OpenSrc stdout exceeded ${runOptions.maxStdoutBytes} bytes`,
+        ));
+        return;
+      }
+      stdoutChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    });
+    child.stderr.on("data", (chunk) => {
+      stderrBytes += outputBytes(chunk);
+      if (stderrBytes > runOptions.maxStderrBytes) {
+        fail(processError(
+          E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+          `OpenSrc stderr exceeded ${runOptions.maxStderrBytes} bytes`,
+        ));
+      }
+    });
+    child.on("error", (error) => {
+      fail(processError(
+        E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+        error?.code === "ENOENT" ? "OpenSrc executable is unavailable" : "OpenSrc process failed",
+        error,
+      ));
+    });
+    child.on("close", (code, signal) => succeed(code, signal));
+    timer = setTimeout(() => {
+      fail(processError(
+        E_ADVISORY_CONTEXT_TIMEOUT,
+        `OpenSrc exceeded the ${runOptions.timeoutMs}ms timeout`,
+      ));
+    }, runOptions.timeoutMs);
+  });
+}
+
+export function parseOpenSrcVersion(stdout) {
+  if (typeof stdout !== "string") {
+    throw processError(E_ADVISORY_CONTEXT_RESULT_INVALID, "OpenSrc version output was not text");
+  }
+  const match = /^\s*opensrc\s+([^\s]+)(?:\s|$)/iu.exec(stdout);
+  if (!match) {
+    throw processError(E_ADVISORY_CONTEXT_RESULT_INVALID, "OpenSrc version output did not contain a qualified version");
+  }
+  return match[1];
+}
+
+export { processError as openSrcProcessError };