shmakk 1.1.0 → 1.2.0

package/skills/backend-adapter-fastify.md

@@ -0,0 +1,222 @@
+---
+name: adapter-fastify
+description: >
+  Mount tRPC as a Fastify plugin with fastifyTRPCPlugin from
+  @trpc/server/adapters/fastify. Configure prefix, trpcOptions (router,
+  createContext, onError). Enable WebSocket subscriptions with useWSS and
+  @fastify/websocket. Set routerOptions.maxParamLength for batch requests.
+  Requires Fastify v5+. FastifyTRPCPluginOptions for type-safe onError.
+  CreateFastifyContextOptions provides req, res.
+type: core
+library: trpc
+library_version: '11.15.1'
+requires:
+  - server-setup
+sources:
+  - www/docs/server/adapters/fastify.md
+  - examples/fastify-server/
+category: backend
+---
+
+# tRPC — Adapter: Fastify
+
+## Setup
+
+```ts
+// server.ts
+import { initTRPC } from '@trpc/server';
+import {
+  fastifyTRPCPlugin,
+  FastifyTRPCPluginOptions,
+} from '@trpc/server/adapters/fastify';
+import type { CreateFastifyContextOptions } from '@trpc/server/adapters/fastify';
+import fastify from 'fastify';
+import { z } from 'zod';
+
+function createContext({ req, res }: CreateFastifyContextOptions) {
+  return { req, res };
+}
+type Context = Awaited<ReturnType<typeof createContext>>;
+
+const t = initTRPC.context<Context>().create();
+
+const appRouter = t.router({
+  greet: t.procedure
+    .input(z.object({ name: z.string() }))
+    .query(({ input }) => ({ greeting: `Hello, ${input.name}!` })),
+});
+
+export type AppRouter = typeof appRouter;
+
+const server = fastify({
+  routerOptions: {
+    maxParamLength: 5000,
+  },
+});
+
+server.register(fastifyTRPCPlugin, {
+  prefix: '/trpc',
+  trpcOptions: {
+    router: appRouter,
+    createContext,
+    onError({ path, error }) {
+      console.error(`Error in tRPC handler on path '${path}':`, error);
+    },
+  } satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'],
+});
+
+(async () => {
+  try {
+    await server.listen({ port: 3000 });
+    console.log('Listening on http://localhost:3000');
+  } catch (err) {
+    server.log.error(err);
+    process.exit(1);
+  }
+})();
+```
+
+## Core Patterns
+
+### WebSocket subscriptions with @fastify/websocket
+
+```ts
+import ws from '@fastify/websocket';
+import {
+  fastifyTRPCPlugin,
+  FastifyTRPCPluginOptions,
+} from '@trpc/server/adapters/fastify';
+import fastify from 'fastify';
+import { createContext } from './context';
+import { appRouter, type AppRouter } from './router';
+
+const server = fastify({
+  routerOptions: { maxParamLength: 5000 },
+});
+
+// Register @fastify/websocket BEFORE the tRPC plugin
+server.register(ws);
+
+server.register(fastifyTRPCPlugin, {
+  prefix: '/trpc',
+  useWSS: true,
+  trpcOptions: {
+    router: appRouter,
+    createContext,
+    keepAlive: {
+      enabled: true,
+      pingMs: 30000,
+      pongWaitMs: 5000,
+    },
+  } satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'],
+});
+
+server.listen({ port: 3000 });
+```
+
+Install: `npm install @fastify/websocket` (minimum version 3.11.0)
+
+### Type-safe onError with satisfies
+
+```ts
+server.register(fastifyTRPCPlugin, {
+  prefix: '/trpc',
+  trpcOptions: {
+    router: appRouter,
+    createContext,
+    onError({ path, error, type, input }) {
+      console.error(`[${type}] ${path}:`, error.message);
+    },
+  } satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'],
+});
+```
+
+Due to Fastify plugin type inference limitations, use `satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions']` to get correct types on `onError` and other callbacks.
+
+### Limiting batch size with maxBatchSize
+
+```ts
+server.register(fastifyTRPCPlugin, {
+  prefix: '/trpc',
+  trpcOptions: {
+    router: appRouter,
+    createContext,
+    maxBatchSize: 10,
+  } satisfies FastifyTRPCPluginOptions<AppRouter>['trpcOptions'],
+});
+```
+
+Requests batching more than `maxBatchSize` operations are rejected with a `400 Bad Request` error. Set `maxItems` on your client's `httpBatchLink` to the same value to avoid exceeding the limit.
+
+## Common Mistakes
+
+### HIGH Registering @fastify/websocket after tRPC plugin
+
+Wrong:
+
+```ts
+server.register(fastifyTRPCPlugin, {
+  useWSS: true,
+  trpcOptions: { router: appRouter, createContext },
+});
+server.register(ws); // too late!
+```
+
+Correct:
+
+```ts
+server.register(ws); // register FIRST
+server.register(fastifyTRPCPlugin, {
+  useWSS: true,
+  trpcOptions: { router: appRouter, createContext },
+});
+```
+
+The WebSocket plugin must be registered before the tRPC plugin. Reverse order causes WebSocket routes to not be recognized.
+
+Source: www/docs/server/adapters/fastify.md
+
+### HIGH Missing maxParamLength for batch requests
+
+Wrong:
+
+```ts
+const server = fastify();
+```
+
+Correct:
+
+```ts
+const server = fastify({
+  routerOptions: { maxParamLength: 5000 },
+});
+```
+
+Fastify defaults to `maxParamLength: 100`. Batch requests from `httpBatchLink` encode multiple procedure names in the URL path parameter, which easily exceeds 100 characters and returns a 404.
+
+Source: www/docs/server/adapters/fastify.md
+
+### CRITICAL Using Fastify v4 with tRPC v11
+
+Wrong:
+
+```json
+{ "dependencies": { "fastify": "^4.0.0" } }
+```
+
+Correct:
+
+```json
+{ "dependencies": { "fastify": "^5.0.0" } }
+```
+
+tRPC v11 requires Fastify v5+. Fastify v4 may return empty responses without errors due to incompatible response handling.
+
+Source: www/docs/server/adapters/fastify.md
+
+## See Also
+
+- **server-setup** -- `initTRPC.create()`, router/procedure definition, context
+- **subscriptions** -- async generator subscriptions, `tracked()`, `keepAlive`
+- **adapter-standalone** -- simpler adapter when Fastify features are not needed
+- Fastify docs: https://fastify.dev/docs/latest/

package/skills/backend-adapter-fetch.md

@@ -0,0 +1,200 @@
+---
+name: adapter-fetch
+description: >
+  Deploy tRPC on WinterCG-compliant edge runtimes with fetchRequestHandler() from
+  @trpc/server/adapters/fetch. Supports Cloudflare Workers, Deno Deploy, Vercel
+  Edge Runtime, Astro, Remix, SolidStart. FetchCreateContextFnOptions provides
+  req (Request) and resHeaders (Headers) for context creation. The endpoint option
+  must match the URL path prefix where the handler is mounted.
+type: core
+library: trpc
+library_version: '11.15.1'
+requires:
+  - server-setup
+sources:
+  - www/docs/server/adapters/fetch.mdx
+  - examples/cloudflare-workers/
+  - examples/deno-deploy/
+category: backend
+---
+
+# tRPC — Adapter: Fetch / Edge Runtimes
+
+## Setup
+
+```ts
+// Cloudflare Worker example
+import { initTRPC } from '@trpc/server';
+import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
+import type { FetchCreateContextFnOptions } from '@trpc/server/adapters/fetch';
+import { z } from 'zod';
+
+function createContext({ req, resHeaders }: FetchCreateContextFnOptions) {
+  const user = req.headers.get('authorization');
+  return { user, resHeaders };
+}
+type Context = Awaited<ReturnType<typeof createContext>>;
+
+const t = initTRPC.context<Context>().create();
+
+const appRouter = t.router({
+  greet: t.procedure
+    .input(z.object({ name: z.string() }))
+    .query(({ input }) => ({ greeting: `Hello, ${input.name}!` })),
+});
+
+export type AppRouter = typeof appRouter;
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    return fetchRequestHandler({
+      endpoint: '/trpc',
+      req: request,
+      router: appRouter,
+      createContext,
+    });
+  },
+};
+```
+
+## Core Patterns
+
+### Cloudflare Workers
+
+```ts
+import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
+import { createContext } from './context';
+import { appRouter } from './router';
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    return fetchRequestHandler({
+      endpoint: '/trpc',
+      req: request,
+      router: appRouter,
+      createContext,
+    });
+  },
+};
+```
+
+### Astro SSR
+
+```ts
+// src/pages/trpc/[trpc].ts
+import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
+import type { APIRoute } from 'astro';
+import { createContext } from '../../server/context';
+import { appRouter } from '../../server/router';
+
+export const ALL: APIRoute = (opts) => {
+  return fetchRequestHandler({
+    endpoint: '/trpc',
+    req: opts.request,
+    router: appRouter,
+    createContext,
+  });
+};
+```
+
+### Remix
+
+```ts
+// app/routes/trpc.$trpc.ts
+import type { ActionFunctionArgs, LoaderFunctionArgs } from '@remix-run/node';
+import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
+import { createContext } from '~/server/context';
+import { appRouter } from '~/server/router';
+
+function handleRequest(args: LoaderFunctionArgs | ActionFunctionArgs) {
+  return fetchRequestHandler({
+    endpoint: '/trpc',
+    req: args.request,
+    router: appRouter,
+    createContext,
+  });
+}
+
+export const loader = async (args: LoaderFunctionArgs) => handleRequest(args);
+export const action = async (args: ActionFunctionArgs) => handleRequest(args);
+```
+
+### Deno Deploy
+
+```ts
+import { fetchRequestHandler } from 'npm:@trpc/server/adapters/fetch';
+import { createContext } from './context.ts';
+import { appRouter } from './router.ts';
+
+Deno.serve((request) => {
+  return fetchRequestHandler({
+    endpoint: '/trpc',
+    req: request,
+    router: appRouter,
+    createContext,
+  });
+});
+```
+
+### Limiting batch size with maxBatchSize
+
+```ts
+import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
+import { createContext } from './context';
+import { appRouter } from './router';
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    return fetchRequestHandler({
+      endpoint: '/trpc',
+      req: request,
+      router: appRouter,
+      createContext,
+      maxBatchSize: 10,
+    });
+  },
+};
+```
+
+Requests batching more than `maxBatchSize` operations are rejected with a `400 Bad Request` error. Set `maxItems` on your client's `httpBatchLink` to the same value to avoid exceeding the limit.
+
+## Common Mistakes
+
+### HIGH Mismatched endpoint path in fetchRequestHandler
+
+Wrong:
+
+```ts
+// Handler mounted at /api/trpc/[trpc] but endpoint says /trpc
+fetchRequestHandler({
+  endpoint: '/trpc',
+  req: request,
+  router: appRouter,
+  createContext,
+});
+```
+
+Correct:
+
+```ts
+// endpoint must match the actual URL path prefix
+fetchRequestHandler({
+  endpoint: '/api/trpc',
+  req: request,
+  router: appRouter,
+  createContext,
+});
+```
+
+The `endpoint` option tells tRPC where to strip the URL prefix to extract the procedure name. If it does not match the actual mount path, all procedures return 404 because the path parsing extracts the wrong procedure name.
+
+Source: www/docs/server/adapters/fetch.mdx
+
+## See Also
+
+- **server-setup** -- `initTRPC.create()`, router/procedure definition, context
+- **adapter-standalone** -- alternative for Node.js HTTP server
+- **adapter-express** -- alternative when Express middleware ecosystem is needed
+- **adapter-aws-lambda** -- alternative for AWS Lambda deployments
+- Cloudflare Workers docs: https://developers.cloudflare.com/workers/
+- Deno Deploy docs: https://deno.com/deploy/docs

package/skills/backend-api-docs.md

@@ -0,0 +1,22 @@
+---
+name: api-docs
+description: Generate API documentation from source code with JSDoc and OpenAPI support
+argument-hint: "<source-path>"
+allowed-tools: Bash(npx *) mcp__claude-flow__hooks_worker-dispatch Read Write Grep
+category: backend
+---
+Generate API documentation from TypeScript/JavaScript source:
+
+1. **Scan exports**: Find all public functions, classes, and interfaces
+2. **Extract JSDoc**: Parse `@param`, `@returns`, `@throws`, `@example` annotations
+3. **Generate missing docs**: Add JSDoc for undocumented public APIs
+4. **OpenAPI spec**: For HTTP endpoints, generate OpenAPI 3.0 definitions
+
+Dispatch via MCP: `mcp__claude-flow__hooks_worker-dispatch({ trigger: "document", scope: "api" })`
+
+Conventions:
+- Every public export must have a JSDoc comment
+- Include `@param` with type and description
+- Include `@returns` with type and description
+- Include `@throws` for known error conditions
+- Include `@example` for non-obvious usage

package/skills/backend-aspire.md

@@ -0,0 +1,232 @@
+---
+name: aspire
+description: 'Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, GitHub Codespaces, templates, dashboard, and deployment. Use when the user asks to create, run, debug, configure, deploy, or troubleshoot an Aspire distributed application.'
+category: backend
+---
+
+# Aspire — Polyglot Distributed-App Orchestration
+
+Aspire is a **code-first, polyglot toolchain** for building observable, production-ready distributed applications. It orchestrates containers, executables, and cloud resources from a single AppHost project — regardless of whether the workloads are C#, Python, JavaScript/TypeScript, Go, Java, Rust, Bun, Deno, or PowerShell.
+
+> **Mental model:** The AppHost is a *conductor* — it doesn't play the instruments, it tells every service when to start, how to find each other, and watches for problems.
+
+Detailed reference material lives in the `references/` folder — load on demand.
+
+---
+
+## References
+
+| Reference | When to load |
+|---|---|
+| [CLI Reference](references/cli-reference.md) | Command flags, options, or detailed usage |
+| [MCP Server](references/mcp-server.md) | Setting up MCP for AI assistants, available tools |
+| [Integrations Catalog](references/integrations-catalog.md) | Discovering integrations via MCP tools, wiring patterns |
+| [Polyglot APIs](references/polyglot-apis.md) | Method signatures, chaining options, language-specific patterns |
+| [Architecture](references/architecture.md) | DCP internals, resource model, service discovery, networking, telemetry |
+| [Dashboard](references/dashboard.md) | Dashboard features, standalone mode, GenAI Visualizer |
+| [Deployment](references/deployment.md) | Docker, Kubernetes, Azure Container Apps, App Service |
+| [Testing](references/testing.md) | Integration tests against the AppHost |
+| [Troubleshooting](references/troubleshooting.md) | Diagnostic codes, common errors, and fixes |
+
+---
+
+## 1. Researching Aspire Documentation
+
+The Aspire team ships an **MCP server** that provides documentation tools directly inside your AI assistant. See [MCP Server](references/mcp-server.md) for setup details.
+
+### Aspire CLI 13.2+ (recommended — has built-in docs search)
+
+If running Aspire CLI **13.2 or later** (`aspire --version`), the MCP server includes docs search tools:
+
+| Tool | Description |
+|---|---|
+| `list_docs` | Lists all available documentation from aspire.dev |
+| `search_docs` | Performs weighted lexical search across indexed documentation |
+| `get_doc` | Retrieves a specific document by its slug |
+
+These tools were added in [PR #14028](https://github.com/dotnet/aspire/pull/14028). To update: `aspire update --self --channel daily`.
+
+For more on this approach, see David Pine's post: https://davidpine.dev/posts/aspire-docs-mcp-tools/
+
+### Aspire CLI 13.1 (integration tools only)
+
+On 13.1, the MCP server provides integration lookup but **not** docs search:
+
+| Tool | Description |
+|---|---|
+| `list_integrations` | Lists available Aspire hosting integrations |
+| `get_integration_docs` | Gets documentation for a specific integration package |
+
+For general docs queries on 13.1, use **Context7** as your primary source (see below).
+
+### Fallback: Context7
+
+Use **Context7** (`mcp_context7`) when the Aspire MCP docs tools are unavailable (13.1) or the MCP server isn't running:
+
+**Step 1 — Resolve the library ID** (one-time per session):
+
+Call `mcp_context7_resolve-library-id` with `libraryName: ".NET Aspire"`.
+
+| Rank | Library ID | Use when |
+|---|---|---|
+| 1 | `/microsoft/aspire.dev` | Primary source. Guides, integrations, CLI reference, deployment. |
+| 2 | `/dotnet/aspire` | API internals, source-level implementation details. |
+| 3 | `/communitytoolkit/aspire` | Non-Microsoft polyglot integrations (Go, Java, Node.js, Ollama). |
+
+**Step 2 — Query docs:**
+
+```
+libraryId: "/microsoft/aspire.dev", query: "Python integration AddPythonApp service discovery"
+libraryId: "/communitytoolkit/aspire", query: "Golang Java Node.js community integrations"
+```
+
+### Fallback: GitHub search (when Context7 is also unavailable)
+
+Search the official docs repo on GitHub:
+- **Docs repo:** `microsoft/aspire.dev` — path: `src/frontend/src/content/docs/`
+- **Source repo:** `dotnet/aspire`
+- **Samples repo:** `dotnet/aspire-samples`
+- **Community integrations:** `CommunityToolkit/Aspire`
+
+---
+
+## 2. Prerequisites & Install
+
+| Requirement | Details |
+|---|---|
+| **.NET SDK** | 10.0+ (required even for non-.NET workloads — the AppHost is .NET) |
+| **Container runtime** | Docker Desktop, Podman, or Rancher Desktop |
+| **IDE (optional)** | VS Code + C# Dev Kit, Visual Studio 2022, JetBrains Rider |
+
+```bash
+# Linux / macOS
+curl -sSL https://aspire.dev/install.sh | bash
+
+# Windows PowerShell
+irm https://aspire.dev/install.ps1 | iex
+
+# Verify
+aspire --version
+
+# Install templates
+dotnet new install Aspire.ProjectTemplates
+```
+
+---
+
+## 3. Project Templates
+
+| Template | Command | Description |
+|---|---|---|
+| **aspire-starter** | `aspire new aspire-starter` | ASP.NET Core/Blazor starter + AppHost + tests |
+| **aspire-ts-cs-starter** | `aspire new aspire-ts-cs-starter` | ASP.NET Core/React starter + AppHost |
+| **aspire-py-starter** | `aspire new aspire-py-starter` | FastAPI/React starter + AppHost |
+| **aspire-apphost-singlefile** | `aspire new aspire-apphost-singlefile` | Empty single-file AppHost |
+
+---
+
+## 4. AppHost Quick Start (Polyglot)
+
+The AppHost orchestrates all services. Non-.NET workloads run as containers or executables.
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+// Infrastructure
+var redis = builder.AddRedis("cache");
+var postgres = builder.AddPostgres("pg").AddDatabase("catalog");
+
+// .NET API
+var api = builder.AddProject<Projects.CatalogApi>("api")
+    .WithReference(postgres).WithReference(redis);
+
+// Python ML service
+var ml = builder.AddPythonApp("ml-service", "../ml-service", "main.py")
+    .WithHttpEndpoint(targetPort: 8000).WithReference(redis);
+
+// React frontend (Vite)
+var web = builder.AddViteApp("web", "../frontend")
+    .WithHttpEndpoint(targetPort: 5173).WithReference(api);
+
+// Go worker
+var worker = builder.AddGolangApp("worker", "../go-worker")
+    .WithReference(redis);
+
+builder.Build().Run();
+```
+
+For complete API signatures, see [Polyglot APIs](references/polyglot-apis.md).
+
+---
+
+## 5. Core Concepts (Summary)
+
+| Concept | Key point |
+|---|---|
+| **Run vs Publish** | `aspire run` = local dev (DCP engine). `aspire publish` = generate deployment manifests. |
+| **Service discovery** | Automatic via env vars: `ConnectionStrings__<name>`, `services__<name>__http__0` |
+| **Resource lifecycle** | DAG ordering — dependencies start first. `.WaitFor()` gates on health checks. |
+| **Resource types** | `ProjectResource`, `ContainerResource`, `ExecutableResource`, `ParameterResource` |
+| **Integrations** | 144+ across 13 categories. Hosting package (AppHost) + Client package (service). |
+| **Dashboard** | Real-time logs, traces, metrics, GenAI visualizer. Runs automatically with `aspire run`. |
+| **MCP Server** | AI assistants can query running apps and search docs via CLI (STDIO). |
+| **Testing** | `Aspire.Hosting.Testing` — spin up full AppHost in xUnit/MSTest/NUnit. |
+| **Deployment** | Docker, Kubernetes, Azure Container Apps, Azure App Service. |
+
+---
+
+## 6. CLI Quick Reference
+
+Valid commands in Aspire CLI 13.1:
+
+| Command | Description | Status |
+|---|---|---|
+| `aspire new <template>` | Create from template | Stable |
+| `aspire init` | Initialize in existing project | Stable |
+| `aspire run` | Start all resources locally | Stable |
+| `aspire add <integration>` | Add an integration | Stable |
+| `aspire publish` | Generate deployment manifests | Preview |
+| `aspire config` | Manage configuration settings | Stable |
+| `aspire cache` | Manage disk cache | Stable |
+| `aspire deploy` | Deploy to defined targets | Preview |
+| `aspire do <step>` | Execute a pipeline step | Preview |
+| `aspire update` | Update integrations (or `--self` for CLI) | Preview |
+| `aspire mcp init` | Configure MCP for AI assistants | Stable |
+| `aspire mcp start` | Start the MCP server | Stable |
+
+Full command reference with flags: [CLI Reference](references/cli-reference.md).
+
+---
+
+## 7. Common Patterns
+
+### Adding a new service
+
+1. Create your service directory (any language)
+2. Add to AppHost: `Add*App()` or `AddProject<T>()`
+3. Wire dependencies: `.WithReference()`
+4. Gate on health: `.WaitFor()` if needed
+5. Run: `aspire run`
+
+### Migrating from Docker Compose
+
+1. `aspire new aspire-apphost-singlefile` (empty AppHost)
+2. Replace each `docker-compose` service with an Aspire resource
+3. `depends_on` → `.WithReference()` + `.WaitFor()`
+4. `ports` → `.WithHttpEndpoint()`
+5. `environment` → `.WithEnvironment()` or `.WithReference()`
+
+---
+
+## 8. Key URLs
+
+| Resource | URL |
+|---|---|
+| **Documentation** | https://aspire.dev |
+| **Runtime repo** | https://github.com/dotnet/aspire |
+| **Docs repo** | https://github.com/microsoft/aspire.dev |
+| **Samples** | https://github.com/dotnet/aspire-samples |
+| **Community Toolkit** | https://github.com/CommunityToolkit/Aspire |
+| **Dashboard image** | `mcr.microsoft.com/dotnet/aspire-dashboard` |
+| **Discord** | https://aka.ms/aspire/discord |
+| **Reddit** | https://www.reddit.com/r/aspiredotdev/ |