shmakk 1.1.0 → 1.2.0

package/skills/architecture.md

@@ -0,0 +1,151 @@
+---
+name: architecture
+version: 1
+category: planning
+---
+
+# Software Architecture Analysis
+
+Analyze project structure, module relationships, dependencies, and architectural patterns.
+
+## When to use this skill
+
+- User wants to understand how a codebase is organized
+- User wants to find architectural problems (coupling, circular deps, bloated modules)
+- User wants to document or diagram the architecture
+- User wants advice on how to reorganize or improve structure
+- User mentions "architecture", "structure", "dependencies", "modules", "how does this connect"
+
+## Procedure
+
+### Step 1: Establish the landscape
+
+Start by reading the top-level directory and key config files:
+```
+list_dir(".")
+read_file("package.json")    # or pyproject.toml, Cargo.toml, go.mod, etc.
+read_file("README.md")
+```
+
+Identify: language, framework, package manager, entry points.
+
+### Step 2: Map the structure
+
+List and read each major directory:
+```
+list_dir("src/")
+list_dir("lib/")
+list_dir("app/")
+```
+
+For each significant module/file, identify:
+- What it exports (public API)
+- What it imports (dependencies)
+- What it's responsible for (single responsibility or mixed?)
+
+### Step 3: Identify imports/dependencies
+
+For JS/TS:
+```
+grep -r "^import\|^require" src/ --include="*.js" --include="*.ts" | head -100
+```
+
+For Python:
+```
+grep -r "^import\|^from" . --include="*.py" | grep -v __pycache__ | head -100
+```
+
+For Go:
+```
+grep -r "\"" --include="*.go" | grep import | head -100
+```
+
+### Step 4: Detect architectural patterns
+
+**Identify which pattern is in use:**
+- **Layered (N-tier)**: controllers → services → repositories → database
+- **Feature-based / vertical slices**: feature-a/ (with its own controller, service, model)
+- **Hexagonal / clean architecture**: domain/ + ports/ + adapters/
+- **Event-driven**: events/, handlers/, dispatchers/
+- **Monolith vs. modules vs. microservices**
+
+**Signs of architectural problems:**
+- Circular imports/dependencies: A imports B, B imports C, C imports A
+- God files: one file with 1000+ lines doing everything
+- Missing abstraction: business logic mixed into controllers or UI components
+- Tight coupling: deep import chains across layers that shouldn't know about each other
+- Inconsistent patterns: half the codebase using one pattern, half using another
+
+### Step 5: Check for circular dependencies
+
+For Node.js:
+```
+npx madge --circular src/
+```
+
+For Python:
+```
+pip show pydeps && pydeps module_name
+```
+
+Or manually trace: if module A imports B, search if B (or anything B imports) imports A.
+
+### Step 6: Assess module responsibilities
+
+For the 5-10 largest files, check if they're doing too much. A module should have one clear answer to: "what is this responsible for?"
+
+Signs of violation: a service file that also does HTTP routing, template rendering, and database migrations.
+
+## Output format
+
+```
+ARCHITECTURE ANALYSIS: my-project
+
+OVERVIEW
+Language: TypeScript (Node.js), React frontend
+Pattern: Layered architecture (controllers → services → repositories)
+Entry points: src/index.ts (API server), src/worker.ts (background jobs)
+
+STRUCTURE
+src/
+  api/         HTTP controllers — good separation
+  services/    Business logic — some mixing with persistence (see below)
+  db/          Database models and migrations
+  utils/       Shared utilities — well-contained
+  types/       Type definitions
+
+ISSUES
+
+⚠️  [HIGH] Circular dependency: auth/service.ts → users/service.ts → auth/middleware.ts → auth/service.ts
+   Resolution: Extract shared types to a separate module that neither imports from the other.
+
+⚠️  [MEDIUM] src/services/payment.ts is 847 lines and handles: Stripe integration, webhook parsing,
+   email notifications, and database writes. Should be split into:
+   - payment-gateway.ts (Stripe API)
+   - webhook-handler.ts
+   - payment-repository.ts
+
+ℹ️  [LOW] src/utils/ has grown to 23 files with no internal organization.
+   Consider grouping into: utils/string/, utils/date/, utils/crypto/
+
+STRENGTHS
+• Clear separation between API and service layers
+• Repository pattern consistently applied for database access
+• Type definitions centralized in types/
+
+RECOMMENDATIONS
+1. Break circular dependency in auth (blocks safe refactoring of either module)
+2. Split payment.ts into focused modules
+3. Organize utils/ directory
+```
+
+## Pitfalls
+
+- Don't redesign the entire architecture based on a read — focus on actual problems
+- Some coupling is intentional — understand the design before calling it wrong
+- Large files aren't always a problem — a well-organized 1000-line file may be fine
+- Framework conventions may explain patterns that look wrong in isolation (e.g. Rails fat models)
+
+## Verification
+
+After identifying issues: trace at least one import path manually to confirm it's a real circular dependency before reporting it.

package/skills/backend-adapter-aws-lambda.md

@@ -0,0 +1,204 @@
+---
+name: adapter-aws-lambda
+description: >
+  Deploy tRPC on AWS Lambda with awsLambdaRequestHandler() from
+  @trpc/server/adapters/aws-lambda for API Gateway v1 (REST, APIGatewayProxyEvent)
+  and v2 (HTTP, APIGatewayProxyEventV2), and Lambda Function URLs. Enable response
+  streaming with awsLambdaStreamingRequestHandler() wrapped in
+  awslambda.streamifyResponse(). CreateAWSLambdaContextOptions provides event and
+  context for context creation.
+type: core
+library: trpc
+library_version: '11.15.1'
+requires:
+  - server-setup
+sources:
+  - www/docs/server/adapters/aws-lambda.md
+  - examples/lambda-url/
+  - examples/lambda-api-gateway/
+category: backend
+---
+
+# tRPC — Adapter: AWS Lambda
+
+## Setup
+
+```ts
+// server.ts
+import { initTRPC } from '@trpc/server';
+import type { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
+import { awsLambdaRequestHandler } from '@trpc/server/adapters/aws-lambda';
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { z } from 'zod';
+
+const t = initTRPC.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 createContext = ({
+  event,
+  context,
+}: CreateAWSLambdaContextOptions<APIGatewayProxyEventV2>) => ({
+  event,
+  lambdaContext: context,
+});
+
+export const handler = awsLambdaRequestHandler({
+  router: appRouter,
+  createContext,
+});
+```
+
+## Core Patterns
+
+### API Gateway v1 (REST) handler
+
+```ts
+import type { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
+import { awsLambdaRequestHandler } from '@trpc/server/adapters/aws-lambda';
+import type { APIGatewayProxyEvent } from 'aws-lambda';
+import { appRouter } from './router';
+
+const createContext = ({
+  event,
+  context,
+}: CreateAWSLambdaContextOptions<APIGatewayProxyEvent>) => ({
+  user: event.requestContext.authorizer?.claims,
+});
+
+export const handler = awsLambdaRequestHandler({
+  router: appRouter,
+  createContext,
+});
+```
+
+Use `APIGatewayProxyEvent` for REST API (v1 payload format) and `APIGatewayProxyEventV2` for HTTP API (v2 payload format).
+
+### Response streaming with awsLambdaStreamingRequestHandler
+
+```ts
+/// <reference types="aws-lambda" />
+import type { CreateAWSLambdaContextOptions } from '@trpc/server/adapters/aws-lambda';
+import { awsLambdaStreamingRequestHandler } from '@trpc/server/adapters/aws-lambda';
+import type { APIGatewayProxyEventV2 } from 'aws-lambda';
+import { appRouter } from './router';
+
+const createContext = ({
+  event,
+  context,
+}: CreateAWSLambdaContextOptions<APIGatewayProxyEventV2>) => ({});
+
+export const handler = awslambda.streamifyResponse(
+  awsLambdaStreamingRequestHandler({
+    router: appRouter,
+    createContext,
+  }),
+);
+```
+
+Response streaming is supported for Lambda Function URLs and API Gateway REST APIs (with `responseTransferMode: STREAM`). The `awslambda` namespace is provided by the Lambda execution environment.
+
+### Streaming async generator procedure
+
+```ts
+import { initTRPC } from '@trpc/server';
+
+const t = initTRPC.create();
+
+export const appRouter = t.router({
+  countdown: t.procedure.query(async function* () {
+    for (let i = 10; i >= 0; i--) {
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      yield i;
+    }
+  }),
+});
+```
+
+Pair with `httpBatchStreamLink` on the client for streamed responses.
+
+### Limiting batch size with maxBatchSize
+
+```ts
+import { awsLambdaRequestHandler } from '@trpc/server/adapters/aws-lambda';
+import { appRouter } from './router';
+
+export const handler = awsLambdaRequestHandler({
+  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 Using httpBatchLink with per-procedure API Gateway resources
+
+Wrong:
+
+```ts
+// API Gateway has a separate resource for each procedure
+// e.g., /getUser, /createUser
+// Client uses:
+import { httpBatchLink } from '@trpc/client';
+
+httpBatchLink({ url: 'https://api.example.com' });
+// Batch request to /getUser,createUser → 404
+```
+
+Correct:
+
+```ts
+import { httpBatchLink, httpLink } from '@trpc/client';
+
+// Option A: Single catch-all resource (e.g., /{proxy+})
+httpBatchLink({ url: 'https://api.example.com' });
+
+// Option B: Per-procedure resources with httpLink (no batching)
+httpLink({ url: 'https://api.example.com' });
+```
+
+`httpBatchLink` sends multiple procedure names in the URL path (e.g., `getUser,createUser`). If API Gateway routes are per-procedure, the combined path does not match any resource and returns 404. Use a single catch-all resource or switch to `httpLink`.
+
+Source: www/docs/server/adapters/aws-lambda.md
+
+### HIGH Forgetting streamifyResponse wrapper for streaming
+
+Wrong:
+
+```ts
+export const handler = awsLambdaStreamingRequestHandler({
+  router: appRouter,
+  createContext,
+});
+```
+
+Correct:
+
+```ts
+export const handler = awslambda.streamifyResponse(
+  awsLambdaStreamingRequestHandler({
+    router: appRouter,
+    createContext,
+  }),
+);
+```
+
+`awsLambdaStreamingRequestHandler` requires wrapping with `awslambda.streamifyResponse()` to enable Lambda response streaming. Without it, Lambda treats the handler as a standard buffered response.
+
+Source: www/docs/server/adapters/aws-lambda.md
+
+## See Also
+
+- **server-setup** -- `initTRPC.create()`, router/procedure definition, context
+- **adapter-fetch** -- alternative for edge/serverless runtimes using Fetch API
+- **links** -- `httpBatchLink` vs `httpLink` for API Gateway routing considerations
+- AWS Lambda docs: https://docs.aws.amazon.com/lambda/latest/dg/welcome.html

package/skills/backend-adapter-express.md

@@ -0,0 +1,177 @@
+---
+name: adapter-express
+description: >
+  Mount tRPC as Express middleware with createExpressMiddleware() from
+  @trpc/server/adapters/express. Access Express req/res in createContext via
+  CreateExpressContextOptions. Mount at a path prefix like app.use('/trpc', ...).
+  Avoid global express.json() conflicting with tRPC body parsing for FormData.
+type: core
+library: trpc
+library_version: '11.15.1'
+requires:
+  - server-setup
+sources:
+  - www/docs/server/adapters/express.md
+  - examples/express-server/src/server.ts
+category: backend
+---
+
+# tRPC — Adapter: Express
+
+## Setup
+
+```ts
+// server.ts
+import { initTRPC } from '@trpc/server';
+import * as trpcExpress from '@trpc/server/adapters/express';
+import express from 'express';
+import { z } from 'zod';
+
+const createContext = ({
+  req,
+  res,
+}: trpcExpress.CreateExpressContextOptions) => {
+  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 app = express();
+
+app.use(
+  '/trpc',
+  trpcExpress.createExpressMiddleware({
+    router: appRouter,
+    createContext,
+  }),
+);
+
+app.listen(4000, () => {
+  console.log('Listening on http://localhost:4000');
+});
+```
+
+## Core Patterns
+
+### Accessing Express req/res in context
+
+```ts
+import * as trpcExpress from '@trpc/server/adapters/express';
+
+const createContext = ({
+  req,
+  res,
+}: trpcExpress.CreateExpressContextOptions) => {
+  const token = req.headers.authorization?.split(' ')[1];
+  return { token, res };
+};
+
+type Context = Awaited<ReturnType<typeof createContext>>;
+```
+
+`CreateExpressContextOptions` provides typed access to the Express `req` (IncomingMessage) and `res` (ServerResponse).
+
+### Adding tRPC alongside existing Express routes
+
+```ts
+import * as trpcExpress from '@trpc/server/adapters/express';
+import cors from 'cors';
+import express from 'express';
+import { createContext } from './context';
+import { appRouter } from './router';
+
+const app = express();
+
+app.use(cors());
+
+app.get('/health', (_req, res) => {
+  res.json({ status: 'ok' });
+});
+
+app.use(
+  '/trpc',
+  trpcExpress.createExpressMiddleware({
+    router: appRouter,
+    createContext,
+  }),
+);
+
+app.listen(4000);
+```
+
+### Limiting batch size with maxBatchSize
+
+```ts
+import * as trpcExpress from '@trpc/server/adapters/express';
+import express from 'express';
+import { createContext } from './context';
+import { appRouter } from './router';
+
+const app = express();
+
+app.use(
+  '/trpc',
+  trpcExpress.createExpressMiddleware({
+    router: appRouter,
+    createContext,
+    maxBatchSize: 10,
+  }),
+);
+
+app.listen(4000);
+```
+
+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 Global express.json() consuming tRPC request body
+
+Wrong:
+
+```ts
+const app = express();
+app.use(express.json()); // global body parser
+app.use(
+  '/trpc',
+  trpcExpress.createExpressMiddleware({
+    router: appRouter,
+    createContext,
+  }),
+);
+```
+
+Correct:
+
+```ts
+const app = express();
+// Only apply body parser to non-tRPC routes
+app.use('/api', express.json());
+app.use(
+  '/trpc',
+  trpcExpress.createExpressMiddleware({
+    router: appRouter,
+    createContext,
+  }),
+);
+```
+
+If `express.json()` is applied globally before the tRPC middleware, it consumes and parses the request body. tRPC then receives an already-parsed body, which breaks FormData and binary content type handling.
+
+Source: www/docs/server/non-json-content-types.md
+
+## See Also
+
+- **server-setup** -- `initTRPC.create()`, router/procedure definition, context
+- **adapter-standalone** -- simpler adapter when Express middleware ecosystem is not needed
+- **auth** -- extracting JWT from `req.headers.authorization` in context
+- Express docs: https://expressjs.com/en/guide/using-middleware.html