MCP: Sync Templates & Documentation from Rust Version (#3943)

## Summary

## Changes

### Template Files (Synchronized with Rust Version)

- **`lib/templates/trpc/CLAUDE.md`** - AI assistant guidance for the
tRPC template
  - Testing guidelines with Node.js test runner
  - Databricks type handling and best practices
  - Frontend styling guidelines with Tailwind CSS
  - Data visualization patterns with Recharts

- **`lib/templates/trpc/server/src/server.test.ts`** - Enhanced test
structure
  - Basic server healthcheck test
  - Commented examples for testing tRPC procedures directly
  - Proper environment variable setup

- **`lib/templates/trpc/server/src/databricks.ts`** - Improved
Databricks client
  - Better documentation and usage examples
  - Added `mapRows` helper utility for manual row mapping
  - Proper Zod schema validation patterns

## Testing

- ✅ All Go tests pass
- ✅ Template files verified to match Rust version
- ✅ Documentation reviewed for accuracy and completeness

## Related

- Implements Phase 5 from `docs/porting-plan/phase-5-templates-docs.md`
- Template files synchronized with
`/Users/fabian.jakobs/Workspaces/agent/edda/edda_templates/template_trpc/`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[email protected]>

Author: fjakobs

experimental/apps-mcp/lib/templates/trpc/CLAUDE.md

@@ -14,12 +14,39 @@ import { strict as assert } from "node:assert";
 
 ## Databricks Type Handling:
 
+- **executeQuery REQUIRES Zod schema**: Pass the Zod schema object as second parameter, NOT a TypeScript type annotation
+  ```typescript
+  // ❌ WRONG - Do NOT use generic type parameter
+  const result = await client.executeQuery<MyType>(sql);
+
+  // ✅ CORRECT - Pass Zod schema as parameter
+  const mySchema = z.object({ id: z.number(), name: z.string() });
+  const result = await client.executeQuery(sql, mySchema);
+  ```
 - **QueryResult access**: `executeQuery()` returns `{rows: T[], rowCount: number}`. Always use `.rows` property: `const {rows} = await client.executeQuery(...)` or `result.rows.map(...)`
 - **Type imports**: Use `import type { T }` (not `import { T }`) when `verbatimModuleSyntax` is enabled
 - **Column access**: Use bracket notation `row['column_name']` (TypeScript strict mode requirement)
 - **DATE/TIMESTAMP columns**: Databricks returns Date objects. Use `z.coerce.date()` in schemas (never `z.string()` for dates)
 - **Dynamic properties**: Cast explicitly `row['order_id'] as number`
 
+### Helper Utilities:
+
+**mapRows<T>(rows, schema)** - Validates and maps raw SQL rows using Zod schema:
+```typescript
+import { mapRows } from './databricks';
+
+// When you have raw rows and need manual mapping
+const rawRows = [{id: 1, name: "Alice"}, {id: 2, name: "Bob"}];
+const userSchema = z.object({ id: z.number(), name: z.string() });
+const users = mapRows(rawRows, userSchema);
+// users is now typed as { id: number; name: string }[]
+```
+
+Use this when:
+- Processing nested query results
+- Manually mapping row data before returning from tRPC
+- Need to validate data from non-Databricks sources
+
 ## Frontend Styling Guidelines:
 
 ### Component Structure Pattern:

experimental/apps-mcp/lib/templates/trpc/server/src/databricks.ts

@@ -5,12 +5,18 @@
 //   const myTableSchema = z.object({
 //     id: z.number(),
 //     name: z.string(),
-//     created_at: z.string(),
+//     created_at: z.coerce.date(),
 //   });
 //
 //   const client = new DatabricksClient();
+//
+//   // ✅ CORRECT - Pass Zod schema (not TypeScript type)
 //   const result = await client.executeQuery("SELECT * FROM my_table", myTableSchema);
-//   // result.rows is now validated and typed as MyTable[]
+//   // result.rows is now validated and typed as z.infer<typeof myTableSchema>[]
+//
+//   // ❌ WRONG - Do NOT use generic type parameter alone
+//   // const result = await client.executeQuery<MyType>("SELECT ...");
+//   // This will cause runtime errors!
 
 import { DBSQLClient } from "@databricks/sql";
 import type { ConnectionOptions } from "@databricks/sql/dist/contracts/IDBSQLClient";
@@ -75,9 +81,21 @@ export class DatabricksClient {
     }
   }
 
-  async executeQuery<T extends z.ZodTypeAny = typeof defaultRowSchema>(
+  /**
+   * Execute a SQL query against Databricks and validate results with Zod schema.
+   *
+   * @param sql - SQL query string
+   * @param schema - Zod schema for row validation (REQUIRED - pass the schema, not a TypeScript type)
+   * @returns QueryResult with validated and typed rows
+   *
+   * @example
+   * const schema = z.object({ id: z.number(), name: z.string() });
+   * const result = await client.executeQuery("SELECT id, name FROM users", schema);
+   * // result.rows is typed as { id: number; name: string }[]
+   */
+  async executeQuery<T extends z.ZodTypeAny>(
     sql: string,
-    schema?: T,
+    schema: T,
   ): Promise<QueryResult<z.infer<T>>> {
     try {
       const client = new DBSQLClient();
@@ -92,8 +110,8 @@ export class DatabricksClient {
       await session.close();
       await connection.close();
 
-      // Apply schema validation if provided
-      const rows = schema ? result.map((row) => schema.parse(row)) : result;
+      // Apply schema validation
+      const rows = result.map((row) => schema.parse(row));
       return { rows: rows as z.infer<T>[], rowCount: rows.length };
     } catch (error) {
       console.error("Databricks SQL query error:", error);
@@ -106,3 +124,21 @@ export class DatabricksClient {
     }
   }
 }
+
+/**
+ * Helper utility to map and validate raw SQL rows using a Zod schema.
+ * Useful when you have raw rows from nested queries or need manual mapping.
+ *
+ * @param rows - Array of raw SQL rows (Record<string, SqlValue>)
+ * @param schema - Zod schema for validation
+ * @returns Array of validated and typed objects
+ *
+ * @example
+ * const rawRows = [{id: 1, name: "Alice"}, {id: 2, name: "Bob"}];
+ * const schema = z.object({ id: z.number(), name: z.string() });
+ * const users = mapRows(rawRows, schema);
+ * // users is typed as { id: number; name: string }[]
+ */
+export function mapRows<T>(rows: SqlRow[], schema: z.ZodSchema<T>): T[] {
+  return rows.map((row) => schema.parse(row));
+}

experimental/apps-mcp/lib/templates/trpc/server/src/server.test.ts

@@ -6,6 +6,8 @@ import type { Server } from "node:http";
 process.env["DATABRICKS_HOST"] =
   process.env["DATABRICKS_HOST"] || "https://dummy.databricks.com";
 process.env["DATABRICKS_TOKEN"] = process.env["DATABRICKS_TOKEN"] || "dummy_token";
+process.env["DATABRICKS_WAREHOUSE_ID"] =
+  process.env["DATABRICKS_WAREHOUSE_ID"] || "dummy_warehouse_id";
 
 test("server starts and responds to healthcheck", async () => {
   // dynamic import to ensure env vars are set first
@@ -34,3 +36,37 @@ test("server starts and responds to healthcheck", async () => {
     }
   }
 });
+
+// Example: Testing tRPC procedures directly without HTTP server
+// This is faster and simpler for most tests
+//
+// test("getUsers returns array of users", async () => {
+//   const { appRouter } = await import("./index");
+//   const { initTRPC } = await import("@trpc/server");
+//
+//   // create tRPC caller - no HTTP server needed
+//   const t = initTRPC.create();
+//   const caller = t.createCallerFactory(appRouter)({});
+//
+//   const result = await caller.getUsers();
+//
+//   // validate structure
+//   assert.ok(Array.isArray(result));
+//   if (result.length > 0) {
+//     assert.ok(result[0].id);
+//     assert.ok(result[0].name);
+//   }
+// });
+//
+// test("getMetrics with input parameter", async () => {
+//   const { appRouter } = await import("./index");
+//   const { initTRPC } = await import("@trpc/server");
+//
+//   const t = initTRPC.create();
+//   const caller = t.createCallerFactory(appRouter)({});
+//
+//   const result = await caller.getMetrics({ category: "sales" });
+//
+//   assert.ok(Array.isArray(result));
+//   // add assertions for your expected data structure
+// });