@cassiomc1/forgeloop 1.10.2 → 1.11.0

package/src/persistent-transport/framing.js

@@ -0,0 +1,61 @@
+import { PERSISTENT_TRANSPORT_DEFAULTS } from "./constants.js";
+import { PERSISTENT_TRANSPORT_ERROR_CODES, persistentTransportError } from "./errors.js";
+
+export function encodeFrame(value, { maxFrameBytes = PERSISTENT_TRANSPORT_DEFAULTS.maxResponseFrameBytes } = {}) {
+  let payload;
+  try {
+    payload = Buffer.from(JSON.stringify(value), "utf8");
+  } catch (error) {
+    throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.FRAME_INVALID, `Unable to encode transport frame: ${error.message}`);
+  }
+  if (payload.length > maxFrameBytes) {
+    throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.FRAME_TOO_LARGE, `Transport frame exceeds ${maxFrameBytes} bytes`);
+  }
+  const frame = Buffer.allocUnsafe(4 + payload.length);
+  frame.writeUInt32BE(payload.length, 0);
+  payload.copy(frame, 4);
+  return frame;
+}
+
+export class FrameDecoder {
+  #buffer = Buffer.alloc(0);
+  #maxFrameBytes;
+
+  constructor({ maxFrameBytes = PERSISTENT_TRANSPORT_DEFAULTS.maxRequestFrameBytes } = {}) {
+    this.#maxFrameBytes = maxFrameBytes;
+  }
+
+  push(chunk) {
+    if (!Buffer.isBuffer(chunk)) chunk = Buffer.from(chunk);
+    this.#buffer = this.#buffer.length === 0 ? chunk : Buffer.concat([this.#buffer, chunk]);
+    const frames = [];
+    while (this.#buffer.length >= 4) {
+      const length = this.#buffer.readUInt32BE(0);
+      if (length > this.#maxFrameBytes) {
+        throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.FRAME_TOO_LARGE, `Transport frame exceeds ${this.#maxFrameBytes} bytes`, { length });
+      }
+      if (this.#buffer.length < 4 + length) break;
+      frames.push(this.#buffer.subarray(4, 4 + length));
+      this.#buffer = this.#buffer.subarray(4 + length);
+    }
+    return frames;
+  }
+
+  end() {
+    if (this.#buffer.length !== 0) {
+      throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.FRAME_INVALID, "Transport stream ended with a truncated frame");
+    }
+  }
+
+  get bufferedBytes() {
+    return this.#buffer.length;
+  }
+}
+
+export function parseFrame(frame) {
+  try {
+    return JSON.parse(frame.toString("utf8"));
+  } catch (error) {
+    throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.FRAME_INVALID, `Transport frame is not valid JSON: ${error.message}`);
+  }
+}

package/src/persistent-transport/lifecycle.js

@@ -0,0 +1,116 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, unlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { acquireRepositoryIndexLock } from "../repository-index/lock.js";
+import { processIsAlive, processCommandLine } from "../repository-index/status.js";
+import { getPackageRoot } from "../core/templates.js";
+import { getPersistentTransportPaths } from "./paths.js";
+import { PERSISTENT_TRANSPORT_DEFAULTS, PERSISTENT_TRANSPORT_PROTOCOL_VERSION } from "./constants.js";
+import { PERSISTENT_TRANSPORT_ERROR_CODES, persistentTransportError } from "./errors.js";
+import { readPersistentTransportState, removePersistentTransportState } from "./state.js";
+import { inspectPersistentTransportOwnership, terminateOwnedPersistentTransport } from "./ownership.js";
+
+async function readPackageVersion() {
+  const packageJson = await readFile(path.join(getPackageRoot(), "package.json"), "utf8");
+  return JSON.parse(packageJson).version ?? null;
+}
+
+async function removeEndpoint(endpoint, platform = process.platform) {
+  if (platform === "win32" || typeof endpoint !== "string") return;
+  try {
+    await unlink(endpoint);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+}
+
+export async function ensurePersistentTransportDirectory({ homeDirectory = os.homedir() } = {}) {
+  const paths = getPersistentTransportPaths({ homeDirectory });
+  await mkdir(paths.root, { recursive: true, mode: 0o700 });
+  return paths;
+}
+
+export async function inspectPersistentTransport({ homeDirectory = os.homedir(), processApi = process, processInspector = {} } = {}) {
+  const paths = getPersistentTransportPaths({ homeDirectory });
+  const { state, invalid } = await readPersistentTransportState(paths.statePath);
+  if (invalid) return { status: "STALE", running: false, owned: false, paths, state: null, reason: "STATE_INVALID" };
+  if (!state) return { status: "NOT_RUNNING", running: false, owned: false, paths, state: null };
+  const ownership = await inspectPersistentTransportOwnership(state, { processApi, processInspector, expectedEndpoint: paths.endpoint });
+  if (!ownership.running && ownership.reason === "PROCESS_EXITED") return { status: "STALE", running: false, owned: true, paths, state, reason: ownership.reason };
+  if (!ownership.owned) return { status: "OWNERSHIP_UNVERIFIED", running: false, owned: false, paths, state, reason: ownership.reason };
+  const packageVersion = await readPackageVersion();
+  if (state.protocolVersion !== PERSISTENT_TRANSPORT_PROTOCOL_VERSION || (packageVersion && state.forgeLoopVersion !== packageVersion)) {
+    return { status: "INCOMPATIBLE", running: true, owned: true, paths, state, reason: "VERSION_MISMATCH", packageVersion, ownershipMode: ownership.ownershipMode };
+  }
+  return { status: "READY", running: true, owned: true, paths, state, packageVersion, ownershipMode: ownership.ownershipMode };
+}
+
+export async function getPersistentTransportStatus(options = {}) {
+  const inspection = await inspectPersistentTransport(options);
+  return {
+    schemaVersion: 1,
+    status: inspection.status,
+    running: inspection.running,
+    owned: inspection.owned,
+    protocolVersion: inspection.state?.protocolVersion ?? null,
+    forgeLoopVersion: inspection.state?.forgeLoopVersion ?? null,
+  };
+}
+
+export async function cleanPersistentTransportState(inspection, { processApi = process } = {}) {
+  if (!inspection?.state || inspection.owned !== true) return;
+  if (inspection.owned && inspection.running) {
+    await terminateOwnedPersistentTransport(inspection.state, { processApi, expectedEndpoint: inspection.paths.endpoint });
+    const deadline = Date.now() + 1_000;
+    while (Date.now() < deadline && processIsAlive(inspection.state.pid, processApi)) {
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+  }
+  await removePersistentTransportState(inspection.paths.statePath, inspection.state.nonce);
+  await removeEndpoint(inspection.paths.endpoint);
+}
+
+export async function startPersistentSearchHost({ homeDirectory = os.homedir(), idleTimeoutMs = PERSISTENT_TRANSPORT_DEFAULTS.idleTimeoutMs, env = {}, spawnImpl = spawn } = {}) {
+  const paths = await ensurePersistentTransportDirectory({ homeDirectory });
+  const entrypoint = path.join(getPackageRoot(), "src", "persistent-transport", "server.js");
+  const args = [entrypoint, "--persistent-transport-server", `--scope-id=${paths.scopeId}`, `--home-directory=${homeDirectory}`, `--idle-timeout-ms=${String(idleTimeoutMs)}`];
+  let child;
+  try {
+    child = spawnImpl(process.execPath, args, {
+      cwd: getPackageRoot(),
+      env: {
+        ...process.env,
+        ...env,
+        HOME: homeDirectory,
+        USERPROFILE: homeDirectory,
+        FORGELOOP_PERSISTENT_TRANSPORT_HOME: homeDirectory,
+        FORGELOOP_PERSISTENT_TRANSPORT_SCOPE: paths.scopeId,
+      },
+      detached: true,
+      stdio: "ignore",
+      shell: false,
+      windowsHide: true,
+    });
+  } catch (cause) {
+    throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.START_FAILED, `Unable to start persistent search host: ${cause.message}`, { cause });
+  }
+  child.unref?.();
+  return { child, paths, entrypoint };
+}
+
+export async function acquirePersistentTransportStartupLock({ homeDirectory = os.homedir(), tryOnly = false } = {}) {
+  const paths = await ensurePersistentTransportDirectory({ homeDirectory });
+  return acquireRepositoryIndexLock(paths.lockPath, "persistent-search-host-startup", { timeoutMs: PERSISTENT_TRANSPORT_DEFAULTS.startupTimeoutMs, tryOnly });
+}
+
+export async function removeDeadPersistentTransport({ homeDirectory = os.homedir() } = {}) {
+  const inspection = await inspectPersistentTransport({ homeDirectory });
+  if (inspection.status !== "STALE") return inspection;
+  await removePersistentTransportState(inspection.paths.statePath, inspection.state?.nonce ?? null);
+  await removeEndpoint(inspection.paths.endpoint);
+  return { ...inspection, removed: true };
+}
+
+export { processIsAlive, processCommandLine };

package/src/persistent-transport/ownership.js

@@ -0,0 +1,184 @@
+import net from "node:net";
+
+import { processCommandLine, processIsAlive } from "../repository-index/status.js";
+import { PERSISTENT_TRANSPORT_DEFAULTS } from "./constants.js";
+import { PERSISTENT_TRANSPORT_ERROR_CODES, persistentTransportError } from "./errors.js";
+import { encodeFrame, FrameDecoder, parseFrame } from "./framing.js";
+import { createRequest, validateResponse } from "./protocol.js";
+
+const ENDPOINT_PROBE_TIMEOUT_MS = 1_000;
+
+function comparable(value) {
+  if (process.platform !== "win32") return value;
+  return value.toLowerCase().replaceAll("\\", "/");
+}
+
+function endpointRequest(state, method = null, params = {}, timeoutMs = ENDPOINT_PROBE_TIMEOUT_MS) {
+  return new Promise((resolve, reject) => {
+    if (typeof state.endpoint !== "string" || state.endpoint.length === 0) {
+      reject(persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.OWNERSHIP_UNVERIFIED, "Persistent search host endpoint is invalid"));
+      return;
+    }
+    const socket = net.createConnection(state.endpoint);
+    const decoder = new FrameDecoder({ maxFrameBytes: PERSISTENT_TRANSPORT_DEFAULTS.maxResponseFrameBytes });
+    const handshakeRequest = createRequest("handshake", { scopeId: state.scopeId });
+    let activeRequest = handshakeRequest;
+    let handshakeResult = null;
+    let settled = false;
+    const timer = setTimeout(() => finish(reject, persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.TIMEOUT, "Timed out verifying the persistent search host endpoint")), timeoutMs);
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.off("data", onData);
+      socket.off("error", onError);
+      socket.off("end", onEnd);
+      socket.destroy();
+      fn(value);
+    };
+    const send = (request) => {
+      activeRequest = request;
+      try {
+        socket.write(encodeFrame(request, { maxFrameBytes: PERSISTENT_TRANSPORT_DEFAULTS.maxRequestFrameBytes }));
+      } catch (error) {
+        finish(reject, error);
+      }
+    };
+    const onData = (chunk) => {
+      try {
+        for (const frame of decoder.push(chunk)) {
+          const response = validateResponse(parseFrame(frame), activeRequest.id);
+          if (!response.ok) {
+            finish(reject, persistentTransportError(response.error.code, response.error.message));
+            return;
+          }
+          if (activeRequest === handshakeRequest) {
+            handshakeResult = response.result;
+            if (!handshakeResult || handshakeResult.pid !== state.pid
+              || handshakeResult.nonce !== state.nonce
+              || handshakeResult.scopeId !== state.scopeId
+              || handshakeResult.protocolVersion !== state.protocolVersion
+              || handshakeResult.forgeLoopVersion !== state.forgeLoopVersion) {
+              finish(reject, persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.OWNERSHIP_UNVERIFIED, "Persistent search host endpoint identity does not match its state"));
+              return;
+            }
+            if (method === null) {
+              finish(resolve, response);
+              return;
+            }
+            send(createRequest(method, params));
+            continue;
+          }
+          finish(resolve, response);
+          return;
+        }
+      } catch (error) {
+        finish(reject, error);
+      }
+    };
+    const onError = (cause) => finish(reject, persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.UNAVAILABLE, `Persistent search host endpoint failed: ${cause.code ?? cause.message}`));
+    const onEnd = () => finish(reject, persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.UNAVAILABLE, "Persistent search host endpoint closed the connection"));
+    socket.on("data", onData);
+    socket.once("error", onError);
+    socket.once("end", onEnd);
+    socket.once("connect", () => {
+      socket.setNoDelay?.(true);
+      send(handshakeRequest);
+    });
+  });
+}
+
+async function endpointMatchesState(state, expectedEndpoint) {
+  if (typeof expectedEndpoint === "string" && comparable(state.endpoint) !== comparable(expectedEndpoint)) return false;
+  try {
+    await endpointRequest(state);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function validPersistentTransportState(state) {
+  if (!state || state.schemaVersion !== 1) return false;
+  if (!Number.isInteger(state.pid) || state.pid <= 0) return false;
+  if (typeof state.nonce !== "string" || typeof state.scopeId !== "string") return false;
+  if (typeof state.entrypoint !== "string") return false;
+  return typeof state.endpoint === "string" && state.endpoint.length > 0;
+}
+
+function ownershipResult(state, owned, ownershipMode = null) {
+  return {
+    owned,
+    running: owned,
+    pid: state.pid,
+    ownershipMode,
+    reason: owned ? null : "PROCESS_IDENTITY_UNVERIFIED",
+    commandLine: null,
+  };
+}
+
+async function inspectEndpointIdentity(state, expectedEndpoint) {
+  const owned = await endpointMatchesState(state, expectedEndpoint);
+  return ownershipResult(state, owned, owned ? "ENDPOINT_HANDSHAKE" : null);
+}
+
+function inspectCommandLineIdentity(state, commandLine) {
+  const command = comparable(commandLine);
+  const entrypoint = comparable(state.entrypoint);
+  const scopeMarker = comparable(state.scopeId);
+  const owned = command.includes(entrypoint) && command.includes("--persistent-transport-server") && command.includes(scopeMarker);
+  return ownershipResult(state, owned, owned ? "PROCESS_COMMAND_LINE" : null);
+}
+
+export async function inspectPersistentTransportOwnership(state, {
+  processApi = process,
+  processInspector = {},
+  expectedEndpoint = null,
+} = {}) {
+  if (!validPersistentTransportState(state)) {
+    return { owned: false, running: false, reason: "STATE_INVALID" };
+  }
+  if (typeof expectedEndpoint === "string" && comparable(state.endpoint) !== comparable(expectedEndpoint)) {
+    return { owned: false, running: false, reason: "STATE_ENDPOINT_MISMATCH" };
+  }
+  const alive = (processInspector.isAlive ?? ((pid) => processIsAlive(pid, processApi)))(state.pid);
+  if (!alive) return { owned: true, running: false, reason: "PROCESS_EXITED", pid: state.pid };
+  if (process.platform === "win32" && processInspector.commandLine === undefined) {
+    return inspectEndpointIdentity(state, expectedEndpoint);
+  }
+  const commandLine = processInspector.commandLine === undefined
+    ? await processCommandLine(state.pid, { platform: process.platform })
+    : await processInspector.commandLine(state.pid);
+  if (typeof commandLine !== "string" || commandLine.length === 0) {
+    return inspectEndpointIdentity(state, expectedEndpoint);
+  }
+  return inspectCommandLineIdentity(state, commandLine);
+}
+
+export async function requireOwnedPersistentTransport(state, options = {}) {
+  const inspection = await inspectPersistentTransportOwnership(state, options);
+  if (!inspection.owned) {
+    throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.OWNERSHIP_UNVERIFIED, "Persistent search host ownership could not be verified");
+  }
+  return inspection;
+}
+
+export async function terminateOwnedPersistentTransport(state, { signal = "SIGTERM", processApi = process, ...options } = {}) {
+  const inspection = await requireOwnedPersistentTransport(state, { processApi, ...options });
+  if (!inspection.running) return { ...inspection, terminated: false };
+  if (inspection.ownershipMode === "ENDPOINT_HANDSHAKE") {
+    try {
+      const response = await endpointRequest(state, "transport.shutdown", { nonce: state.nonce });
+      if (!response.result || response.result.status !== "SHUTTING_DOWN") throw new Error("Persistent search host did not accept shutdown");
+    } catch (cause) {
+      throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.OWNERSHIP_UNVERIFIED, "Owned persistent search host could not be shut down through its verified endpoint", { cause });
+    }
+    return { ...inspection, terminated: true, termination: "ENDPOINT_SHUTDOWN" };
+  }
+  try {
+    processApi.kill(state.pid, signal);
+  } catch (error) {
+    if (error.code !== "ESRCH") throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.OWNERSHIP_UNVERIFIED, "Owned persistent search host could not be terminated", { cause: error });
+  }
+  return { ...inspection, terminated: true };
+}

package/src/persistent-transport/paths.js

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+
+import { getPersistentTransportRoot } from "./constants.js";
+
+function scopeHash(homeDirectory) {
+  return createHash("sha256").update(String(homeDirectory)).digest("hex").slice(0, 20);
+}
+
+export function getPersistentTransportScopeId({ homeDirectory = os.homedir() } = {}) {
+  return `user-${scopeHash(homeDirectory)}`;
+}
+
+export function getPersistentTransportPaths({ homeDirectory = os.homedir(), platform = process.platform } = {}) {
+  const root = getPersistentTransportRoot({ homeDirectory });
+  const scopeId = getPersistentTransportScopeId({ homeDirectory });
+  return {
+    root,
+    scopeId,
+    statePath: path.join(root, "state.json"),
+    lockPath: path.join(root, "startup.lock"),
+    endpoint: platform === "win32"
+      ? `\\\\.\\pipe\\forgeloop-persistent-search-${scopeHash(homeDirectory)}`
+      // macOS limits Unix-domain socket paths to a small fixed length. Keep
+      // the user-scoped endpoint in the local temporary namespace while the
+      // authoritative ownership state remains under the user's ForgeLoop
+      // directory.
+      : path.join(os.tmpdir(), `forgeloop-persistent-search-${scopeHash(homeDirectory)}.sock`),
+  };
+}

package/src/persistent-transport/protocol.js

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+
+import { PERSISTENT_TRANSPORT_METHODS, PERSISTENT_TRANSPORT_PROTOCOL_VERSION } from "./constants.js";
+import { PERSISTENT_TRANSPORT_ERROR_CODES, persistentTransportError } from "./errors.js";
+
+const MAX_REQUEST_ID_CHARS = 128;
+export const PERSISTENT_SEARCH_QUERY_KEYS = Object.freeze([
+  "pattern", "globs", "types", "context", "beforeContext", "afterContext", "maxCount",
+  "filesWithMatches", "stats", "fixedStrings", "ignoreCase", "smartCase", "wordRegexp",
+]);
+
+function invalid(message, details = {}) {
+  return persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.INVALID_REQUEST, message, details);
+}
+
+export function validateRequest(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw invalid("Transport request must be an object");
+  if (value.protocolVersion !== PERSISTENT_TRANSPORT_PROTOCOL_VERSION) {
+    throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.PROTOCOL_MISMATCH, `Unsupported transport protocol version: ${value.protocolVersion ?? "missing"}`, { expectedVersion: PERSISTENT_TRANSPORT_PROTOCOL_VERSION, actualVersion: value.protocolVersion });
+  }
+  if (typeof value.id !== "string" || value.id.length === 0 || value.id.length > MAX_REQUEST_ID_CHARS) throw invalid("Transport request id is invalid");
+  if (typeof value.method !== "string" || !PERSISTENT_TRANSPORT_METHODS.includes(value.method)) throw invalid(`Unsupported transport method: ${value.method ?? "missing"}`);
+  if (value.params !== undefined && (!value.params || typeof value.params !== "object" || Array.isArray(value.params))) throw invalid("Transport request params must be an object");
+  return {
+    protocolVersion: value.protocolVersion,
+    id: value.id,
+    method: value.method,
+    params: value.params ?? {},
+  };
+}
+
+export function createRequest(method, params = {}, id = randomUUID()) {
+  return { protocolVersion: PERSISTENT_TRANSPORT_PROTOCOL_VERSION, id, method, params };
+}
+
+export function createSuccessResponse(id, result) {
+  return { protocolVersion: PERSISTENT_TRANSPORT_PROTOCOL_VERSION, id, ok: true, result };
+}
+
+export function createErrorResponse(id, error) {
+  return {
+    protocolVersion: PERSISTENT_TRANSPORT_PROTOCOL_VERSION,
+    id: id ?? null,
+    ok: false,
+    error: {
+      code: error?.code ?? PERSISTENT_TRANSPORT_ERROR_CODES.INVALID_RESPONSE,
+      message: String(error?.message ?? "Transport request failed").slice(0, 4_000),
+      ...(error?.expectedVersion !== undefined ? { expectedVersion: error.expectedVersion } : {}),
+      ...(error?.actualVersion !== undefined ? { actualVersion: error.actualVersion } : {}),
+    },
+  };
+}
+
+export function validateResponse(value, expectedId) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.INVALID_RESPONSE, "Transport response must be an object");
+  }
+  if (value.protocolVersion !== PERSISTENT_TRANSPORT_PROTOCOL_VERSION) {
+    throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.PROTOCOL_MISMATCH, "Transport response protocol version is unsupported", { expectedVersion: PERSISTENT_TRANSPORT_PROTOCOL_VERSION, actualVersion: value.protocolVersion });
+  }
+  if (value.id !== expectedId) throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.INVALID_RESPONSE, "Transport response id does not match the request");
+  if (typeof value.ok !== "boolean") throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.INVALID_RESPONSE, "Transport response ok flag is invalid");
+  if (!value.ok && (!value.error || typeof value.error !== "object" || typeof value.error.code !== "string")) throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.INVALID_RESPONSE, "Transport error response is malformed");
+  return value;
+}
+
+export function assertSearchParams(params) {
+  if (!params || typeof params !== "object" || Array.isArray(params)) throw invalid("repository.search params must be an object");
+  if (typeof params.repository !== "string" || !path.isAbsolute(params.repository) || params.repository.length > 4_096) throw invalid("repository.search repository identity is invalid");
+  if (!params.query || typeof params.query !== "object" || Array.isArray(params.query)) throw invalid("repository.search query must be an object");
+  const unknownKeys = Object.keys(params.query).filter((key) => !PERSISTENT_SEARCH_QUERY_KEYS.includes(key));
+  if (unknownKeys.length > 0) throw invalid(`repository.search query contains unsupported fields: ${unknownKeys.join(", ")}`);
+  if (typeof params.query.pattern !== "string" || params.query.pattern.length === 0 || params.query.pattern.length > 4_096) throw invalid("repository.search query pattern is invalid");
+  return params;
+}
+
+export function projectSearchQuery(query) {
+  const projected = {
+    pattern: query.pattern,
+    globs: query.globs,
+    types: query.types,
+    context: query.context,
+    beforeContext: query.beforeContext,
+    afterContext: query.afterContext,
+    maxCount: query.maxCount,
+    filesWithMatches: query.filesWithMatches,
+    stats: query.stats,
+    fixedStrings: query.fixedStrings,
+    ignoreCase: query.ignoreCase,
+    smartCase: query.smartCase,
+    wordRegexp: query.wordRegexp,
+  };
+  return Object.fromEntries(Object.entries(projected).filter(([, value]) => value !== undefined));
+}