teamshare-bridge 0.3.0 → 0.4.0

package/dist/lib/scaffold/verify.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyScaffold = verifyScaffold;
+/**
+ * Scaffold verification — runs build/typecheck on the scaffolded project.
+ */
+const node_child_process_1 = require("node:child_process");
+function verifyScaffold(rootPath, type) {
+    const steps = [];
+    // Install dependencies
+    steps.push(runStep(rootPath, 'npm install', 'install'));
+    // Type-specific verification
+    if (type === 'web' || type === 'full') {
+        steps.push(runStep(rootPath, 'npm run build', 'next-build'));
+    }
+    if (type === 'backend' || type === 'full') {
+        steps.push(runStep(rootPath, 'npx prisma generate', 'prisma-generate'));
+        steps.push(runStep(rootPath, 'npm run build', 'nest-build'));
+    }
+    if (type === 'mobile') {
+        steps.push(runStep(rootPath, 'npx expo export --dump-sourcemap', 'expo-export'));
+    }
+    return {
+        passed: steps.every((s) => s.passed),
+        steps,
+    };
+}
+function runStep(cwd, command, name) {
+    try {
+        (0, node_child_process_1.execSync)(command, {
+            cwd,
+            timeout: 120_000,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, CI: 'true' },
+        });
+        return { name, passed: true };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            name,
+            passed: false,
+            error: (e.stderr ?? e.message ?? 'Unknown error').slice(0, 1000),
+        };
+    }
+}
+//# sourceMappingURL=verify.js.map

package/dist/lib/scaffold/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../src/lib/scaffold/verify.ts"],"names":[],"mappings":";;AAUA,wCAsBC;AAhCD;;GAEG;AACH,2DAA8C;AAO9C,SAAgB,cAAc,CAAC,QAAgB,EAAE,IAAY;IAC3D,MAAM,KAAK,GAAwD,EAAE,CAAC;IAEtE,uBAAuB;IACvB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC,CAAC;IAExD,6BAA6B;IAC7B,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,qBAAqB,EAAE,iBAAiB,CAAC,CAAC,CAAC;QACxE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,kCAAkC,EAAE,aAAa,CAAC,CAAC,CAAC;IACnF,CAAC;IAED,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;QACpC,KAAK;KACN,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,GAAW,EAAE,OAAe,EAAE,IAAY;IACzD,IAAI,CAAC;QACH,IAAA,6BAAQ,EAAC,OAAO,EAAE;YAChB,GAAG;YACH,OAAO,EAAE,OAAO;YAChB,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;YAC/B,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE;SACpC,CAAC,CAAC;QACH,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAChC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,GAA4C,CAAC;QACvD,OAAO;YACL,IAAI;YACJ,MAAM,EAAE,KAAK;YACb,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,IAAI,eAAe,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC;SACjE,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/lib/skills.d.ts

@@ -1,5 +1,5 @@
-/** The four skills shipped with the bridge (source of truth: ./skills). */
-export declare const SHIPPED_SKILLS: readonly ["teamshare-cdd", "teamshare-modularity", "teamshare-auth-rbac", "teamshare-orchestrator-ask"];
+/** The five skills shipped with the bridge (source of truth: ./skills). */
+export declare const SHIPPED_SKILLS: readonly ["teamshare-cdd", "teamshare-modularity", "teamshare-auth-rbac", "teamshare-orchestrator-ask", "teamshare-scaffold"];
 /** Source: <package>/skills (ships in the npm tarball via package.json files). */
 export declare function skillsSourceDir(): string;
 /** Target: ~/.agents/skills (opencode convention) unless overridden. */

package/dist/lib/skills.js

@@ -16,12 +16,13 @@ exports.uninstallSkills = uninstallSkills;
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
-/** The four skills shipped with the bridge (source of truth: ./skills). */
+/** The five skills shipped with the bridge (source of truth: ./skills). */
 exports.SHIPPED_SKILLS = [
     'teamshare-cdd',
     'teamshare-modularity',
     'teamshare-auth-rbac',
     'teamshare-orchestrator-ask',
+    'teamshare-scaffold',
 ];
 /** Source: <package>/skills (ships in the npm tarball via package.json files). */
 function skillsSourceDir() {

package/dist/lib/skills.js.map

@@ -1 +1 @@
-{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/lib/skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/lib/skills.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
-{
+{
   "name": "teamshare-bridge",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Local bridge for TeamShare agents - CLI session runner, auto-wake WebSocket daemon, and teamshare:// protocol handler.",
   "type": "commonjs",
   "license": "MIT",
@@ -19,6 +19,7 @@
   "files": [
     "dist",
     "skills",
+    "templates",
     "tools",
     "README.md"
   ],

package/skills/teamshare-orchestrator-ask/SKILL.md

@@ -61,3 +61,17 @@ Humans can answer from two places:
 2. **#agent-questions chat**: answer in the project's agent-questions channel
 
 Both surfaces trigger the same `question.answered` wake event.
+
+## Merge conflicts (IMP-810)
+
+When two agents edit the same file and their branches conflict during merge:
+1. The orchestrator blocks the task (`status: 'blocked'`, `workerStatus: 'blocked'`)
+2. A `[question]` comment is posted on the linked task listing the conflicting files
+3. The OT transitions to `question_pending`
+4. A human resolves the conflicts (manually or by telling an agent what to do)
+5. When the question is answered, the OT requeues and the worker retries
+
+If you are the worker agent and see a merge conflict:
+- Do NOT force-push or overwrite the integration branch
+- Wait for the human to resolve or give you instructions
+- When re-dispatched, pull the latest integration branch and re-apply your changes

package/skills/teamshare-scaffold/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: teamshare-scaffold
+description: "Enforce TeamShare standards when scaffolding new codebases, auditing existing ones, or cleaning up code. Covers stack decisions, folder layouts, view recipes, RBAC guards, loading states, safety patterns (no lint-disable unless worse), and the audit report format."
+---
+
+# teamshare-scaffold
+
+Standards enforcement for TeamShare codebases. Use when scaffolding a new repo, auditing an existing codebase, or cleaning up code.
+
+## Stack Decisions
+
+| Layer | Stack |
+|-------|-------|
+| Web | Next.js App Router + TS + Tailwind v4 + shadcn (radix-nova) + TS* wrappers |
+| Icons | iconsax-react (variant+color always, no emoji) |
+| Tables | @tanstack/react-table v8 (NOT v9) |
+| Forms | TSForm + zodResolver + zod schemas mirroring backend |
+| State | useListState + useUrlTab (URL-driven) |
+| Backend | NestJS 11 + Prisma 6 + zod-first DTOs + envelope |
+| Mobile | Expo SDK 57 + NativeWind v4 + reusables |
+
+## Frontend Layout
+
+- `src/components/ui/` = VENDOR shadcn. DO NOT EDIT. DO NOT IMPORT from app code.
+- `src/components/shared/` = Shared wrappers (AppButton, AppTable, etc). Barrel index.ts.
+- `src/modules/<feature>/{views,components,columns,hooks,utils}`
+- `src/lib/api/<feature>.ts` + `src/lib/query-keys.ts` + `src/lib/validation/schemas.ts`
+- Pages stay thin. Views do the work.
+
+## Backend Layout
+
+- `src/modules/<feature>/{controller,service,dto,module}`
+- `src/common/{guards,filters,interceptors,pipes,swagger,constants,utils,prisma,logging}`
+- Prisma schema.prisma is canonical. `npx prisma migrate deploy` only.
+
+## View Recipe (every list view)
+
+1. `useListState({ pageSize })` - URL-driven
+2. `useQuery({ queryKey: qkList(qk.x, list.query), queryFn: () => api.list(token, list.query) })`
+3. Loading: `AppSkeleton` rows (3-6)
+4. Empty: `AppTable` with emptyTitle + emptyDescription + emptyAction (create CTA)
+5. Error: `ErrorState` with retry
+6. Toolbar: `AppListToolbar` with actions slot (create button always visible)
+7. Mutations: `useMutation` + toast success/error + `queryClient.invalidateQueries`
+
+Every view MUST handle loading, error, and empty states. Never show white screen.
+
+## RBAC Guard Table
+
+| Who | Guard stack |
+|-----|-------------|
+| Human only | `@Permissions('entity.action')` |
+| Agent + human | `@Public()` + `AgentsDualAuthGuard` + `@ApiKeyScopes` |
+| Truly public | `@Public()` only |
+| MCP | `ApiKeyGuard` + `canUseTool()` |
+
+Never combine @Permissions with AgentsDualAuthGuard on same route.
+
+Three enforcement layers: capability + key scope + project access. Never less than two.
+
+## IconSax Rules
+
+Every icon instance MUST pass `variant` and `color` props. Default variant="Outline".
+- Bold for active nav
+- TwoTone for empty-state illustrations
+- Broken for destructive confirmations
+- Sizes: 16/20/24/32
+
+## Safety Patterns
+
+1. **eslint-disable only when fix is worse.** Add `// eslint-disable-next-line <rule> -- <reason>`. Inventoried for revert.
+2. **Never hand-edit generated/ or vendor ui/.**
+3. **Build/typecheck verified.** Failed fixes reverted + noted.
+4. **Cleanup in worktrees/branches.**
+5. **Secrets never in code/logs/messages.**
+6. **Existing repos: additive fixes only.** Never restructure.
+7. **Max 120 chars per line.**
+
+## Audit Report Format
+
+When running an audit, produce findings in this structure:
+
+```
+# Audit Report — [repo-name]
+
+**Date:** YYYY-MM-DD
+**Scope:** [files scanned]
+
+## Critical / Security
+- [finding] [file:line] [evidence] [suggested fix]
+
+## Modularity
+- [finding] [file:line] [evidence] [suggested fix]
+
+## Quality
+- [finding] [file:line] [evidence] [suggested fix]
+
+## Advisory (existing code)
+- [finding] [file:line] [note]
+
+## Summary
+- Total findings: N (Critical: X, Security: Y, Modularity: Z, Quality: W)
+- Gate status: build [pass/fail], typecheck [pass/fail]
+```
+
+Severity levels: Critical (security, data loss), High (broken patterns, missing guards),
+Medium (quality, missing states), Low (style, naming), Advisory (existing code deviations).
+
+## Scaffold Task Flow
+
+When asked to scaffold a new codebase:
+1. Ask questions first (stack, auth provider, DB, package manager) if --ask
+2. Write plan.md before generating
+3. Create folder tree from template
+4. Write AGENTS.md + docs/ skeleton
+5. Generate module skeletons with full guard stack + loading states
+6. Run build/typecheck gates
+7. Write summary.md with what was built
+
+When asked to audit an existing codebase:
+1. Scan all dimensions (security, modularity, rbac, errors, quality, ux, docs, gates)
+2. Existing code deviations = Advisory only (never force restructure)
+3. New code deviations = High/Critical findings
+4. Produce detailed markdown report with file:line evidence
+5. Suggest fixes for each finding
+
+When asked to clean up code:
+1. Run audit first
+2. Group findings into fix tasks
+3. Apply mechanical fixes (line length, naming, imports)
+4. For complex fixes: ask_human or route to orchestrator
+5. Every fix verified by build/typecheck
+6. Failed fixes reverted + noted in report

package/templates/backend/.env.example.tpl

@@ -0,0 +1,13 @@
+# Database
+DATABASE_URL="postgresql://user:password@localhost:5432/{{slug}}?schema=public"
+
+# JWT
+JWT_SECRET="change-me-to-a-random-secret"
+JWT_EXPIRES_IN="7d"
+
+# Server
+PORT={{apiPort}}
+NODE_ENV=development
+
+# CORS
+CORS_ORIGIN="http://localhost:{{port}}"

package/templates/backend/nest-cli.json.tpl

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

package/templates/backend/package.json.tpl

@@ -0,0 +1,41 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "{{description}}",
+  "scripts": {
+    "build": "nest build",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "prisma:generate": "prisma generate",
+    "prisma:migrate": "prisma migrate dev",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/config": "^4.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/passport": "^11.0.0",
+    "@nestjs/platform-express": "^11.0.0",
+    "@nestjs/swagger": "^11.0.0",
+    "@prisma/client": "^6.0.0",
+    "argon2": "^0.41.0",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.0",
+    "passport": "^0.7.0",
+    "passport-jwt": "^4.0.1",
+    "prisma-zod-generator": "^0.9.0",
+    "reflect-metadata": "^0.2.0",
+    "rxjs": "^7.8.0",
+    "socket.io": "^4.8.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^11.0.0",
+    "@nestjs/schematics": "^11.0.0",
+    "@types/node": "^22.0.0",
+    "@types/passport-jwt": "^4.0.0",
+    "prisma": "^6.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/backend/prisma/schema.prisma.tpl

@@ -0,0 +1,39 @@
+generator client {
+  provider = "prisma-client-js"
+}
+
+generator zod {
+  provider = "prisma-zod-generator"
+  output   = "../src/generated/zod"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(uuid()) @db.Uuid
+  email     String   @unique
+  name      String?
+  password  String
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  apiKey ApiKey[]
+
+  @@map("users")
+}
+
+model ApiKey {
+  id        String   @id @default(uuid()) @db.Uuid
+  key       String   @unique
+  name      String
+  userId    String   @map("user_id") @db.Uuid
+  createdAt DateTime @default(now()) @map("created_at")
+  lastUsed  DateTime? @map("last_used")
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@map("api_keys")
+}

package/templates/backend/src/app.module.ts.tpl

@@ -0,0 +1,24 @@
+import { Module } from "@nestjs/common";
+import { ConfigModule } from "@nestjs/config";
+import { APP_GUARD, APP_FILTER, APP_INTERCEPTOR } from "@nestjs/core";
+import { AuthGuard } from "./common/guards/jwt-auth.guard";
+import { RbacGuard } from "./common/guards/rbac.guard";
+import { AllExceptionsFilter } from "./common/filters/all-exceptions.filter";
+import { TransformInterceptor } from "./common/interceptors/transform.interceptor";
+import { PrismaModule } from "./prisma/prisma.module";
+import { ExampleModule } from "./modules/example/example.module";
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+    PrismaModule,
+    ExampleModule,
+  ],
+  providers: [
+    { provide: APP_GUARD, useClass: AuthGuard },
+    { provide: APP_GUARD, useClass: RbacGuard },
+    { provide: APP_FILTER, useClass: AllExceptionsFilter },
+    { provide: APP_INTERCEPTOR, useClass: TransformInterceptor },
+  ],
+})
+export class AppModule {}

package/templates/backend/src/common/filters/all-exceptions.filter.ts.tpl

@@ -0,0 +1,59 @@
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  HttpException,
+  HttpStatus,
+} from "@nestjs/common";
+import { Response } from "express";
+
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+
+    let status = HttpStatus.INTERNAL_SERVER_ERROR;
+    let code = "INTERNAL_ERROR";
+    let message = "An unexpected error occurred";
+    let details: unknown = undefined;
+
+    if (exception instanceof HttpException) {
+      status = exception.getStatus();
+      const res = exception.getResponse();
+      if (typeof res === "string") {
+        message = res;
+      } else if (typeof res === "object" && res !== null) {
+        const obj = res as Record<string, unknown>;
+        message = (obj.message as string) ?? message;
+        code = (obj.error as string) ?? code;
+        details = obj.details;
+      }
+      code = this.codeFromStatus(status);
+    } else if (exception instanceof Error) {
+      message = exception.message;
+    }
+
+    response.status(status).json({
+      success: false,
+      error: {
+        code,
+        message,
+        details,
+      },
+    });
+  }
+
+  private codeFromStatus(status: number): string {
+    const map: Record<number, string> = {
+      400: "BAD_REQUEST",
+      401: "UNAUTHORIZED",
+      403: "FORBIDDEN",
+      404: "NOT_FOUND",
+      409: "CONFLICT",
+      422: "UNPROCESSABLE_ENTITY",
+      429: "TOO_MANY_REQUESTS",
+    };
+    return map[status] ?? "INTERNAL_ERROR";
+  }
+}

package/templates/backend/src/common/guards/jwt-auth.guard.ts.tpl

@@ -0,0 +1,27 @@
+import { ExecutionContext, Injectable, UnauthorizedException } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { AuthGuard as PassportAuthGuard } from "@nestjs/passport";
+import { IS_PUBLIC_KEY } from "../decorators/public.decorator";
+
+@Injectable()
+export class AuthGuard extends PassportAuthGuard("jwt") {
+  constructor(private reflector: Reflector) {
+    super();
+  }
+
+  canActivate(context: ExecutionContext) {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (isPublic) return true;
+    return super.canActivate(context);
+  }
+
+  handleRequest(err: unknown, user: unknown) {
+    if (err || !user) {
+      throw err ?? new UnauthorizedException("Invalid or missing token");
+    }
+    return user;
+  }
+}

package/templates/backend/src/common/guards/rbac.guard.ts.tpl

@@ -0,0 +1,48 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+} from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { PERMISSIONS_KEY } from "../decorators/permissions.decorator";
+import { IS_PUBLIC_KEY } from "../decorators/public.decorator";
+
+@Injectable()
+export class RbacGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (isPublic) return true;
+
+    const requiredPermissions = this.reflector.getAllAndOverride<string[]>(
+      PERMISSIONS_KEY,
+      [context.getHandler(), context.getClass()]
+    );
+    if (!requiredPermissions || requiredPermissions.length === 0) return true;
+
+    const request = context.switchToHttp().getRequest();
+    const user = request.user;
+
+    if (!user) {
+      throw new ForbiddenException("Authentication required");
+    }
+
+    const userPermissions: string[] = user.permissions ?? [];
+    const hasPermission = requiredPermissions.every((p) =>
+      userPermissions.includes(p)
+    );
+
+    if (!hasPermission) {
+      throw new ForbiddenException(
+        `Missing required permissions: ${requiredPermissions.join(", ")}`
+      );
+    }
+
+    return true;
+  }
+}

package/templates/backend/src/common/interceptors/transform.interceptor.ts.tpl

@@ -0,0 +1,44 @@
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+} from "@nestjs/common";
+import { Observable, map } from "rxjs";
+
+export interface SuccessResponse<T> {
+  success: true;
+  data: T;
+  pagination?: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+  };
+}
+
+@Injectable()
+export class TransformInterceptor<T>
+  implements NestInterceptor<T, SuccessResponse<T>>
+{
+  intercept(
+    context: ExecutionContext,
+    next: CallHandler
+  ): Observable<SuccessResponse<T>> {
+    return next.handle().pipe(
+      map((data) => {
+        if (data && typeof data === "object" && "data" in data && "pagination" in data) {
+          return {
+            success: true as const,
+            data: data.data,
+            pagination: data.pagination,
+          };
+        }
+        return {
+          success: true as const,
+          data,
+        };
+      })
+    );
+  }
+}

package/templates/backend/src/common/pipes/zod-validation.pipe.ts.tpl

@@ -0,0 +1,29 @@
+import {
+  PipeTransform,
+  Injectable,
+  BadRequestException,
+} from "@nestjs/common";
+import { ZodSchema } from "zod";
+
+@Injectable()
+export class ZodValidationPipe implements PipeTransform {
+  constructor(
+    private schema: ZodSchema,
+    private source: "body" | "query" | "params" = "body"
+  ) {}
+
+  transform(value: unknown) {
+    const result = this.schema.safeParse(value);
+    if (!result.success) {
+      const issues = result.error.issues.map((i) => ({
+        path: i.path.join("."),
+        message: i.message,
+      }));
+      throw new BadRequestException({
+        message: "Validation failed",
+        details: issues,
+      });
+    }
+    return result.data;
+  }
+}

package/templates/backend/src/common/swagger/envelope.schemas.ts.tpl

@@ -0,0 +1,53 @@
+
+export function successSchema(dataSchema: Record<string, unknown>) {
+  return {
+    type: "object",
+    properties: {
+      success: { type: "boolean", example: true },
+      data: dataSchema,
+    },
+    required: ["success", "data"],
+  };
+}
+
+export function paginatedSchema(dataSchema: Record<string, unknown>) {
+  return {
+    type: "object",
+    properties: {
+      success: { type: "boolean", example: true },
+      data: {
+        type: "array",
+        items: dataSchema,
+      },
+      pagination: {
+        type: "object",
+        properties: {
+          page: { type: "number", example: 1 },
+          limit: { type: "number", example: 20 },
+          total: { type: "number", example: 100 },
+          totalPages: { type: "number", example: 5 },
+        },
+      },
+    },
+    required: ["success", "data", "pagination"],
+  };
+}
+
+export function errorSchema() {
+  return {
+    type: "object",
+    properties: {
+      success: { type: "boolean", example: false },
+      error: {
+        type: "object",
+        properties: {
+          code: { type: "string", example: "NOT_FOUND" },
+          message: { type: "string", example: "Resource not found" },
+          details: {},
+        },
+        required: ["code", "message"],
+      },
+    },
+    required: ["success", "error"],
+  };
+}