@zigrivers/surface-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,1030 @@
+// src/index.ts
+import { pathToFileURL } from "url";
+import {
+  DEFAULT_COMPOSITION_STAGE_IDS,
+  DEFAULT_SURFACE_CONFIG,
+  createBoundedAlternatives,
+  createTrackedFinding,
+  createSurfaceComposition,
+  createSurfaceError,
+  diffTrackedFindings,
+  err,
+  instantiateLensExecutionPlan,
+  isOk,
+  ok,
+  scoreFinding,
+  selectLensExecutionPlan,
+  synthesizeBacklog,
+  toMcpError,
+  transitionTrackedFinding
+} from "@zigrivers/surface-core";
+import { z } from "zod";
+var SURFACE_MCP_SERVER_NAME = "surface";
+var SURFACE_MCP_SERVER_VERSION = "1.0.0";
+var SURFACE_MCP_TOOL_SCHEMA_VERSION = "1.0.0";
+var TOOL_ORDER = [
+  "surface_capture",
+  "surface_audit",
+  "surface_explain",
+  "surface_backlog",
+  "surface_gate",
+  "surface_validate",
+  "surface_baseline",
+  "surface_verdict",
+  "surface_diff",
+  "surface_alternatives",
+  "surface_trace",
+  "surface_run",
+  "surface_next",
+  "surface_status"
+];
+var TargetSchema = z.object({
+  kind: z.enum(["url", "localhost", "route", "screenshot", "component", "dom"]),
+  ref: z.string().min(1),
+  theme: z.enum(["light", "dark"]).optional(),
+  viewport: z.object({
+    height: z.number().int().positive(),
+    label: z.enum(["mobile", "tablet", "desktop"]),
+    width: z.number().int().positive()
+  }).strict().optional()
+}).strict();
+var AuthStateRefSchema = z.string().min(1);
+var RunRefSchema = z.object({ runId: z.string().min(1) }).strict();
+var GatePolicyInputSchema = z.record(z.string(), z.unknown());
+var TOOL_INPUT_SCHEMAS = {
+  surface_capture: z.object({
+    authState: AuthStateRefSchema.optional(),
+    target: TargetSchema
+  }).strict(),
+  surface_audit: z.object({
+    authState: AuthStateRefSchema.optional(),
+    depth: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4), z.literal(5)]).optional(),
+    persona: z.string().min(1).optional(),
+    preset: z.string().min(1).optional(),
+    target: TargetSchema,
+    task: z.string().min(1).optional()
+  }).strict(),
+  surface_explain: z.object({ findingId: z.string().min(1) }).strict(),
+  surface_backlog: z.object({
+    exportTarget: z.string().min(1).optional(),
+    runId: z.string().min(1).optional()
+  }).strict(),
+  surface_gate: z.object({
+    policy: GatePolicyInputSchema.optional(),
+    runId: z.string().min(1).optional()
+  }).strict(),
+  surface_validate: z.object({ runId: z.string().min(1) }).strict(),
+  surface_baseline: z.object({ reason: z.string().min(1).optional() }).strict(),
+  surface_verdict: z.object({
+    decision: z.enum(["accept", "reject", "correct", "defer"]),
+    findingId: z.string().min(1),
+    rationale: z.string().min(1)
+  }).strict(),
+  surface_diff: z.object({ after: RunRefSchema, before: RunRefSchema }).strict(),
+  surface_alternatives: z.object({
+    authState: AuthStateRefSchema.optional(),
+    target: TargetSchema
+  }).strict(),
+  surface_trace: z.object({ findingId: z.string().min(1) }).strict(),
+  surface_run: z.object({
+    step: z.string().min(1),
+    target: TargetSchema.optional()
+  }).strict(),
+  surface_next: z.object({}).strict(),
+  surface_status: z.object({}).strict()
+};
+var TOOL_METADATA = {
+  surface_capture: {
+    title: "Capture Target",
+    description: "Capture a target into Surface artifacts."
+  },
+  surface_audit: {
+    title: "Audit Target",
+    description: "Run a Surface audit over a target."
+  },
+  surface_explain: {
+    title: "Explain Finding",
+    description: "Explain one Surface finding with evidence."
+  },
+  surface_backlog: {
+    title: "Read Backlog",
+    description: "Return or export the implementation backlog."
+  },
+  surface_gate: {
+    title: "Evaluate Gate",
+    description: "Evaluate the configured Surface quality gate."
+  },
+  surface_validate: {
+    title: "Validate Run",
+    description: "Run validation checks for an audit run."
+  },
+  surface_baseline: {
+    title: "Create Baseline",
+    description: "Baseline current findings for future gate comparisons."
+  },
+  surface_verdict: {
+    title: "Record Verdict",
+    description: "Record a human verdict for a finding."
+  },
+  surface_diff: {
+    title: "Diff Runs",
+    description: "Compare findings across two audit runs."
+  },
+  surface_alternatives: {
+    title: "Suggest Alternatives",
+    description: "Suggest bounded alternatives for a target."
+  },
+  surface_trace: {
+    title: "Trace Finding",
+    description: "Trace a finding through closed-loop state."
+  },
+  surface_run: {
+    title: "Run Pipeline Step",
+    description: "Run a Surface pipeline step."
+  },
+  surface_next: {
+    title: "List Next Steps",
+    description: "List eligible Surface pipeline steps."
+  },
+  surface_status: {
+    title: "Read Status",
+    description: "Read Surface project status."
+  }
+};
+var INTERNAL_TOOLS = TOOL_ORDER.map((name) => {
+  const metadata = TOOL_METADATA[name];
+  const inputZodSchema = TOOL_INPUT_SCHEMAS[name];
+  return {
+    name,
+    ...metadata,
+    inputZodSchema,
+    inputSchema: z.toJSONSchema(inputZodSchema),
+    schemaVersion: SURFACE_MCP_TOOL_SCHEMA_VERSION
+  };
+});
+function createSurfaceMcpToolRegistry() {
+  const toolsByName = new Map(
+    INTERNAL_TOOLS.map((tool) => [tool.name, tool])
+  );
+  return {
+    serverInfo: {
+      name: SURFACE_MCP_SERVER_NAME,
+      version: SURFACE_MCP_SERVER_VERSION
+    },
+    getTool: (name) => {
+      const tool = toolsByName.get(name);
+      return tool === void 0 ? void 0 : publicToolDefinition(tool);
+    },
+    listTools: () => INTERNAL_TOOLS.map(publicToolDefinition)
+  };
+}
+function createSurfaceMcpServer(options = {}) {
+  const registry = createSurfaceMcpToolRegistry();
+  const composition = options.composition ?? createSurfaceComposition(options);
+  const session = createSurfaceMcpSessionState();
+  return {
+    composition,
+    callTool: async (name, input) => {
+      const hydrated = await hydrateSurfaceMcpSession(composition, session);
+      if (!hydrated.ok) {
+        return hydrated;
+      }
+      return await callSurfaceMcpTool({
+        composition,
+        input,
+        name,
+        session
+      });
+    },
+    registry,
+    listTools: () => registry.listTools()
+  };
+}
+function createMcpToolSchemaSnapshot(registry = createSurfaceMcpToolRegistry()) {
+  return registry.listTools().map((tool) => ({
+    inputSchema: tool.inputSchema,
+    name: tool.name,
+    schemaVersion: tool.schemaVersion
+  }));
+}
+function assertMcpToolSchemaCompatibility(input) {
+  if (input.current.name !== input.next.name) {
+    return mcpSchemaIncompatible(
+      "MCP tool names cannot change without a major version bump.",
+      input
+    );
+  }
+  if (!hasMajorVersionIncrement(input.current.schemaVersion, input.next.schemaVersion)) {
+    const currentRequired = requiredFields(input.current.inputSchema);
+    const nextRequired = requiredFields(input.next.inputSchema);
+    const addedRequired = [...nextRequired].filter((field) => !currentRequired.has(field));
+    if (addedRequired.length > 0) {
+      return mcpSchemaIncompatible(
+        "MCP tool schema added required fields without a major version bump.",
+        input,
+        { addedRequired }
+      );
+    }
+  }
+  return ok(true);
+}
+function createSurfaceMcpSessionState() {
+  return {
+    baselines: /* @__PURE__ */ new Map(),
+    baselineOrder: [],
+    runs: /* @__PURE__ */ new Map(),
+    runOrder: [],
+    trackedByIdentity: /* @__PURE__ */ new Map(),
+    verdicts: /* @__PURE__ */ new Map(),
+    nextBaselineSequence: 1,
+    nextRunSequence: 1
+  };
+}
+async function hydrateSurfaceMcpSession(composition, session) {
+  const state = await composition.stateStore.readState();
+  if (!state.ok) {
+    return state;
+  }
+  resetSurfaceMcpSessionFromState(session, state.value);
+  return ok(void 0);
+}
+function resetSurfaceMcpSessionFromState(session, state) {
+  session.baselines.clear();
+  session.baselineOrder.length = 0;
+  session.runs.clear();
+  session.runOrder.length = 0;
+  session.trackedByIdentity.clear();
+  session.verdicts.clear();
+  for (const trackedFinding of state.trackedFindings ?? []) {
+    session.trackedByIdentity.set(trackedFinding.identityKey, trackedFinding);
+  }
+  for (const record of state.runRecords ?? []) {
+    const mcpRecord = surfaceMcpRunRecordFromProjectRecord(record);
+    if (mcpRecord === void 0) {
+      continue;
+    }
+    session.runs.set(mcpRecord.runId, mcpRecord);
+    session.runOrder.push(mcpRecord.runId);
+    for (const trackedFinding of mcpRecord.trackedFindings) {
+      session.trackedByIdentity.set(trackedFinding.identityKey, trackedFinding);
+    }
+  }
+  for (const baseline of state.baselines ?? []) {
+    const mcpBaseline = surfaceMcpBaselineFromProjectBaseline(baseline);
+    session.baselines.set(mcpBaseline.baselineId, mcpBaseline);
+    session.baselineOrder.push(mcpBaseline.baselineId);
+  }
+  for (const verdict of state.verdicts ?? []) {
+    if (isSurfaceMcpVerdict(verdict)) {
+      session.verdicts.set(verdict.findingId, verdict);
+    }
+  }
+  session.nextRunSequence = nextSequenceFromIds(session.runOrder, "run_mcp_");
+  session.nextBaselineSequence = nextSequenceFromIds(session.baselineOrder, "baseline_mcp_");
+}
+function surfaceMcpRunRecordFromProjectRecord(record) {
+  if (record.backlog === void 0 || record.capture === void 0 || record.findings === void 0 || record.status === void 0 || record.skippedLenses === void 0) {
+    return void 0;
+  }
+  return {
+    backlog: record.backlog,
+    capture: record.capture,
+    findings: record.findings,
+    runId: record.runId,
+    skippedLenses: record.skippedLenses,
+    status: record.status,
+    trackedFindings: record.trackedFindings
+  };
+}
+function surfaceMcpBaselineFromProjectBaseline(baseline) {
+  return {
+    baselineId: baseline.baselineId,
+    identityKeys: new Set(baseline.identityKeys),
+    ...baseline.reason === void 0 ? {} : { reason: baseline.reason }
+  };
+}
+function isSurfaceMcpVerdict(verdict) {
+  return verdict.decision === "accept" || verdict.decision === "reject" || verdict.decision === "correct" || verdict.decision === "defer";
+}
+async function persistSurfaceMcpSession(composition, session) {
+  const updateState = stateSnapshotForMcpSession(session);
+  if (composition.stateStore.updateState !== void 0) {
+    const updated = await composition.stateStore.updateState(updateState);
+    return updated.ok ? ok(void 0) : updated;
+  }
+  const current = await composition.stateStore.readState();
+  if (!current.ok) {
+    return current;
+  }
+  const written = await composition.stateStore.writeState(updateState(current.value));
+  return written.ok ? ok(void 0) : written;
+}
+function stateSnapshotForMcpSession(session) {
+  return (state) => {
+    const runRecords = session.runOrder.map((runId) => session.runs.get(runId)).filter((record) => record !== void 0).map(projectRunRecordFromSurfaceMcpRecord);
+    const latestRun = runRecords.at(-1);
+    const baselines = session.baselineOrder.map((baselineId) => session.baselines.get(baselineId)).filter((baseline) => baseline !== void 0).map(projectBaselineFromSurfaceMcpBaseline);
+    const trackedFindings = [...session.trackedByIdentity.values()];
+    const verdicts = [...session.verdicts.values()];
+    const currentStage = latestRun?.status ?? state.currentStage;
+    return {
+      ...state,
+      ...latestRun?.backlog === void 0 ? {} : { backlog: latestRun.backlog },
+      ...currentStage === void 0 ? {} : { currentStage },
+      ...latestRun?.findings === void 0 ? {} : { findings: latestRun.findings },
+      baselines,
+      runRecords,
+      trackedFindings,
+      verdicts
+    };
+  };
+}
+function projectRunRecordFromSurfaceMcpRecord(record) {
+  return {
+    backlog: record.backlog,
+    capture: record.capture,
+    findings: record.findings,
+    runId: record.runId,
+    skippedLenses: record.skippedLenses,
+    status: record.status,
+    trackedFindings: record.trackedFindings
+  };
+}
+function projectBaselineFromSurfaceMcpBaseline(baseline) {
+  return {
+    baselineId: baseline.baselineId,
+    identityKeys: [...baseline.identityKeys],
+    ...baseline.reason === void 0 ? {} : { reason: baseline.reason },
+    waivers: []
+  };
+}
+function nextSequenceFromIds(ids, prefix) {
+  let maxSequence = 0;
+  for (const id of ids) {
+    if (!id.startsWith(prefix)) {
+      continue;
+    }
+    const sequence = Number.parseInt(id.slice(prefix.length), 10);
+    if (Number.isInteger(sequence)) {
+      maxSequence = Math.max(maxSequence, sequence);
+    }
+  }
+  return maxSequence + 1;
+}
+async function callSurfaceMcpTool(input) {
+  switch (input.name) {
+    case "surface_capture":
+      return await callSurfaceCapture(input.composition, input.input);
+    case "surface_audit":
+      return await callSurfaceAudit(input.composition, input.session, input.input);
+    case "surface_explain":
+      return callSurfaceExplain(input.session, input.input);
+    case "surface_backlog":
+      return await callSurfaceBacklog(input.composition, input.session, input.input);
+    case "surface_gate":
+      return await callSurfaceGate(input.composition, input.session, input.input);
+    case "surface_validate":
+      return callSurfaceValidate(input.session, input.input);
+    case "surface_baseline":
+      return await callSurfaceBaseline(input.composition, input.session, input.input);
+    case "surface_verdict":
+      return await callSurfaceVerdict(input.composition, input.session, input.input);
+    case "surface_diff":
+      return callSurfaceDiff(input.session, input.input);
+    case "surface_alternatives":
+      return await callSurfaceAlternatives(input.composition, input.input);
+    case "surface_trace":
+      return callSurfaceTrace(input.session, input.input);
+    case "surface_run":
+      return await callSurfaceRun(input.composition, input.input);
+    case "surface_next":
+      return await callSurfaceNext(input.composition);
+    case "surface_status":
+      return callSurfaceStatus(input.session);
+  }
+}
+async function callSurfaceCapture(composition, rawInput) {
+  const parsed = parseToolInput("surface_capture", rawInput);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  return await composition.captureService.capture(
+    targetForCore(parsed.value.target),
+    captureOptionsFor(DEFAULT_SURFACE_CONFIG, parsed.value.authState)
+  );
+}
+async function callSurfaceAudit(composition, session, rawInput) {
+  const parsed = parseToolInput("surface_audit", rawInput);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const config = configForAuditInput(parsed.value);
+  const capture = await composition.captureService.capture(
+    targetForCore(parsed.value.target),
+    captureOptionsFor(config, parsed.value.authState)
+  );
+  if (!capture.ok) {
+    return capture;
+  }
+  const evidence = await groundingEvidenceFor(composition, capture.value);
+  if (!evidence.ok) {
+    return evidence;
+  }
+  const plan = selectLensExecutionPlan({
+    capture: capture.value,
+    config,
+    modelAvailability: {
+      available: false,
+      message: "No MCP model provider is configured.",
+      reason: "no-model-configured"
+    },
+    registry: composition.lensRegistry
+  });
+  const findings = await findingsForPlan(composition, config, capture.value, evidence.value, plan);
+  if (!findings.ok) {
+    return findings;
+  }
+  const runId = nextRunId(session);
+  const backlog = synthesizeBacklog(runId, findings.value);
+  if (!backlog.ok) {
+    return backlog;
+  }
+  const trackedFindings = trackedFindingsForRun(session, runId, findings.value);
+  const record = {
+    backlog: backlog.value,
+    capture: capture.value,
+    findings: findings.value,
+    runId,
+    skippedLenses: plan.skipped,
+    status: "completed",
+    trackedFindings
+  };
+  session.runs.set(runId, record);
+  session.runOrder.push(runId);
+  const persisted = await persistSurfaceMcpSession(composition, session);
+  if (!persisted.ok) {
+    return persisted;
+  }
+  return ok({
+    backlog: record.backlog,
+    capture: record.capture,
+    findings: record.findings,
+    runId: record.runId,
+    skippedLenses: record.skippedLenses
+  });
+}
+function callSurfaceExplain(session, rawInput) {
+  const parsed = parseToolInput("surface_explain", rawInput);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const finding = findStoredFinding(session, parsed.value.findingId);
+  if (finding === void 0) {
+    return err(
+      createSurfaceError("finding_not_found", "No stored MCP finding matched the requested id.", {
+        details: { findingId: parsed.value.findingId }
+      })
+    );
+  }
+  if (finding.evidence.length === 0) {
+    return err(
+      createSurfaceError("evidence_missing", "Stored MCP finding has no evidence to explain.", {
+        details: { findingId: finding.id }
+      })
+    );
+  }
+  return ok({
+    evidence: finding.evidence,
+    finding,
+    rationale: finding.rationale
+  });
+}
+async function callSurfaceBacklog(composition, session, rawInput) {
+  const parsed = parseToolInput("surface_backlog", rawInput);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const record = runRecordFor(session, parsed.value.runId);
+  if (record === void 0) {
+    return err(
+      createSurfaceError("run_not_found", "No stored MCP run matched the requested backlog.", {
+        details: { runId: parsed.value.runId ?? null }
+      })
+    );
+  }
+  if (parsed.value.exportTarget === void 0) {
+    return ok(record.backlog);
+  }
+  const exporter = composition.issueExporters.find(
+    (candidate) => candidate.target === parsed.value.exportTarget
+  );
+  if (exporter === void 0) {
+    return err(
+      createSurfaceError(
+        "unknown_export_target",
+        "No issue exporter matched the MCP backlog target.",
+        {
+          details: { exportTarget: parsed.value.exportTarget }
+        }
+      )
+    );
+  }
+  const artifact = await composition.stateStore.writeArtifact({
+    bytes: new TextEncoder().encode(JSON.stringify(record.backlog, null, 2)),
+    kind: "report",
+    relativePath: `reports/${record.runId}/backlog.json`
+  });
+  if (!artifact.ok) {
+    return artifact;
+  }
+  const exported = await exporter.export({
+    backlogId: record.backlog.id,
+    path: artifact.value.path
+  });
+  if (!exported.ok) {
+    return exported;
+  }
+  if (exported.value.status === "partial") {
+    return err(
+      createSurfaceError("export_partial", "MCP backlog export completed partially.", {
+        details: { exportId: exported.value.id, target: exported.value.target }
+      })
+    );
+  }
+  return ok(exported.value);
+}
+async function callSurfaceGate(composition, session, rawInput) {
+  const parsed = parseToolInput("surface_gate", rawInput);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const record = runRecordFor(session, parsed.value.runId);
+  if (record === void 0) {
+    return err(
+      createSurfaceError("run_not_found", "No stored MCP run matched the requested gate.", {
+        details: { runId: parsed.value.runId ?? null }
+      })
+    );
+  }
+  const baseline = latestBaseline(session);
+  const baselineIdentityKeys = baseline?.identityKeys ?? /* @__PURE__ */ new Set();
+  const findings = record.findings.filter((finding) => {
+    const tracked = trackedFindingForRunFinding(record, finding.id);
+    return tracked === void 0 || !baselineIdentityKeys.has(tracked.identityKey);
+  });
+  const policy = parsed.value.policy === void 0 ? DEFAULT_SURFACE_CONFIG.reporting.gatePolicy : parsed.value.policy;
+  return await composition.gateEvaluator.evaluate(findings, policy);
+}
+function callSurfaceValidate(session, rawInput) {
+  const parsed = parseToolInput("surface_validate", rawInput);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const record = runRecordFor(session, parsed.value.runId);
+  if (record === void 0) {
+    return err(
+      createSurfaceError("run_not_found", "No stored MCP run matched the requested validation.", {
+        details: { runId: parsed.value.runId }
+      })
+    );
+  }
+  return ok({
+    checks: record.trackedFindings.map((trackedFinding) => ({
+      id: trackedFinding.identityKey,
+      passed: trackedFinding.status !== "identity-broken",
+      validation: trackedFinding.validation,
+      ...trackedFinding.currentFindingId === void 0 ? {} : { findingId: trackedFinding.currentFindingId }
+    }))
+  });
+}
+async function callSurfaceBaseline(composition, session, rawInput) {
+  const parsed = parseToolInput("surface_baseline", rawInput);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const record = runRecordFor(session, void 0);
+  if (record === void 0 || record.trackedFindings.length === 0) {
+    return err(
+      createSurfaceError("no_findings_to_baseline", "No MCP findings are available to baseline.")
+    );
+  }
+  const baselineId = nextBaselineId(session);
+  const baseline = {
+    baselineId,
+    identityKeys: new Set(
+      record.trackedFindings.map((trackedFinding) => trackedFinding.identityKey)
+    ),
+    ...parsed.value.reason === void 0 ? {} : { reason: parsed.value.reason }
+  };
+  session.baselines.set(baselineId, baseline);
+  session.baselineOrder.push(baselineId);
+  const persisted = await persistSurfaceMcpSession(composition, session);
+  if (!persisted.ok) {
+    return persisted;
+  }
+  return ok({
+    baselineId,
+    count: baseline.identityKeys.size,
+    ...baseline.reason === void 0 ? {} : { reason: baseline.reason }
+  });
+}
+async function callSurfaceVerdict(composition, session, rawInput) {
+  const parsed = parseToolInput("surface_verdict", rawInput);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const finding = findStoredFinding(session, parsed.value.findingId);
+  if (finding === void 0) {
+    return err(
+      createSurfaceError("finding_not_found", "No stored MCP finding matched the verdict.", {
+        details: { findingId: parsed.value.findingId }
+      })
+    );
+  }
+  const verdict = {
+    decision: parsed.value.decision,
+    findingId: parsed.value.findingId,
+    rationale: parsed.value.rationale
+  };
+  session.verdicts.set(parsed.value.findingId, verdict);
+  const persisted = await persistSurfaceMcpSession(composition, session);
+  if (!persisted.ok) {
+    return persisted;
+  }
+  return ok(verdict);
+}
+function callSurfaceDiff(session, rawInput) {
+  const parsed = parseToolInput("surface_diff", rawInput);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const before = runRecordFor(session, parsed.value.before.runId);
+  const after = runRecordFor(session, parsed.value.after.runId);
+  if (before === void 0 || after === void 0) {
+    return err(
+      createSurfaceError("run_not_found", "Both MCP diff runs must exist.", {
+        details: { after: parsed.value.after.runId, before: parsed.value.before.runId }
+      })
+    );
+  }
+  return ok(diffTrackedFindings(before.trackedFindings, after.trackedFindings));
+}
+async function callSurfaceAlternatives(composition, rawInput) {
+  const parsed = parseToolInput("surface_alternatives", rawInput);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const target = targetForCore(parsed.value.target);
+  const capture = await composition.captureService.capture(
+    target,
+    captureOptionsFor(DEFAULT_SURFACE_CONFIG, parsed.value.authState)
+  );
+  if (!capture.ok) {
+    return capture;
+  }
+  return ok({
+    alternatives: createBoundedAlternatives(target)
+  });
+}
+function callSurfaceTrace(session, rawInput) {
+  const parsed = parseToolInput("surface_trace", rawInput);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const trackedFinding = findStoredTrackedFinding(session, parsed.value.findingId);
+  if (trackedFinding === void 0) {
+    return err(
+      createSurfaceError("finding_not_found", "No tracked MCP finding matched the requested id.", {
+        details: { findingId: parsed.value.findingId }
+      })
+    );
+  }
+  return ok({ trackedFinding });
+}
+async function callSurfaceRun(composition, rawInput) {
+  const parsed = parseToolInput("surface_run", rawInput);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  if (parsed.value.step !== "all" && !isExecutableStageId(parsed.value.step)) {
+    return err(
+      createSurfaceError("unknown_step", `Unknown MCP pipeline step "${parsed.value.step}".`, {
+        details: { step: parsed.value.step }
+      })
+    );
+  }
+  const runId = nextMcpPipelineRunId();
+  const run = await composition.pipelineOrchestrator.run({
+    config: DEFAULT_SURFACE_CONFIG,
+    runId
+  });
+  if (!run.ok) {
+    return err(
+      createSurfaceError("step_failed", `MCP pipeline run ${runId} failed.`, {
+        cause: run.error,
+        details: { runId, stage: parsed.value.step }
+      })
+    );
+  }
+  return ok({
+    runId: run.value.runId,
+    stage: parsed.value.step,
+    status: "completed"
+  });
+}
+async function callSurfaceNext(composition) {
+  const state = await composition.stateStore.readState();
+  if (!state.ok) {
+    return state;
+  }
+  const lastCompletedStage = state.value.pipeline?.lastCompletedStage;
+  const eligible = lastCompletedStage === void 0 ? ["run discovery", "run all"] : eligibleStagesAfter(lastCompletedStage).map((stage) => `run ${stage}`);
+  return ok({ eligible });
+}
+function callSurfaceStatus(session) {
+  const runHistory = session.runOrder.map((runId) => session.runs.get(runId)).filter((record) => record !== void 0).map((record) => ({
+    findings: record.findings.length,
+    runId: record.runId,
+    status: record.status,
+    target: record.capture.target
+  }));
+  const completedRuns = runHistory.filter((entry) => entry.status === "completed").length;
+  const failedRuns = runHistory.filter((entry) => entry.status === "failed").length;
+  return ok({
+    currentStage: runHistory.at(-1)?.status === "completed" ? "completed" : "pending",
+    progress: {
+      completedRuns,
+      failedRuns,
+      findings: runHistory.reduce((total, entry) => total + entry.findings, 0)
+    },
+    runHistory
+  });
+}
+async function groundingEvidenceFor(composition, capture) {
+  const evidence = [];
+  for (const tool of composition.groundingTools) {
+    const result = await tool.run(capture);
+    if (!result.ok) {
+      return result;
+    }
+    for (const toolResult of result.value) {
+      evidence.push(...toolResult.evidence);
+    }
+  }
+  return ok(evidence);
+}
+async function findingsForPlan(composition, config, capture, evidence, plan) {
+  const findings = [];
+  const lenses = instantiateLensExecutionPlan(plan, composition.lensFactoryOptions);
+  for (const { lens } of lenses) {
+    const drafts = await lens.evaluate({
+      capture,
+      config,
+      evidence: [...evidence],
+      knowledge: composition.knowledgeSource
+    });
+    if (!drafts.ok) {
+      return drafts;
+    }
+    for (const draft of drafts.value) {
+      const scored = scoreFinding(draft, config.findings);
+      if (!scored.ok) {
+        return scored;
+      }
+      findings.push(scored.value);
+    }
+  }
+  return ok(findings);
+}
+function configForAuditInput(input) {
+  return {
+    ...DEFAULT_SURFACE_CONFIG,
+    capture: { ...DEFAULT_SURFACE_CONFIG.capture },
+    evaluation: {
+      ...DEFAULT_SURFACE_CONFIG.evaluation,
+      ...input.depth === void 0 ? {} : { depth: input.depth },
+      ...input.preset === void 0 ? {} : { preset: input.preset }
+    },
+    findings: { ...DEFAULT_SURFACE_CONFIG.findings },
+    reporting: { ...DEFAULT_SURFACE_CONFIG.reporting }
+  };
+}
+function captureOptionsFor(config, authStateRef) {
+  return {
+    config: config.capture,
+    ...authStateRef === void 0 ? {} : { authStateRef }
+  };
+}
+function targetForCore(input) {
+  return {
+    kind: input.kind,
+    ref: input.ref,
+    ...input.theme === void 0 ? {} : { theme: input.theme },
+    ...input.viewport === void 0 ? {} : {
+      viewport: {
+        height: input.viewport.height,
+        label: input.viewport.label,
+        width: input.viewport.width
+      }
+    }
+  };
+}
+function parseToolInput(name, input) {
+  const parsed = TOOL_INPUT_SCHEMAS[name].safeParse(input);
+  if (!parsed.success) {
+    return err(
+      createSurfaceError("config_invalid", "MCP tool input did not match the registered schema.", {
+        cause: parsed.error,
+        details: { tool: name }
+      })
+    );
+  }
+  return ok(parsed.data);
+}
+function nextRunId(session) {
+  const runId = `run_mcp_${session.nextRunSequence.toString().padStart(4, "0")}`;
+  session.nextRunSequence += 1;
+  return runId;
+}
+function nextBaselineId(session) {
+  const baselineId = `baseline_mcp_${session.nextBaselineSequence.toString().padStart(4, "0")}`;
+  session.nextBaselineSequence += 1;
+  return baselineId;
+}
+function nextMcpPipelineRunId() {
+  return `run_mcp_pipeline_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function isExecutableStageId(step) {
+  return DEFAULT_COMPOSITION_STAGE_IDS.includes(step);
+}
+function eligibleStagesAfter(lastCompletedStage) {
+  const index = DEFAULT_COMPOSITION_STAGE_IDS.findIndex((stage) => stage === lastCompletedStage);
+  if (index === -1) {
+    return DEFAULT_COMPOSITION_STAGE_IDS;
+  }
+  return DEFAULT_COMPOSITION_STAGE_IDS.slice(index + 1);
+}
+function runRecordFor(session, runId) {
+  if (runId !== void 0) {
+    return session.runs.get(runId);
+  }
+  const latestRunId = session.runOrder.at(-1);
+  return latestRunId === void 0 ? void 0 : session.runs.get(latestRunId);
+}
+function findStoredFinding(session, findingId) {
+  for (const runId of session.runOrder) {
+    const record = session.runs.get(runId);
+    const finding = record?.findings.find((candidate) => candidate.id === findingId);
+    if (finding !== void 0) {
+      return finding;
+    }
+  }
+  return void 0;
+}
+function trackedFindingsForRun(session, runId, findings) {
+  return findings.map((finding) => {
+    const initial = createTrackedFinding({
+      finding,
+      runId,
+      validation: validationForFinding(finding)
+    });
+    const previous = session.trackedByIdentity.get(initial.identityKey);
+    const trackedFinding = previous === void 0 ? initial : transitionTrackedFinding(previous, { finding, kind: "detected", runId });
+    session.trackedByIdentity.set(trackedFinding.identityKey, trackedFinding);
+    return trackedFinding;
+  });
+}
+function validationForFinding(finding) {
+  if (finding.method === "measured") {
+    const toolEvidence = finding.evidence.find((entry) => entry.kind === "tool-result");
+    return {
+      expectation: toolEvidence === void 0 ? `${finding.lens}/${finding.issueType} remains resolved.` : `${toolEvidence.tool} ${toolEvidence.rule} passes for ${locationLabelFor(finding)}.`,
+      kind: "measured-rule"
+    };
+  }
+  return {
+    expectation: `${finding.lens}/${finding.issueType} should be re-evaluated at ${locationLabelFor(
+      finding
+    )}.`,
+    kind: "re-evaluate-lens"
+  };
+}
+function locationLabelFor(finding) {
+  return finding.location.elementRef ?? finding.location.selector ?? finding.location.component ?? finding.location.file ?? finding.id;
+}
+function latestBaseline(session) {
+  const baselineId = session.baselineOrder.at(-1);
+  return baselineId === void 0 ? void 0 : session.baselines.get(baselineId);
+}
+function trackedFindingForRunFinding(record, findingId) {
+  return record.trackedFindings.find(
+    (trackedFinding) => trackedFinding.currentFindingId === findingId
+  );
+}
+function findStoredTrackedFinding(session, findingId) {
+  for (const trackedFinding of session.trackedByIdentity.values()) {
+    if (trackedFinding.currentFindingId === findingId) {
+      return trackedFinding;
+    }
+  }
+  return void 0;
+}
+async function createSurfaceSdkMcpServer(options = {}) {
+  const surfaceServer = createSurfaceMcpServer(options);
+  const [{ McpServer }] = await Promise.all([import("@modelcontextprotocol/sdk/server/mcp.js")]);
+  const server = new McpServer({
+    name: SURFACE_MCP_SERVER_NAME,
+    version: SURFACE_MCP_SERVER_VERSION
+  });
+  for (const tool of INTERNAL_TOOLS) {
+    server.registerTool(
+      tool.name,
+      {
+        description: tool.description,
+        inputSchema: tool.inputZodSchema,
+        title: tool.title
+      },
+      async (input) => mcpToolCallResult(await surfaceServer.callTool(tool.name, input))
+    );
+  }
+  return server;
+}
+async function runSurfaceMcpStdioServer(options = {}) {
+  const [{ StdioServerTransport }, server] = await Promise.all([
+    import("@modelcontextprotocol/sdk/server/stdio.js"),
+    createSurfaceSdkMcpServer(options)
+  ]);
+  await server.connect(new StdioServerTransport());
+}
+function mcpToolCallResult(result) {
+  if (isOk(result)) {
+    return {
+      content: [{ text: JSON.stringify(result.value, null, 2), type: "text" }],
+      structuredContent: result.value
+    };
+  }
+  return {
+    content: [{ text: result.error.message, type: "text" }],
+    isError: true,
+    structuredContent: toMcpError(result.error)
+  };
+}
+function publicToolDefinition(tool) {
+  return {
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    name: tool.name,
+    schemaVersion: tool.schemaVersion,
+    title: tool.title
+  };
+}
+function requiredFields(schema) {
+  const required = schema.required;
+  return Array.isArray(required) ? new Set(required.filter((field) => typeof field === "string")) : /* @__PURE__ */ new Set();
+}
+function hasMajorVersionIncrement(currentVersion, nextVersion) {
+  const currentMajor = majorVersion(currentVersion);
+  const nextMajor = majorVersion(nextVersion);
+  return currentMajor !== void 0 && nextMajor !== void 0 && nextMajor > currentMajor;
+}
+function majorVersion(version) {
+  const match = /^(\d+)\./u.exec(version);
+  const value = match?.[1];
+  if (value === void 0) {
+    return void 0;
+  }
+  const major = Number(value);
+  return Number.isInteger(major) ? major : void 0;
+}
+function mcpSchemaIncompatible(message, input, details = {}) {
+  return err(
+    createSurfaceError("mcp_schema_incompatible", message, {
+      details: {
+        current: {
+          name: input.current.name,
+          schemaVersion: input.current.schemaVersion
+        },
+        next: {
+          name: input.next.name,
+          schemaVersion: input.next.schemaVersion
+        },
+        ...details
+      }
+    })
+  );
+}
+if (process.argv[1] !== void 0 && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await runSurfaceMcpStdioServer();
+}
+export {
+  SURFACE_MCP_SERVER_NAME,
+  SURFACE_MCP_SERVER_VERSION,
+  SURFACE_MCP_TOOL_SCHEMA_VERSION,
+  assertMcpToolSchemaCompatibility,
+  createMcpToolSchemaSnapshot,
+  createSurfaceMcpServer,
+  createSurfaceMcpToolRegistry,
+  createSurfaceSdkMcpServer,
+  runSurfaceMcpStdioServer
+};
+//# sourceMappingURL=index.js.map