@untangle-code/cli 0.0.0-stage → 0.1.1

package/src/mcp/path-sandbox.ts

@@ -0,0 +1,156 @@
+import { lstatSync, readlinkSync, realpathSync, type Stats } from "node:fs";
+import path from "node:path";
+
+export class PathOutsideWorkspaceError extends Error {
+  readonly requestedPath: string;
+  readonly workspaceRoots: readonly string[];
+
+  constructor(requestedPath: string, workspaceRoots: readonly string[]) {
+    super(`Path "${requestedPath}" resolves outside every allowed workspace root.`);
+    this.name = "PathOutsideWorkspaceError";
+    this.requestedPath = requestedPath;
+    this.workspaceRoots = workspaceRoots;
+  }
+}
+
+/** A path could not be canonicalized safely (cycle, invalid bytes, I/O). */
+export class InvalidWorkspacePathError extends Error {
+  readonly requestedPath: string;
+
+  constructor(requestedPath: string, cause: unknown) {
+    super(
+      `Path "${requestedPath}" cannot be canonicalized safely: ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause },
+    );
+    this.name = "InvalidWorkspacePathError";
+    this.requestedPath = requestedPath;
+  }
+}
+
+/**
+ * Canonicalizes an existing path, or the nearest existing ancestor plus the
+ * unresolved suffix. The latter closes the common `out/new-file` case while
+ * still resolving every symlink that already exists on the route.
+ */
+export function canonicalPotentialPath(input: string): string {
+  try {
+    return canonicalPotentialPathFrom(input, new Set<string>());
+  } catch (error) {
+    if (error instanceof InvalidWorkspacePathError) throw error;
+    throw new InvalidWorkspacePathError(input, error);
+  }
+}
+
+function canonicalPotentialPathFrom(input: string, visitedLinks: Set<string>): string {
+  let cursor = path.resolve(input);
+  const suffix: string[] = [];
+  for (;;) {
+    const stat = lstatOrNull(cursor);
+    if (stat !== null) {
+      if (stat.isSymbolicLink()) {
+        if (visitedLinks.has(cursor)) {
+          throw new InvalidWorkspacePathError(
+            input,
+            new Error(`Symbolic-link cycle encountered at "${cursor}".`),
+          );
+        }
+        visitedLinks.add(cursor);
+        const target = path.resolve(path.dirname(cursor), readlinkSync(cursor));
+        return canonicalPotentialPathFrom(path.resolve(target, ...suffix), visitedLinks);
+      }
+      return path.resolve(realpathSync(cursor), ...suffix);
+    }
+    const parent = path.dirname(cursor);
+    if (parent === cursor) break;
+    suffix.unshift(path.basename(cursor));
+    cursor = parent;
+  }
+  return path.resolve(cursor, ...suffix);
+}
+
+function lstatOrNull(candidate: string): Stats | null {
+  try {
+    return lstatSync(candidate);
+  } catch (error) {
+    if (
+      typeof error === "object" &&
+      error !== null &&
+      "code" in error &&
+      (error.code === "ENOENT" || error.code === "ENOTDIR")
+    ) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+function isWithin(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return (
+    relative === "" ||
+    (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative))
+  );
+}
+
+export function assertPathInsideWorkspace(
+  requestedPath: string,
+  options: { cwd: string; workspaceRoots: readonly string[] },
+): string {
+  let candidate: string;
+  try {
+    candidate = canonicalPotentialPath(path.resolve(options.cwd, requestedPath));
+  } catch (error) {
+    if (error instanceof InvalidWorkspacePathError) {
+      throw new InvalidWorkspacePathError(requestedPath, error.cause ?? error);
+    }
+    throw error;
+  }
+  const roots = options.workspaceRoots.map(canonicalPotentialPath);
+  if (!roots.some((root) => isWithin(root, candidate))) {
+    throw new PathOutsideWorkspaceError(requestedPath, roots);
+  }
+  return candidate;
+}
+
+export function assertToolPathsInsideWorkspace(
+  input: Readonly<Record<string, unknown>>,
+  pathFields: readonly string[],
+  options: { cwd: string; workspaceRoots: readonly string[] },
+): void {
+  canonicalizeToolPathsInsideWorkspace(input, pathFields, options);
+}
+
+/**
+ * Prueft alle deklarierten Pfade und ersetzt sie fuer den nachfolgenden
+ * Runtime-Aufruf durch ihre kanonischen absoluten Ziele. So kann ein bereits
+ * aufgeloester Symlink nach der Pruefung nicht allein dadurch wieder wirksam
+ * werden, dass die Runtime denselben rohen Linkpfad erneut interpretiert.
+ */
+export function canonicalizeToolPathsInsideWorkspace(
+  input: Readonly<Record<string, unknown>>,
+  pathFields: readonly string[],
+  options: { cwd: string; workspaceRoots: readonly string[] },
+): Record<string, unknown> {
+  const canonicalInput: Record<string, unknown> = { ...input };
+  const rootValue = input["root"];
+  const toolCwd =
+    typeof rootValue === "string" ? assertPathInsideWorkspace(rootValue, options) : options.cwd;
+  if (typeof rootValue === "string") canonicalInput["root"] = toolCwd;
+
+  for (const field of pathFields) {
+    if (field === "root") continue;
+    const value = input[field];
+    if (typeof value === "string") {
+      canonicalInput[field] = assertPathInsideWorkspace(value, { ...options, cwd: toolCwd });
+      continue;
+    }
+    if (Array.isArray(value)) {
+      canonicalInput[field] = value.map((entry) =>
+        typeof entry === "string"
+          ? assertPathInsideWorkspace(entry, { ...options, cwd: toolCwd })
+          : entry,
+      );
+    }
+  }
+  return canonicalInput;
+}

package/src/mcp/server.ts

@@ -0,0 +1,358 @@
+import { McpServer, type CallToolResult } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+
+import { CLI_VERSION } from "../cli/version.js";
+
+import { DefaultUntangleMcpRuntime } from "./default-runtime.js";
+import { mcpFailure } from "./envelope.js";
+import {
+  canonicalPotentialPath,
+  canonicalizeToolPathsInsideWorkspace,
+  InvalidWorkspacePathError,
+  PathOutsideWorkspaceError,
+} from "./path-sandbox.js";
+import { UNTANGLE_MCP_TOOLS, type McpToolDefinition } from "./tools.js";
+import {
+  UNTANGLE_MCP_TOOL_NAMES,
+  type UntangleMcpRuntime,
+  type UntangleMcpToolName,
+} from "./types.js";
+
+const warningSchema = z
+  .object({
+    code: z.string(),
+    message: z.string(),
+    details: z.record(z.string(), z.json()).optional(),
+  })
+  .strict();
+
+const toolErrorSchema = z
+  .object({
+    code: z.string(),
+    message: z.string(),
+    retryable: z.boolean(),
+    details: z.record(z.string(), z.json()).optional(),
+  })
+  .strict();
+
+const indexStateSchema = z
+  .object({
+    generationId: z.string(),
+    status: z.string(),
+    stale: z.boolean(),
+  })
+  .strict();
+
+const toolNameSchema = z.enum(UNTANGLE_MCP_TOOL_NAMES);
+const successDataSchemas = new Map(
+  UNTANGLE_MCP_TOOLS.map((definition) => [definition.name, definition.successDataSchema] as const),
+);
+
+const knownSuccessEnvelopeSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    ok: z.literal(true),
+    operation: toolNameSchema,
+    workspaceId: z.string().optional(),
+    data: z.unknown(),
+    warnings: z.array(warningSchema),
+    indexState: indexStateSchema.optional(),
+  })
+  .strict()
+  .superRefine((envelope, context) => {
+    const schema = successDataSchemas.get(envelope.operation);
+    const parsed = schema?.safeParse(envelope.data);
+    if (parsed?.success === true) return;
+    context.addIssue({
+      code: "custom",
+      path: ["data"],
+      message: `Data does not match the success contract for ${envelope.operation}.`,
+    });
+  });
+
+/** The wire contract from spec.md section 21.2. */
+export const toolResponseEnvelopeSchema = z.discriminatedUnion("ok", [
+  knownSuccessEnvelopeSchema,
+  z
+    .object({
+      schemaVersion: z.literal(1),
+      ok: z.literal(false),
+      operation: toolNameSchema,
+      workspaceId: z.string().optional(),
+      warnings: z.array(warningSchema),
+      error: toolErrorSchema,
+      indexState: indexStateSchema.optional(),
+    })
+    .strict(),
+]);
+
+export interface CreateUntangleMcpServerOptions {
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly runtime?: UntangleMcpRuntime;
+  /** Canonical containment roots. An omitted/empty list is restricted to cwd. */
+  readonly workspaceRoots?: readonly string[];
+}
+
+/**
+ * Creates one transport-neutral server instance. The public CLI package owns
+ * this runtime so programmatic and binary consumers cannot drift apart.
+ */
+export function createUntangleMcpServer(options: CreateUntangleMcpServerOptions = {}): McpServer {
+  const cwd = options.cwd ?? process.cwd();
+  const env = options.env ?? process.env;
+  const runtime = options.runtime ?? new DefaultUntangleMcpRuntime();
+  const configuredRoots = options.workspaceRoots ?? [];
+  const workspaceRoots = uniqueCanonicalRoots(
+    configuredRoots.length === 0 ? [cwd] : configuredRoots,
+  );
+  const server = new McpServer(
+    { name: "untangle", version: CLI_VERSION },
+    { capabilities: { tools: {} } },
+  );
+
+  for (const definition of UNTANGLE_MCP_TOOLS) {
+    const outputSchema = outputEnvelopeSchema(definition);
+    server.registerTool(
+      definition.name,
+      {
+        description: definition.description,
+        // The SDK normally turns validation failures into a text-only tool
+        // error before our handler runs. Advertise the exact schema, but let
+        // this boundary validate manually so EVERY tool result still carries
+        // the normative §21.2 envelope.
+        inputSchema: advertiseSchemaWithoutPrevalidation(definition.inputSchema),
+        outputSchema,
+      },
+      async (input, requestContext): Promise<CallToolResult> => {
+        return executeMcpToolInvocation(definition, input, {
+          cwd,
+          env,
+          runtime,
+          workspaceRoots,
+          signal: requestContext.mcpReq.signal,
+        });
+      },
+    );
+  }
+
+  return server;
+}
+
+interface ExecuteMcpToolInvocationOptions {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly runtime: UntangleMcpRuntime;
+  readonly workspaceRoots: readonly string[];
+  readonly signal: AbortSignal;
+}
+
+/**
+ * One testable invocation boundary. Keeping cancellation here means an
+ * already-aborted request never reaches a storage adapter or mutating use case.
+ */
+export async function executeMcpToolInvocation(
+  definition: McpToolDefinition,
+  input: unknown,
+  options: ExecuteMcpToolInvocationOptions,
+): Promise<CallToolResult> {
+  let envelope;
+  try {
+    if (options.signal.aborted) {
+      envelope = mcpFailure(
+        definition.name,
+        "CANCELLED",
+        "The MCP operation was cancelled.",
+        false,
+      );
+      return toCallToolResult(definition, envelope);
+    }
+    const parsed = definition.inputSchema.safeParse(input);
+    if (!parsed.success) {
+      envelope = mcpFailure(
+        definition.name,
+        "INVALID_ARGUMENT",
+        `Invalid arguments for MCP tool "${definition.name}".`,
+        false,
+        { details: { issues: publicZodIssues(parsed.error) } },
+      );
+      return toCallToolResult(definition, envelope);
+    }
+    const canonicalInput = canonicalizeToolPathsInsideWorkspace(
+      parsed.data,
+      definition.pathFields,
+      {
+        cwd: options.cwd,
+        workspaceRoots: options.workspaceRoots,
+      },
+    );
+    if (options.signal.aborted) {
+      envelope = mcpFailure(
+        definition.name,
+        "CANCELLED",
+        "The MCP operation was cancelled.",
+        false,
+      );
+      return toCallToolResult(definition, envelope);
+    }
+    envelope = await options.runtime.invoke(definition.name, canonicalInput, {
+      cwd: options.cwd,
+      env: options.env,
+      signal: options.signal,
+    });
+    if (options.signal.aborted) {
+      envelope = mcpFailure(
+        definition.name,
+        "CANCELLED",
+        "The MCP operation was cancelled.",
+        false,
+      );
+    }
+  } catch (error) {
+    envelope = options.signal.aborted
+      ? mcpFailure(definition.name, "CANCELLED", "The MCP operation was cancelled.", false)
+      : serverFailure(definition.name, error);
+  }
+  return toCallToolResult(definition, envelope);
+}
+
+/**
+ * Keeps the advertised JSON Schema byte-for-byte equivalent to the Zod
+ * schema while deferring validation to our envelope-producing handler.
+ */
+function advertiseSchemaWithoutPrevalidation(
+  schema: z.ZodType<Record<string, unknown>>,
+): z.ZodType<Record<string, unknown>> {
+  const standard = schema["~standard"];
+  return {
+    "~standard": {
+      ...standard,
+      validate: (value: unknown) => ({ value }),
+    },
+  } as unknown as z.ZodType<Record<string, unknown>>;
+}
+
+function outputEnvelopeSchema(definition: McpToolDefinition) {
+  return z.discriminatedUnion("ok", [
+    z
+      .object({
+        schemaVersion: z.literal(1),
+        ok: z.literal(true),
+        operation: z.literal(definition.name),
+        workspaceId: z.string().optional(),
+        data: definition.successDataSchema,
+        warnings: z.array(warningSchema),
+        indexState: indexStateSchema.optional(),
+      })
+      .strict(),
+    z
+      .object({
+        schemaVersion: z.literal(1),
+        ok: z.literal(false),
+        operation: z.literal(definition.name),
+        workspaceId: z.string().optional(),
+        warnings: z.array(warningSchema),
+        error: toolErrorSchema,
+        indexState: indexStateSchema.optional(),
+      })
+      .strict(),
+  ]);
+}
+
+function publicZodIssues(error: z.ZodError): Array<{
+  code: string;
+  path: string;
+  message: string;
+}> {
+  return error.issues.slice(0, 32).map((issue) => ({
+    code: issue.code,
+    path: issue.path.map(String).join("."),
+    message: issue.message,
+  }));
+}
+
+function toCallToolResult(definition: McpToolDefinition, value: unknown): CallToolResult {
+  const operation = definition.name;
+  let envelope;
+  try {
+    const parsed = toolResponseEnvelopeSchema.safeParse(value);
+    if (!parsed.success || parsed.data.operation !== operation) {
+      envelope = invalidRuntimeEnvelope(
+        operation,
+        parsed.success ? "operation mismatch" : "schema mismatch",
+      );
+    } else if (parsed.data.ok) {
+      const data = definition.successDataSchema.safeParse(parsed.data.data);
+      envelope = data.success
+        ? { ...parsed.data, data: data.data }
+        : invalidRuntimeEnvelope(operation, "success data schema mismatch");
+    } else {
+      envelope = parsed.data;
+    }
+    const structuredContent = jsonObject(envelope);
+    return {
+      content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+      structuredContent,
+      isError: !envelope.ok,
+    };
+  } catch {
+    envelope = invalidRuntimeEnvelope(operation, "response was not JSON serializable");
+    const structuredContent = jsonObject(envelope);
+    return {
+      content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+      structuredContent,
+      isError: true,
+    };
+  }
+}
+
+function invalidRuntimeEnvelope(
+  operation: UntangleMcpToolName,
+  reason: string,
+): ReturnType<typeof mcpFailure> {
+  return mcpFailure(
+    operation,
+    "INVALID_INTERNAL_OUTPUT",
+    `The MCP runtime returned an invalid response envelope (${reason}).`,
+    false,
+  );
+}
+
+function serverFailure(operation: UntangleMcpToolName, error: unknown) {
+  if (error instanceof PathOutsideWorkspaceError) {
+    return mcpFailure(operation, "PATH_OUTSIDE_WORKSPACE", error.message, false, {
+      details: { requestedPath: error.requestedPath },
+    });
+  }
+  if (error instanceof InvalidWorkspacePathError) {
+    return mcpFailure(operation, "INVALID_ARGUMENT", error.message, false, {
+      details: { requestedPath: error.requestedPath },
+    });
+  }
+  if (error instanceof Error && error.name === "AbortError") {
+    return mcpFailure(operation, "CANCELLED", "The MCP operation was cancelled.", false);
+  }
+  return mcpFailure(
+    operation,
+    "INTERNAL_ERROR",
+    error instanceof Error ? error.message : String(error),
+    false,
+  );
+}
+
+function uniqueCanonicalRoots(roots: readonly string[]): string[] {
+  return [...new Set(roots.map(canonicalPotentialPath))];
+}
+
+/** Makes the JSON boundary explicit and rejects accidental non-JSON values. */
+function jsonObject(value: unknown): Record<string, unknown> {
+  const serialized = JSON.stringify(value);
+  if (serialized === undefined) {
+    throw new TypeError("The MCP response is not JSON serializable.");
+  }
+  const parsed: unknown = JSON.parse(serialized);
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new TypeError("The MCP response envelope must be a JSON object.");
+  }
+  return parsed as Record<string, unknown>;
+}

package/src/mcp/stdio.ts

@@ -0,0 +1,92 @@
+import {
+  serveStdio,
+  StdioServerTransport,
+  type StdioServerHandle,
+} from "@modelcontextprotocol/server/stdio";
+
+import { createUntangleMcpServer, type CreateUntangleMcpServerOptions } from "./server.js";
+
+export interface ServeUntangleMcpStdioOptions extends CreateUntangleMcpServerOptions {
+  readonly onerror?: (error: Error) => void;
+  /** Injection seam for lifecycle tests and non-process stdio bindings. */
+  readonly transport?: StdioServerTransport;
+}
+
+export type UntangleStdioCloseOutcome =
+  { readonly reason: "closed" } | { readonly reason: "error"; readonly error: Error };
+
+export interface UntangleStdioServerHandle extends StdioServerHandle {
+  /** Settles when the owned wire transport actually closes. */
+  readonly closed: Promise<UntangleStdioCloseOutcome>;
+}
+
+/** Starts the dual-era MCP stdio binding. stdout remains JSON-RPC only. */
+export function serveUntangleMcpStdio(
+  options: ServeUntangleMcpStdioOptions = {},
+): UntangleStdioServerHandle {
+  const transport = options.transport ?? new StdioServerTransport();
+  let pendingTransportError: Error | undefined;
+  let closingFromHandle = false;
+  let settleClosed!: (outcome: UntangleStdioCloseOutcome) => void;
+  let didSettle = false;
+  const closed = new Promise<UntangleStdioCloseOutcome>((resolve) => {
+    settleClosed = (outcome) => {
+      if (didSettle) return;
+      didSettle = true;
+      resolve(outcome);
+    };
+  });
+
+  // The upstream handle exposes close(), but not the wire's close event. A
+  // fatal buffer/stdout failure calls transport.close() while stdin may stay
+  // open; intercepting that actual close gives the CLI a lifecycle signal.
+  // Recoverable protocol errors only call onerror and therefore do not end
+  // this promise.
+  const closeTransport = transport.close.bind(transport);
+  const startTransport = transport.start.bind(transport);
+  transport.start = async (): Promise<void> => {
+    try {
+      await startTransport();
+    } catch (error) {
+      settleClosed({
+        reason: "error",
+        error: error instanceof Error ? error : new Error(String(error)),
+      });
+      throw error;
+    }
+  };
+  transport.close = async (): Promise<void> => {
+    const fatalError = closingFromHandle ? undefined : pendingTransportError;
+    try {
+      await closeTransport();
+    } finally {
+      settleClosed(
+        fatalError === undefined ? { reason: "closed" } : { reason: "error", error: fatalError },
+      );
+    }
+  };
+
+  const handle = serveStdio(() => createUntangleMcpServer(options), {
+    legacy: "serve",
+    transport,
+    onerror: (error) => {
+      pendingTransportError = error;
+      queueMicrotask(() => {
+        if (pendingTransportError === error) pendingTransportError = undefined;
+      });
+      options.onerror?.(error);
+    },
+  });
+
+  return {
+    closed,
+    async close(): Promise<void> {
+      closingFromHandle = true;
+      try {
+        await handle.close();
+      } finally {
+        settleClosed({ reason: "closed" });
+      }
+    },
+  };
+}