sift-light 1.0.0

package/src/inspect.ts

@@ -0,0 +1,271 @@
+import { resolve } from "node:path";
+import { abortError, CursorError, SiftLightError } from "./errors.js";
+import { SearchPathPolicy } from "./path-policy.js";
+import type { CodeStructureProvider, StructureInspection } from "./structure.js";
+import {
+  assertExistingSearchPath,
+  getSourceRevision,
+  readSourceRange,
+  sameSourceRevision,
+  SourceBudgetTooSmallError,
+  SourceTooLargeError,
+  type SourceRangeRead,
+} from "./source.js";
+import { SnapshotStore } from "./snapshot-store.js";
+import {
+  MAX_LINE_CHARACTERS,
+  MAX_RESULT_BYTES,
+  type MatchRecord,
+  type SiftLightDetails,
+  type SiftLightResult,
+  type SourceExcerptDetails,
+  type SourceRevision,
+  type StructureDetails,
+} from "./types.js";
+
+export interface InspectInput {
+  path?: string;
+  line?: number;
+  cursor?: string;
+  matchIndex?: number;
+}
+
+export interface InspectOptions {
+  snapshots: SnapshotStore;
+  structure?: CodeStructureProvider;
+}
+
+export interface InspectionTarget {
+  path: string;
+  absolutePath: string;
+  line: number;
+  retainedMatch?: MatchRecord;
+  expectedRevision?: SourceRevision;
+  unverified: boolean;
+}
+
+export interface InspectionEvidence {
+  target: InspectionTarget;
+  structure: StructureDetails;
+  source?: SourceRangeRead;
+  revision?: SourceRevision;
+}
+
+export function resolveInspectionTarget(
+  input: InspectInput,
+  cwd: string,
+  snapshots: SnapshotStore,
+): InspectionTarget {
+  let path = input.path?.replace(/^@/, "");
+  let line = input.line;
+  let retainedMatch: MatchRecord | undefined;
+  if (input.matchIndex !== undefined) {
+    if (!input.cursor) throw new SiftLightError("matchIndex requires a cursor when mode=inspect");
+    if (input.path !== undefined || input.line !== undefined) {
+      throw new SiftLightError("matchIndex replaces path and line when mode=inspect");
+    }
+    if (!Number.isSafeInteger(input.matchIndex) || input.matchIndex < 1) {
+      throw new SiftLightError("matchIndex must be a positive integer when mode=inspect");
+    }
+    const { snapshot } = snapshots.resolve(input.cursor);
+    retainedMatch = snapshot.matches[input.matchIndex - 1];
+    if (!retainedMatch) {
+      throw new CursorError(
+        `matchIndex is ${snapshot.snapshotComplete ? "outside this snapshot" : "not retained in this partial snapshot"}.`,
+      );
+    }
+    path = retainedMatch.displayPath;
+    line = retainedMatch.lineNumber;
+  }
+  if (!path) throw new SiftLightError("path is required when mode=inspect");
+  if (line === undefined || !Number.isSafeInteger(line) || line < 1) {
+    throw new SiftLightError("line must be a positive integer when mode=inspect");
+  }
+  const absolutePath = retainedMatch?.absolutePath ?? resolve(cwd, path);
+  new SearchPathPolicy(cwd).assertPath(absolutePath);
+  let expectedRevision: SourceRevision | undefined;
+  if (input.cursor) {
+    const { snapshot } = snapshots.resolve(input.cursor);
+    retainedMatch ??= snapshot.matches.find(
+      (match) => match.absolutePath === absolutePath && match.lineNumber === line,
+    );
+    if (!retainedMatch) {
+      throw new CursorError("The requested line is not a retained match in this snapshot.");
+    }
+    expectedRevision = snapshot.sourceRevisions.get(absolutePath);
+  }
+  return {
+    path,
+    absolutePath,
+    line,
+    unverified: input.cursor !== undefined && expectedRevision === undefined,
+    ...(retainedMatch ? { retainedMatch } : {}),
+    ...(expectedRevision ? { expectedRevision } : {}),
+  };
+}
+
+export function sourceExcerptDetails(source: SourceRangeRead): SourceExcerptDetails {
+  return {
+    range: { startLine: source.startLine, endLine: source.endLine },
+    omittedBefore: source.omittedBefore,
+    omittedAfter: source.omittedAfter,
+    truncatedLines: source.truncatedLines,
+  };
+}
+
+export function sourceTruncationText(source: SourceRangeRead): string {
+  const range = source.truncated
+    ? `\n[source range centered on target; omitted ${String(source.omittedBefore)} lines before and ${String(source.omittedAfter)} lines after]`
+    : "";
+  const lines =
+    source.truncatedLines.length > 0
+      ? `\n[source line excerpts truncated: ${source.truncatedLines.join(", ")}; maximum ${String(MAX_LINE_CHARACTERS)} source characters per line]`
+      : "";
+  return range + lines;
+}
+
+export function inspectionDescription(evidence: InspectionEvidence): string {
+  const symbol = evidence.structure.symbol;
+  return symbol
+    ? `${symbol.scope.length > 0 ? `${symbol.scope.join(".")}.` : ""}${symbol.name} (${symbol.kind}) lines ${symbol.range.startLine}-${symbol.range.endLine}`
+    : `No enclosing symbol found for line ${String(evidence.target.line)}`;
+}
+
+function unavailableEvidence(
+  target: InspectionTarget,
+  status: StructureDetails["status"],
+  provider?: string,
+): InspectionEvidence {
+  return { target, structure: { status, ...(provider ? { provider } : {}) } };
+}
+
+function isUnavailableSourceError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    ["ENOENT", "EACCES", "EPERM", "ENOTDIR", "EISDIR"].includes(String(error.code))
+  );
+}
+
+export async function inspectSourceEvidence(
+  target: InspectionTarget,
+  cwd: string,
+  signal: AbortSignal | undefined,
+  options: InspectOptions,
+  maxSourceBytes?: number,
+): Promise<InspectionEvidence> {
+  if (signal?.aborted) throw abortError();
+  try {
+    await assertExistingSearchPath(target.absolutePath, cwd);
+  } catch (error) {
+    if (signal?.aborted) throw abortError();
+    if (isUnavailableSourceError(error)) return unavailableEvidence(target, "source-unavailable");
+    throw error;
+  }
+  if (signal?.aborted) throw abortError();
+  if (target.unverified) return unavailableEvidence(target, "source-unavailable");
+  let inspection: StructureInspection;
+  if (options.structure) {
+    inspection = await options.structure.inspect(
+      {
+        absolutePath: target.absolutePath,
+        cwd,
+        line: target.line,
+        ...(target.expectedRevision ? { expectedRevision: target.expectedRevision } : {}),
+      },
+      signal,
+    );
+  } else {
+    const currentRevision = await getSourceRevision(target.absolutePath);
+    inspection = {
+      details: { status: "provider-unavailable" },
+      ...(currentRevision ? { currentRevision } : {}),
+    };
+  }
+  const { details: structure } = inspection;
+  if (signal?.aborted) throw abortError();
+  if (["source-changed", "source-unavailable", "file-too-large"].includes(structure.status)) {
+    return { target, structure };
+  }
+  const revision = inspection.currentRevision ?? (await getSourceRevision(target.absolutePath));
+  if (!revision) return unavailableEvidence(target, "source-unavailable", structure.provider);
+  if (target.expectedRevision && !sameSourceRevision(target.expectedRevision, revision)) {
+    return unavailableEvidence(target, "source-changed", structure.provider);
+  }
+  const evidence: InspectionEvidence = { target, structure, revision };
+  const headerBytes = Buffer.byteLength(
+    `${target.path}:${String(target.line)}\n${inspectionDescription(evidence)}\n\n[structure: ${structure.status}${structure.provider ? ` via ${structure.provider}` : ""}${structure.reason ? `; ${structure.reason}` : ""}]`,
+  );
+  const maxBytes = Math.min(
+    maxSourceBytes ?? MAX_RESULT_BYTES,
+    MAX_RESULT_BYTES - headerBytes - 1024,
+  );
+  if (maxBytes <= 0) throw new SourceBudgetTooSmallError();
+  const range = structure.range ?? {
+    startLine: Math.max(1, target.line - 10),
+    endLine: target.line + 10,
+  };
+  try {
+    evidence.source = await readSourceRange(
+      target.absolutePath,
+      range.startLine,
+      range.endLine,
+      signal,
+      target.line,
+      {
+        maxBytes,
+        ...(target.retainedMatch?.occurrences[0]
+          ? { focus: target.retainedMatch.occurrences[0] }
+          : {}),
+      },
+    );
+  } catch (error) {
+    if (signal?.aborted || (error instanceof Error && error.name === "AbortError"))
+      throw abortError();
+    if (error instanceof SourceTooLargeError)
+      return unavailableEvidence(target, "file-too-large", structure.provider);
+    if (isUnavailableSourceError(error)) {
+      return unavailableEvidence(target, "source-unavailable", structure.provider);
+    }
+    throw error;
+  }
+  const finalRevision = await getSourceRevision(target.absolutePath);
+  if (signal?.aborted) throw abortError();
+  if (!finalRevision || !sameSourceRevision(revision, finalRevision)) {
+    return unavailableEvidence(target, "source-changed", structure.provider);
+  }
+  return evidence;
+}
+
+export async function inspectSource(
+  input: InspectInput,
+  cwd: string,
+  signal: AbortSignal | undefined,
+  options: InspectOptions,
+): Promise<SiftLightResult> {
+  const target = resolveInspectionTarget(input, cwd, options.snapshots);
+  const evidence = await inspectSourceEvidence(target, cwd, signal, options);
+  const { source, structure } = evidence;
+  const details: SiftLightDetails = {
+    version: 1,
+    mode: "inspect",
+    status: source ? "complete" : "partial",
+    totalMatches: 0,
+    storedMatches: 0,
+    totalFiles: 1,
+    returnedMatches: source?.lines.length ?? 0,
+    snapshotComplete: source !== undefined,
+    structure,
+    ...(source ? { source: sourceExcerptDetails(source) } : {}),
+    ...(source && source.truncatedLines.length > 0
+      ? { lineContentTruncated: source.truncatedLines.length }
+      : {}),
+  };
+  const status = `[structure: ${structure.status}${structure.provider ? ` via ${structure.provider}` : ""}${structure.reason ? `; ${structure.reason}` : ""}${!source && target.retainedMatch ? "; refresh the search before inspecting this match" : ""}]`;
+  const text = source
+    ? `${target.path}:${String(target.line)}\n${inspectionDescription(evidence)}\n\n${source.text}${sourceTruncationText(source)}\n\n${status}`
+    : `${target.path}:${String(target.line)}\n\n${status}`;
+  if (Buffer.byteLength(text) > MAX_RESULT_BYTES)
+    throw new SiftLightError("Inspection metadata exceeds the result byte budget");
+  return { text, details };
+}

package/src/language-capabilities.ts

@@ -0,0 +1,157 @@
+import { resolve } from "node:path";
+import { listWorkspaceFiles } from "./workspace-files.js";
+import {
+  DEFAULT_LANGUAGE_CAPABILITIES,
+  DEFAULT_NEUTRAL_CAPABILITIES,
+  descriptorForPath,
+  type CapabilityAvailability,
+  type LanguageCapability,
+  type LanguageCapabilityDescriptor,
+  type LanguageCapabilitySpec,
+  type LanguageId,
+  type NeutralCapabilitySpec,
+} from "./language-capability-definitions.js";
+
+export type {
+  CapabilityAvailability,
+  LanguageCapability,
+  LanguageCapabilityDescriptor,
+  LanguageCapabilitySpec,
+  LanguageId,
+  NeutralCapabilitySpec,
+} from "./language-capability-definitions.js";
+export {
+  DEFAULT_LANGUAGE_CAPABILITIES,
+  DEFAULT_NEUTRAL_CAPABILITIES,
+} from "./language-capability-definitions.js";
+
+export interface LanguageCapabilityEntry {
+  readonly language: LanguageId;
+  readonly files: number;
+  readonly extensions: readonly string[];
+  /** Stable ids are resolved through inventory.capabilityDefinitions. */
+  readonly capabilities: readonly { id: string; name: LanguageCapability }[];
+  readonly availability: CapabilityAvailability;
+  /** Capability discovery never probes external tools or project indexes. */
+  readonly readiness: "not-probed";
+  readonly evidence: "inventory" | "target-extension";
+}
+
+export interface LanguageCapabilityRequest {
+  readonly cwd: string;
+  readonly path?: string;
+  readonly glob?: readonly string[];
+  readonly exclude?: readonly string[];
+  readonly hidden?: boolean;
+  readonly signal?: AbortSignal;
+}
+
+export interface LanguageCapabilityInventory {
+  /** Root of the bounded names-only inventory, not a parsed project root. */
+  readonly root: string;
+  readonly path?: string;
+  readonly partial: boolean;
+  readonly reasons: readonly string[];
+  readonly languages: readonly LanguageCapabilityEntry[];
+  /** Deduplicated implementation facts, referenced by capability id above. */
+  readonly capabilityDefinitions: readonly LanguageCapabilitySpec[];
+  readonly neutral: readonly NeutralCapabilitySpec[];
+}
+
+function normalizeLists(values: readonly string[] | undefined): string[] {
+  return values === undefined ? [] : [...values];
+}
+
+function languageAvailability(
+  capabilities: readonly LanguageCapabilitySpec[],
+): CapabilityAvailability {
+  if (capabilities.length === 0) return "unavailable";
+  if (capabilities.some((capability) => capability.availability === "conditional"))
+    return "conditional";
+  return "implemented";
+}
+
+/**
+ * Lightweight project capability discovery. It enumerates names only and
+ * never opens a parser, compiler, model worker or language server.
+ */
+export class LanguageCapabilityCatalog {
+  readonly #descriptors: readonly LanguageCapabilityDescriptor[];
+  readonly #neutral: readonly NeutralCapabilitySpec[];
+
+  constructor(
+    descriptors: readonly LanguageCapabilityDescriptor[] = DEFAULT_LANGUAGE_CAPABILITIES,
+    neutral: readonly NeutralCapabilitySpec[] = DEFAULT_NEUTRAL_CAPABILITIES,
+  ) {
+    this.#descriptors = [...descriptors];
+    this.#neutral = [...neutral];
+  }
+
+  descriptor(language: LanguageId): LanguageCapabilityDescriptor | undefined {
+    return this.#descriptors.find((item) => item.language === language);
+  }
+
+  descriptorForPath(path: string): LanguageCapabilityDescriptor | undefined {
+    return descriptorForPath(this.#descriptors, path);
+  }
+
+  async inspect(request: LanguageCapabilityRequest): Promise<LanguageCapabilityInventory> {
+    const path = request.path?.replace(/^@/, "");
+    const files = await listWorkspaceFiles(request.cwd, request.signal, {
+      ...(path ? { path } : {}),
+      glob: normalizeLists(request.glob),
+      exclude: normalizeLists(request.exclude),
+      hidden: request.hidden ?? true,
+    });
+    const counts = new Map<LanguageId, number>();
+    for (const file of files.paths) {
+      const descriptor = this.descriptorForPath(file);
+      if (descriptor) counts.set(descriptor.language, (counts.get(descriptor.language) ?? 0) + 1);
+    }
+    const entries = [...counts.entries()].flatMap(([language, count]) => {
+      const descriptor = this.descriptor(language);
+      if (!descriptor) return [];
+      return [this.#entry(descriptor, count, "inventory")];
+    });
+    const target = path ? this.descriptorForPath(path) : undefined;
+    if (target && !counts.has(target.language))
+      entries.push(this.#entry(target, 0, "target-extension"));
+    entries.sort((left, right) => left.language.localeCompare(right.language));
+    const capabilityDefinitions = [
+      ...new Map(
+        entries
+          .flatMap((entry) => this.descriptor(entry.language)?.capabilities ?? [])
+          .map((capability) => [capability.id, capability] as const),
+      ).values(),
+    ];
+    return {
+      root: resolve(request.cwd),
+      ...(path ? { path } : {}),
+      partial: files.partial,
+      reasons: files.reasons,
+      languages: entries,
+      capabilityDefinitions,
+      neutral: this.#neutral,
+    };
+  }
+
+  #entry(
+    descriptor: LanguageCapabilityDescriptor,
+    files: number,
+    evidence: LanguageCapabilityEntry["evidence"],
+  ): LanguageCapabilityEntry {
+    return {
+      language: descriptor.language,
+      files,
+      extensions: descriptor.extensions,
+      capabilities: descriptor.capabilities.map(({ id, name }) => ({ id, name })),
+      availability: languageAvailability(descriptor.capabilities),
+      readiness: "not-probed",
+      evidence,
+    };
+  }
+}
+
+export function languageCapabilityForPath(path: string): LanguageCapabilityDescriptor | undefined {
+  return descriptorForPath(DEFAULT_LANGUAGE_CAPABILITIES, path);
+}

package/src/language-capability-definitions.ts

@@ -0,0 +1,204 @@
+import { extname } from "node:path";
+
+export type LanguageId = "javascript" | "typescript" | "tsx" | "go" | "python" | "swift";
+
+export type LanguageCapability = "outline" | "structure" | "roles" | "imports" | "tests";
+
+export type CapabilityEvidence = "text" | "syntax" | "compiler" | "external" | "model";
+export type CapabilityAvailability = "implemented" | "conditional" | "unavailable";
+export type CapabilityProviderKind = "builtin" | "external" | "model";
+
+/** One capability declaration is the source of provider, evidence and loading facts. */
+export interface LanguageCapabilitySpec {
+  readonly id: string;
+  readonly name: LanguageCapability;
+  readonly provider: string;
+  readonly providerKind: CapabilityProviderKind;
+  readonly evidence: CapabilityEvidence;
+  readonly availability: CapabilityAvailability;
+  /** Runtime parser/compiler/model resource activation, not JavaScript module import timing. */
+  readonly load: "lazy";
+  readonly prerequisites?: readonly string[];
+}
+
+export interface LanguageCapabilityDescriptor {
+  readonly language: LanguageId;
+  readonly extensions: readonly string[];
+  readonly capabilities: readonly LanguageCapabilitySpec[];
+}
+
+export type NeutralCapabilityName = "content" | "files" | "concept" | "hybrid";
+
+export interface NeutralCapabilitySpec {
+  readonly id: string;
+  readonly name: NeutralCapabilityName;
+  readonly provider: string;
+  readonly providerKind: CapabilityProviderKind;
+  readonly evidence: CapabilityEvidence;
+  readonly availability: CapabilityAvailability;
+  readonly load: "none" | "lazy";
+  readonly prerequisites?: readonly string[];
+}
+
+const TYPESCRIPT_LANGUAGE_CAPABILITIES: readonly LanguageCapabilitySpec[] = [
+  {
+    id: "ast-grep.outline",
+    name: "outline",
+    provider: "ast-grep",
+    providerKind: "builtin",
+    evidence: "syntax",
+    availability: "implemented",
+    load: "lazy",
+  },
+  {
+    id: "ast-grep.structure",
+    name: "structure",
+    provider: "ast-grep",
+    providerKind: "builtin",
+    evidence: "syntax",
+    availability: "implemented",
+    load: "lazy",
+  },
+  {
+    id: "ast-grep.roles",
+    name: "roles",
+    provider: "ast-grep",
+    providerKind: "builtin",
+    evidence: "syntax",
+    availability: "implemented",
+    load: "lazy",
+  },
+  {
+    id: "static-navigation.imports",
+    name: "imports",
+    provider: "bounded static module resolver",
+    providerKind: "builtin",
+    evidence: "syntax",
+    availability: "implemented",
+    load: "lazy",
+  },
+  {
+    id: "static-navigation.tests",
+    name: "tests",
+    provider: "bounded static module resolver",
+    providerKind: "builtin",
+    evidence: "syntax",
+    availability: "implemented",
+    load: "lazy",
+  },
+];
+
+const GO_LANGUAGE_CAPABILITIES: readonly LanguageCapabilitySpec[] = [
+  {
+    id: "ast-grep-go.structure",
+    name: "structure",
+    provider: "ast-grep lang-go",
+    providerKind: "builtin",
+    evidence: "syntax",
+    availability: "implemented",
+    load: "lazy",
+  },
+  {
+    id: "ast-grep-go.roles",
+    name: "roles",
+    provider: "ast-grep lang-go",
+    providerKind: "builtin",
+    evidence: "syntax",
+    availability: "implemented",
+    load: "lazy",
+  },
+];
+
+const PYTHON_LANGUAGE_CAPABILITIES: readonly LanguageCapabilitySpec[] = [
+  {
+    id: "python-outline.outline",
+    name: "outline",
+    provider: "bounded Python outline parser",
+    providerKind: "builtin",
+    evidence: "syntax",
+    availability: "implemented",
+    load: "lazy",
+  },
+];
+
+export const DEFAULT_LANGUAGE_CAPABILITIES: readonly LanguageCapabilityDescriptor[] = [
+  {
+    language: "javascript",
+    extensions: [".js", ".jsx", ".mjs", ".cjs"],
+    capabilities: TYPESCRIPT_LANGUAGE_CAPABILITIES,
+  },
+  {
+    language: "typescript",
+    extensions: [".ts", ".mts", ".cts"],
+    capabilities: TYPESCRIPT_LANGUAGE_CAPABILITIES,
+  },
+  {
+    language: "tsx",
+    extensions: [".tsx"],
+    capabilities: TYPESCRIPT_LANGUAGE_CAPABILITIES,
+  },
+  { language: "go", extensions: [".go"], capabilities: GO_LANGUAGE_CAPABILITIES },
+  { language: "python", extensions: [".py"], capabilities: PYTHON_LANGUAGE_CAPABILITIES },
+  { language: "swift", extensions: [".swift"], capabilities: [] },
+];
+
+export const DEFAULT_NEUTRAL_CAPABILITIES: readonly NeutralCapabilitySpec[] = [
+  {
+    id: "neutral.content",
+    name: "content",
+    provider: "ripgrep",
+    providerKind: "builtin",
+    evidence: "text",
+    availability: "implemented",
+    load: "none",
+  },
+  {
+    id: "neutral.files",
+    name: "files",
+    provider: "ripgrep --files",
+    providerKind: "builtin",
+    evidence: "text",
+    availability: "implemented",
+    load: "none",
+  },
+  {
+    id: "neutral.concept",
+    name: "concept",
+    provider: "local multilingual-e5 model",
+    providerKind: "model",
+    evidence: "model",
+    availability: "conditional",
+    load: "lazy",
+    prerequisites: ["verified local model assets"],
+  },
+  {
+    id: "neutral.hybrid",
+    name: "hybrid",
+    provider: "ripgrep + local multilingual-e5 model",
+    providerKind: "model",
+    evidence: "model",
+    availability: "conditional",
+    load: "lazy",
+    prerequisites: ["verified local model assets"],
+  },
+];
+
+export function descriptorForPath(
+  descriptors: readonly LanguageCapabilityDescriptor[],
+  path: string,
+): LanguageCapabilityDescriptor | undefined {
+  const extension = extname(path).toLowerCase();
+  return descriptors.find((item) => item.extensions.includes(extension));
+}
+
+export function languageForPath(
+  descriptors: readonly LanguageCapabilityDescriptor[],
+  path: string,
+): LanguageId | undefined {
+  return descriptorForPath(descriptors, path)?.language;
+}
+
+export function outlineExtension(path: string): string | undefined {
+  const extension = extname(path).toLowerCase();
+  return extension || undefined;
+}

package/src/literal-search.ts

@@ -0,0 +1,25 @@
+import type { ByteRange, SourceDocument } from "./source-document.js";
+
+export function escapeRegexLiteral(term: string): string {
+  return term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Finds non-overlapping occurrences of one exact byte sequence. Different terms are scanned independently. */
+export function literalOccurrences(
+  document: SourceDocument,
+  term: string,
+  allowed?: readonly ByteRange[],
+): ByteRange[] {
+  const needle = Buffer.from(term);
+  const found: ByteRange[] = [];
+  for (
+    let start = document.bytes.indexOf(needle);
+    start >= 0;
+    start = document.bytes.indexOf(needle, start + Math.max(1, needle.length))
+  ) {
+    const range = { start, end: start + needle.length };
+    if (!allowed || allowed.some((part) => part.start <= range.start && range.end <= part.end))
+      found.push(range);
+  }
+  return found;
+}

package/src/mcp-cli.ts

@@ -0,0 +1,21 @@
+export type SiftLightMcpTransport = "http" | "stdio";
+
+export const SIFT_LIGHT_MCP_USAGE = `Usage: sift-light-mcp [--http | --stdio]
+
+Transports:
+  --http   Start the Streamable HTTP server (default)
+  --stdio  Serve one local MCP client over stdin/stdout
+`;
+
+export function parseSiftLightMcpTransport(
+  arguments_: readonly string[],
+): SiftLightMcpTransport | "help" {
+  if (arguments_.length === 0 || (arguments_.length === 1 && arguments_[0] === "--http")) {
+    return "http";
+  }
+  if (arguments_.length === 1 && arguments_[0] === "--stdio") return "stdio";
+  if (arguments_.length === 1 && (arguments_[0] === "--help" || arguments_[0] === "-h")) {
+    return "help";
+  }
+  throw new Error(`Unknown arguments: ${arguments_.join(" ")}\n${SIFT_LIGHT_MCP_USAGE}`);
+}