@rce-mcp/contracts 0.1.0

package/dist/index.js

@@ -0,0 +1,234 @@
+import { z } from "zod";
+export const API_VERSION = "v1";
+export const PublicToolNameSchema = z.enum(["search_context", "enhance_prompt"]);
+export const ErrorCodeSchema = z.enum([
+    "INVALID_ARGUMENT",
+    "UNAUTHENTICATED",
+    "FORBIDDEN",
+    "NOT_FOUND",
+    "RATE_LIMITED",
+    "CONFLICT",
+    "UPSTREAM_FAILURE",
+    "INTERNAL"
+]);
+export const ErrorEnvelopeSchema = z
+    .object({
+    error: z
+        .object({
+        code: ErrorCodeSchema,
+        message: z.string().min(1),
+        retryable: z.boolean(),
+        trace_id: z.string().min(1),
+        details: z.record(z.unknown()).optional()
+    })
+        .strict()
+})
+    .strict();
+export const SearchContextFiltersSchema = z
+    .object({
+    language: z.string().max(50).optional(),
+    path_prefix: z.string().max(1024).optional(),
+    glob: z.string().max(256).optional()
+})
+    .strict();
+export const SearchContextInputSchema = z
+    .object({
+    project_root_path: z.string().min(1).max(1024),
+    query: z.string().min(3).max(4000),
+    top_k: z.number().int().min(1).max(20).default(8),
+    filters: SearchContextFiltersSchema.optional()
+})
+    .strict();
+export const SearchContextResultSchema = z
+    .object({
+    path: z.string(),
+    start_line: z.number().int().min(1),
+    end_line: z.number().int().min(1),
+    snippet: z.string(),
+    score: z.number(),
+    reason: z.string()
+})
+    .strict();
+export const SearchContextOutputSchema = z
+    .object({
+    trace_id: z.string().min(1),
+    results: z.array(SearchContextResultSchema),
+    search_metadata: z
+        .object({
+        latency_ms: z.number().int().min(0),
+        retrieval_mode: z.enum(["hybrid", "vector", "lexical"]),
+        index_version: z.string()
+    })
+        .strict()
+})
+    .strict();
+export const SyncPushFileSchema = z
+    .object({
+    path: z.string().min(1).max(2048),
+    content: z.string().max(1_000_000),
+    language: z.string().min(1).max(50).optional(),
+    generated: z.boolean().optional(),
+    binary: z.boolean().optional(),
+    updated_at: z.string().max(64).optional()
+})
+    .strict();
+export const SyncPushInputSchema = z
+    .object({
+    project_root_path: z.string().min(1).max(1024),
+    workspace_id: z.string().min(1).max(128).optional(),
+    index_version: z.string().min(1).max(128).optional(),
+    files: z.array(SyncPushFileSchema).min(1).max(10_000)
+})
+    .strict();
+export const SyncPushDeltaInputSchema = z
+    .object({
+    project_root_path: z.string().min(1).max(1024),
+    workspace_id: z.string().min(1).max(128).optional(),
+    base_index_version: z.string().min(1).max(128).optional(),
+    upsert_files: z.array(SyncPushFileSchema).max(10_000).default([]),
+    deleted_paths: z.array(z.string().min(1).max(2048)).max(10_000).default([])
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.upsert_files.length + value.deleted_paths.length <= 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "at least one delta operation is required",
+            path: ["upsert_files"]
+        });
+    }
+});
+export const SyncPushReportSchema = z
+    .object({
+    status: z.string(),
+    counts: z
+        .object({
+        added: z.number().int().min(0),
+        modified: z.number().int().min(0),
+        deleted: z.number().int().min(0),
+        unchanged: z.number().int().min(0),
+        skipped: z.number().int().min(0)
+    })
+        .strict()
+})
+    .strict();
+export const SyncPushResponseSchema = z
+    .object({
+    trace_id: z.string().min(1),
+    tenant_id: z.string().min(1),
+    workspace_id: z.string().min(1).max(128),
+    project_root_path: z.string().min(1).max(1024),
+    index_version: z.string().min(1).max(128),
+    workspace_created: z.boolean(),
+    report: SyncPushReportSchema
+})
+    .strict();
+export const SyncPushDeltaResponseSchema = SyncPushResponseSchema.extend({
+    base_index_version: z.string().min(1).max(128).nullable(),
+    applied_delta: z
+        .object({
+        upsert_files: z.number().int().min(0),
+        deleted_paths: z.number().int().min(0)
+    })
+        .strict()
+}).strict();
+export const ConversationMessageSchema = z
+    .object({
+    role: z.enum(["user", "assistant", "system"]),
+    content: z.string().max(4000)
+})
+    .strict();
+export const EnhancePromptInputSchema = z
+    .object({
+    prompt: z.string().min(3).max(12000),
+    conversation_history: z.array(ConversationMessageSchema).max(30),
+    project_root_path: z.string().max(1024).optional()
+})
+    .strict();
+export const ContextRefSchema = z
+    .object({
+    path: z.string(),
+    start_line: z.number().int().min(1),
+    end_line: z.number().int().min(1),
+    reason: z.string()
+})
+    .strict();
+export const EnhancePromptOutputSchema = z
+    .object({
+    trace_id: z.string().min(1),
+    enhanced_prompt: z.string(),
+    context_refs: z.array(ContextRefSchema),
+    warnings: z.array(z.string()),
+    questions: z.array(z.string())
+})
+    .strict();
+export const RetrievalBenchmarkRepoSchema = z
+    .object({
+    id: z.string().min(1).max(100),
+    git_url: z.string().min(1).max(2000),
+    commit: z.string().regex(/^[0-9a-f]{7,40}$/i),
+    split: z.enum(["train", "dev", "test"]),
+    language: z.string().max(50).optional(),
+    notes: z.string().max(500).optional()
+})
+    .strict();
+export const RetrievalBenchmarkManifestSchema = z
+    .object({
+    schema_version: z.literal("v1"),
+    generated_at: z.string().datetime().optional(),
+    repos: z.array(RetrievalBenchmarkRepoSchema).min(1)
+})
+    .strict();
+export const RetrievalBenchmarkQuerySchema = z
+    .object({
+    id: z.string().min(1).max(120),
+    repo_id: z.string().min(1).max(100),
+    tool: z.enum(["search_context", "enhance_prompt"]).default("search_context"),
+    query: z.string().min(3).max(4000),
+    expected_paths: z.array(z.string().min(1).max(2048)).min(1),
+    tags: z.array(z.string().min(1).max(50)).max(12).optional(),
+    notes: z.string().max(500).optional()
+})
+    .strict();
+export function isPublicToolName(value) {
+    return PublicToolNameSchema.safeParse(value).success;
+}
+export function toValidationDetails(error) {
+    const issue = error.issues[0];
+    return {
+        field: issue?.path.join(".") ?? "unknown",
+        reason: issue?.message ?? "invalid input"
+    };
+}
+export function makeErrorEnvelope(input) {
+    return {
+        error: {
+            code: input.code,
+            message: input.message,
+            retryable: input.retryable ?? false,
+            trace_id: input.trace_id,
+            ...(input.details ? { details: input.details } : {})
+        }
+    };
+}
+export function errorCodeToHttpStatus(code) {
+    switch (code) {
+        case "INVALID_ARGUMENT":
+            return 400;
+        case "UNAUTHENTICATED":
+            return 401;
+        case "FORBIDDEN":
+            return 403;
+        case "NOT_FOUND":
+            return 404;
+        case "CONFLICT":
+            return 409;
+        case "RATE_LIMITED":
+            return 429;
+        case "UPSTREAM_FAILURE":
+            return 503;
+        case "INTERNAL":
+        default:
+            return 500;
+    }
+}

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@rce-mcp/contracts",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,281 @@
+import { z } from "zod";
+
+export const API_VERSION = "v1" as const;
+
+export const PublicToolNameSchema = z.enum(["search_context", "enhance_prompt"]);
+export type PublicToolName = z.infer<typeof PublicToolNameSchema>;
+
+export const ErrorCodeSchema = z.enum([
+  "INVALID_ARGUMENT",
+  "UNAUTHENTICATED",
+  "FORBIDDEN",
+  "NOT_FOUND",
+  "RATE_LIMITED",
+  "CONFLICT",
+  "UPSTREAM_FAILURE",
+  "INTERNAL"
+]);
+export type ErrorCode = z.infer<typeof ErrorCodeSchema>;
+
+export const ErrorEnvelopeSchema = z
+  .object({
+    error: z
+      .object({
+        code: ErrorCodeSchema,
+        message: z.string().min(1),
+        retryable: z.boolean(),
+        trace_id: z.string().min(1),
+        details: z.record(z.unknown()).optional()
+      })
+      .strict()
+  })
+  .strict();
+export type ErrorEnvelope = z.infer<typeof ErrorEnvelopeSchema>;
+
+export const SearchContextFiltersSchema = z
+  .object({
+    language: z.string().max(50).optional(),
+    path_prefix: z.string().max(1024).optional(),
+    glob: z.string().max(256).optional()
+  })
+  .strict();
+
+export const SearchContextInputSchema = z
+  .object({
+    project_root_path: z.string().min(1).max(1024),
+    query: z.string().min(3).max(4000),
+    top_k: z.number().int().min(1).max(20).default(8),
+    filters: SearchContextFiltersSchema.optional()
+  })
+  .strict();
+export type SearchContextInput = z.infer<typeof SearchContextInputSchema>;
+
+export const SearchContextResultSchema = z
+  .object({
+    path: z.string(),
+    start_line: z.number().int().min(1),
+    end_line: z.number().int().min(1),
+    snippet: z.string(),
+    score: z.number(),
+    reason: z.string()
+  })
+  .strict();
+
+export const SearchContextOutputSchema = z
+  .object({
+    trace_id: z.string().min(1),
+    results: z.array(SearchContextResultSchema),
+    search_metadata: z
+      .object({
+        latency_ms: z.number().int().min(0),
+        retrieval_mode: z.enum(["hybrid", "vector", "lexical"]),
+        index_version: z.string()
+      })
+      .strict()
+  })
+  .strict();
+export type SearchContextOutput = z.infer<typeof SearchContextOutputSchema>;
+
+export const SyncPushFileSchema = z
+  .object({
+    path: z.string().min(1).max(2048),
+    content: z.string().max(1_000_000),
+    language: z.string().min(1).max(50).optional(),
+    generated: z.boolean().optional(),
+    binary: z.boolean().optional(),
+    updated_at: z.string().max(64).optional()
+  })
+  .strict();
+export type SyncPushFile = z.infer<typeof SyncPushFileSchema>;
+
+export const SyncPushInputSchema = z
+  .object({
+    project_root_path: z.string().min(1).max(1024),
+    workspace_id: z.string().min(1).max(128).optional(),
+    index_version: z.string().min(1).max(128).optional(),
+    files: z.array(SyncPushFileSchema).min(1).max(10_000)
+  })
+  .strict();
+export type SyncPushInput = z.infer<typeof SyncPushInputSchema>;
+
+export const SyncPushDeltaInputSchema = z
+  .object({
+    project_root_path: z.string().min(1).max(1024),
+    workspace_id: z.string().min(1).max(128).optional(),
+    base_index_version: z.string().min(1).max(128).optional(),
+    upsert_files: z.array(SyncPushFileSchema).max(10_000).default([]),
+    deleted_paths: z.array(z.string().min(1).max(2048)).max(10_000).default([])
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.upsert_files.length + value.deleted_paths.length <= 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "at least one delta operation is required",
+        path: ["upsert_files"]
+      });
+    }
+  });
+export type SyncPushDeltaInput = z.infer<typeof SyncPushDeltaInputSchema>;
+
+export const SyncPushReportSchema = z
+  .object({
+    status: z.string(),
+    counts: z
+      .object({
+        added: z.number().int().min(0),
+        modified: z.number().int().min(0),
+        deleted: z.number().int().min(0),
+        unchanged: z.number().int().min(0),
+        skipped: z.number().int().min(0)
+      })
+      .strict()
+  })
+  .strict();
+export type SyncPushReport = z.infer<typeof SyncPushReportSchema>;
+
+export const SyncPushResponseSchema = z
+  .object({
+    trace_id: z.string().min(1),
+    tenant_id: z.string().min(1),
+    workspace_id: z.string().min(1).max(128),
+    project_root_path: z.string().min(1).max(1024),
+    index_version: z.string().min(1).max(128),
+    workspace_created: z.boolean(),
+    report: SyncPushReportSchema
+  })
+  .strict();
+export type SyncPushResponse = z.infer<typeof SyncPushResponseSchema>;
+
+export const SyncPushDeltaResponseSchema = SyncPushResponseSchema.extend({
+  base_index_version: z.string().min(1).max(128).nullable(),
+  applied_delta: z
+    .object({
+      upsert_files: z.number().int().min(0),
+      deleted_paths: z.number().int().min(0)
+    })
+    .strict()
+}).strict();
+export type SyncPushDeltaResponse = z.infer<typeof SyncPushDeltaResponseSchema>;
+
+export const ConversationMessageSchema = z
+  .object({
+    role: z.enum(["user", "assistant", "system"]),
+    content: z.string().max(4000)
+  })
+  .strict();
+
+export const EnhancePromptInputSchema = z
+  .object({
+    prompt: z.string().min(3).max(12000),
+    conversation_history: z.array(ConversationMessageSchema).max(30),
+    project_root_path: z.string().max(1024).optional()
+  })
+  .strict();
+export type EnhancePromptInput = z.infer<typeof EnhancePromptInputSchema>;
+
+export const ContextRefSchema = z
+  .object({
+    path: z.string(),
+    start_line: z.number().int().min(1),
+    end_line: z.number().int().min(1),
+    reason: z.string()
+  })
+  .strict();
+
+export const EnhancePromptOutputSchema = z
+  .object({
+    trace_id: z.string().min(1),
+    enhanced_prompt: z.string(),
+    context_refs: z.array(ContextRefSchema),
+    warnings: z.array(z.string()),
+    questions: z.array(z.string())
+  })
+  .strict();
+export type EnhancePromptOutput = z.infer<typeof EnhancePromptOutputSchema>;
+
+export const RetrievalBenchmarkRepoSchema = z
+  .object({
+    id: z.string().min(1).max(100),
+    git_url: z.string().min(1).max(2000),
+    commit: z.string().regex(/^[0-9a-f]{7,40}$/i),
+    split: z.enum(["train", "dev", "test"]),
+    language: z.string().max(50).optional(),
+    notes: z.string().max(500).optional()
+  })
+  .strict();
+export type RetrievalBenchmarkRepo = z.infer<typeof RetrievalBenchmarkRepoSchema>;
+
+export const RetrievalBenchmarkManifestSchema = z
+  .object({
+    schema_version: z.literal("v1"),
+    generated_at: z.string().datetime().optional(),
+    repos: z.array(RetrievalBenchmarkRepoSchema).min(1)
+  })
+  .strict();
+export type RetrievalBenchmarkManifest = z.infer<typeof RetrievalBenchmarkManifestSchema>;
+
+export const RetrievalBenchmarkQuerySchema = z
+  .object({
+    id: z.string().min(1).max(120),
+    repo_id: z.string().min(1).max(100),
+    tool: z.enum(["search_context", "enhance_prompt"]).default("search_context"),
+    query: z.string().min(3).max(4000),
+    expected_paths: z.array(z.string().min(1).max(2048)).min(1),
+    tags: z.array(z.string().min(1).max(50)).max(12).optional(),
+    notes: z.string().max(500).optional()
+  })
+  .strict();
+export type RetrievalBenchmarkQuery = z.infer<typeof RetrievalBenchmarkQuerySchema>;
+
+export function isPublicToolName(value: string): value is PublicToolName {
+  return PublicToolNameSchema.safeParse(value).success;
+}
+
+export function toValidationDetails(error: z.ZodError): Record<string, unknown> {
+  const issue = error.issues[0];
+  return {
+    field: issue?.path.join(".") ?? "unknown",
+    reason: issue?.message ?? "invalid input"
+  };
+}
+
+export function makeErrorEnvelope(input: {
+  code: ErrorCode;
+  message: string;
+  trace_id: string;
+  retryable?: boolean;
+  details?: Record<string, unknown>;
+}): ErrorEnvelope {
+  return {
+    error: {
+      code: input.code,
+      message: input.message,
+      retryable: input.retryable ?? false,
+      trace_id: input.trace_id,
+      ...(input.details ? { details: input.details } : {})
+    }
+  };
+}
+
+export function errorCodeToHttpStatus(code: ErrorCode): number {
+  switch (code) {
+    case "INVALID_ARGUMENT":
+      return 400;
+    case "UNAUTHENTICATED":
+      return 401;
+    case "FORBIDDEN":
+      return 403;
+    case "NOT_FOUND":
+      return 404;
+    case "CONFLICT":
+      return 409;
+    case "RATE_LIMITED":
+      return 429;
+    case "UPSTREAM_FAILURE":
+      return 503;
+    case "INTERNAL":
+    default:
+      return 500;
+  }
+}

package/test/benchmark-assets.test.ts

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { RetrievalBenchmarkManifestSchema, RetrievalBenchmarkQuerySchema } from "../src/index.js";
+
+function loadJson(path: string): unknown {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function loadJsonl(path: string): unknown[] {
+  return readFileSync(path, "utf8")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => JSON.parse(line));
+}
+
+describe("benchmark assets", () => {
+  const root = process.cwd();
+  const benchmarkDir = join(root, "benchmarks");
+
+  it("validates benchmark manifest schema", () => {
+    const manifest = RetrievalBenchmarkManifestSchema.parse(loadJson(join(benchmarkDir, "repos.manifest.json")));
+    expect(manifest.repos.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it("validates benchmark query files and repo references", () => {
+    const manifest = RetrievalBenchmarkManifestSchema.parse(loadJson(join(benchmarkDir, "repos.manifest.json")));
+    const repoIds = new Set(manifest.repos.map((repo) => repo.id));
+
+    const splits = ["train", "dev", "test"] as const;
+    const allQueries = splits.flatMap((split) => {
+      const rows = loadJsonl(join(benchmarkDir, `queries.${split}.jsonl`));
+      return rows.map((row) => RetrievalBenchmarkQuerySchema.parse(row));
+    });
+
+    const seen = new Set<string>();
+    for (const query of allQueries) {
+      expect(repoIds.has(query.repo_id)).toBe(true);
+      expect(seen.has(query.id)).toBe(false);
+      seen.add(query.id);
+    }
+  });
+});

package/test/contracts.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import {
+  EnhancePromptInputSchema,
+  ErrorEnvelopeSchema,
+  RetrievalBenchmarkManifestSchema,
+  RetrievalBenchmarkQuerySchema,
+  SearchContextInputSchema,
+  SearchContextOutputSchema,
+  makeErrorEnvelope
+} from "../src/index.js";
+
+describe("contracts", () => {
+  it("applies search_context defaults", () => {
+    const parsed = SearchContextInputSchema.parse({
+      project_root_path: "/workspace/default",
+      query: "find auth guard"
+    });
+
+    expect(parsed.top_k).toBe(8);
+  });
+
+  it("rejects unknown search_context fields", () => {
+    const result = SearchContextInputSchema.safeParse({
+      project_root_path: "/workspace/default",
+      query: "find auth guard",
+      unexpected: true
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it("validates error envelope shape", () => {
+    const envelope = makeErrorEnvelope({
+      code: "INVALID_ARGUMENT",
+      message: "top_k must be between 1 and 20",
+      trace_id: "trc_123",
+      retryable: false,
+      details: { field: "top_k" }
+    });
+
+    expect(ErrorEnvelopeSchema.parse(envelope)).toEqual(envelope);
+  });
+
+  it("validates enhance_prompt schema", () => {
+    const parsed = EnhancePromptInputSchema.parse({
+      prompt: "Improve search ranking",
+      conversation_history: [{ role: "user", content: "Need better search" }]
+    });
+
+    expect(parsed.prompt).toContain("Improve");
+  });
+
+  it("validates search_context output schema", () => {
+    const output = {
+      trace_id: "trc_out",
+      results: [
+        {
+          path: "src/app.ts",
+          start_line: 1,
+          end_line: 2,
+          snippet: "const a = 1;",
+          score: 0.9,
+          reason: "semantic match"
+        }
+      ],
+      search_metadata: {
+        latency_ms: 7,
+        retrieval_mode: "hybrid",
+        index_version: "idx-1"
+      }
+    };
+
+    expect(SearchContextOutputSchema.parse(output)).toEqual(output);
+  });
+
+  it("validates retrieval benchmark manifest schema", () => {
+    const manifest = RetrievalBenchmarkManifestSchema.parse({
+      schema_version: "v1",
+      repos: [
+        {
+          id: "express",
+          git_url: "https://github.com/expressjs/express.git",
+          commit: "66404b347a1690c0b783f47a8cf04a37caea8de5",
+          split: "test"
+        }
+      ]
+    });
+    expect(manifest.repos).toHaveLength(1);
+  });
+
+  it("validates retrieval benchmark query schema", () => {
+    const query = RetrievalBenchmarkQuerySchema.parse({
+      id: "express-app-use",
+      repo_id: "express",
+      query: "where is app.use implemented",
+      expected_paths: ["lib/application.js"]
+    });
+    expect(query.tool).toBe("search_context");
+  });
+});

package/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": false,
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
+  },
+  "include": ["src/**/*.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}