teamshare-bridge 0.2.5 → 0.4.0

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"],
+  };
+}

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

@@ -0,0 +1,62 @@
+import { applyDecorators } from "@nestjs/common";
+import { ApiResponse } from "@nestjs/swagger";
+
+export const INTERNAL_ERROR_CODES = [
+  "INTERNAL_ERROR",
+  "BAD_REQUEST",
+  "UNAUTHORIZED",
+  "FORBIDDEN",
+  "NOT_FOUND",
+  "CONFLICT",
+  "UNPROCESSABLE_ENTITY",
+  "TOO_MANY_REQUESTS",
+] as const;
+
+export function errs(...codes: (typeof INTERNAL_ERROR_CODES)[number][]) {
+  const descriptions: Record<string, string> = {
+    INTERNAL_ERROR: "Internal server error",
+    BAD_REQUEST: "Invalid request parameters",
+    UNAUTHORIZED: "Authentication required",
+    FORBIDDEN: "Insufficient permissions",
+    NOT_FOUND: "Resource not found",
+    CONFLICT: "Resource already exists",
+    UNPROCESSABLE_ENTITY: "Validation failed",
+    TOO_MANY_REQUESTS: "Rate limit exceeded",
+  };
+
+  return applyDecorators(
+    ...codes.map((code) =>
+      ApiResponse({
+        status: codeToStatus(code),
+        description: descriptions[code] ?? code,
+        schema: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: false },
+            error: {
+              type: "object",
+              properties: {
+                code: { type: "string", example: code },
+                message: { type: "string", example: descriptions[code] },
+              },
+            },
+          },
+        },
+      })
+    )
+  );
+}
+
+function codeToStatus(code: string): number {
+  const map: Record<string, number> = {
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    UNPROCESSABLE_ENTITY: 422,
+    TOO_MANY_REQUESTS: 429,
+    INTERNAL_ERROR: 500,
+  };
+  return map[code] ?? 500;
+}

package/templates/backend/src/main.ts.tpl

@@ -0,0 +1,27 @@
+import { NestFactory } from "@nestjs/core";
+import { ValidationPipe } from "@nestjs/common";
+import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";
+import { AppModule } from "./app.module";
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  app.setGlobalPrefix("api");
+  app.enableCors();
+  app.useGlobalPipes(new ValidationPipe({ transform: true, whitelist: true }));
+
+  const config = new DocumentBuilder()
+    .setTitle("{{projectName}} API")
+    .setDescription("{{description}}")
+    .setVersion("0.1.0")
+    .addBearerAuth()
+    .build();
+
+  const document = SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup("docs", app, document);
+
+  await app.listen({{apiPort}});
+  console.log(`Application running on: http://localhost:{{apiPort}}`);
+  console.log(`Swagger docs: http://localhost:{{apiPort}}/docs`);
+}
+bootstrap();

package/templates/backend/src/modules/example/example.controller.ts.tpl

@@ -0,0 +1,102 @@
+import {
+  Controller,
+  Get,
+  Post,
+  Param,
+  Query,
+  Body,
+  ParseUUIDPipe,
+} from "@nestjs/common";
+import {
+  ApiTags,
+  ApiOperation,
+  ApiParam,
+  ApiQuery,
+  ApiBody,
+  ApiOkResponse,
+  ApiBearerAuth,
+} from "@nestjs/swagger";
+import { Permissions } from "../../common/decorators/permissions.decorator";
+import { Public } from "../../common/decorators/public.decorator";
+import { ZodValidationPipe } from "../../common/pipes/zod-validation.pipe";
+import { successSchema, paginatedSchema } from "../../common/swagger/envelope.schemas";
+import { errs } from "../../common/swagger/error.schemas";
+import { ExampleService } from "./example.service";
+import { CreateExampleSchema, ExampleQuerySchema } from "./example.dto";
+
+@ApiTags("examples")
+@ApiBearerAuth()
+@Controller("examples")
+export class ExampleController {
+  constructor(private readonly exampleService: ExampleService) {}
+
+  @Get()
+  @Public()
+  @ApiOperation({ summary: "List examples", description: "Retrieve a paginated list of examples" })
+  @ApiQuery({ name: "page", required: false, example: 1 })
+  @ApiQuery({ name: "limit", required: false, example: 20 })
+  @ApiQuery({ name: "search", required: false })
+  @ApiOkResponse({
+    description: "Paginated list of examples",
+    schema: paginatedSchema({
+      type: "object",
+      properties: {
+        id: { type: "string", format: "uuid" },
+        name: { type: "string" },
+        createdAt: { type: "string", format: "date-time" },
+      },
+    }),
+  })
+  @errs("INTERNAL_ERROR")
+  async list(
+    @Query(new ZodValidationPipe(ExampleQuerySchema, "query")) query: {
+      page: number;
+      limit: number;
+      search?: string;
+    }
+  ) {
+    return this.exampleService.list(query);
+  }
+
+  @Post()
+  @Permissions("example:create")
+  @ApiOperation({ summary: "Create example", description: "Create a new example" })
+  @ApiBody({ schema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] } })
+  @ApiOkResponse({
+    description: "Created example",
+    schema: successSchema({
+      type: "object",
+      properties: {
+        id: { type: "string", format: "uuid" },
+        name: { type: "string" },
+        createdAt: { type: "string", format: "date-time" },
+      },
+    }),
+  })
+  @errs("BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "INTERNAL_ERROR")
+  async create(
+    @Body(new ZodValidationPipe(CreateExampleSchema)) body: { name: string }
+  ) {
+    return this.exampleService.create(body);
+  }
+
+  @Get(":id")
+  @Permissions("example:read")
+  @ApiOperation({ summary: "Get example", description: "Get an example by ID" })
+  @ApiParam({ name: "id", required: true })
+  @ApiOkResponse({
+    description: "Example details",
+    schema: successSchema({
+      type: "object",
+      properties: {
+        id: { type: "string", format: "uuid" },
+        name: { type: "string" },
+        createdAt: { type: "string", format: "date-time" },
+      },
+    }),
+  })
+  @errs("NOT_FOUND", "UNAUTHORIZED", "FORBIDDEN", "INTERNAL_ERROR")
+  async getOne(@Param("id", ParseUUIDPipe) id: string) {
+    return this.exampleService.getOne(id);
+  }
+}

package/templates/backend/src/modules/example/example.dto.ts.tpl

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+export const CreateExampleSchema = z.object({
+  name: z.string().min(1).max(200),
+});
+
+export const ExampleQuerySchema = z.object({
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().positive().max(100).default(20),
+  search: z.string().optional(),
+});
+
+export type CreateExampleInput = z.infer<typeof CreateExampleSchema>;
+export type ExampleQueryInput = z.infer<typeof ExampleQuerySchema>;

package/templates/backend/src/modules/example/example.module.ts.tpl

@@ -0,0 +1,10 @@
+import { Module } from "@nestjs/common";
+import { ExampleController } from "./example.controller";
+import { ExampleService } from "./example.service";
+
+@Module({
+  controllers: [ExampleController],
+  providers: [ExampleService],
+  exports: [ExampleService],
+})
+export class ExampleModule {}

package/templates/backend/src/modules/example/example.service.ts.tpl

@@ -0,0 +1,45 @@
+import { Injectable, NotFoundException } from "@nestjs/common";
+import { PrismaService } from "../../prisma/prisma.service";
+
+@Injectable()
+export class ExampleService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async list(query: { page: number; limit: number; search?: string }) {
+    const where = query.search
+      ? { name: { contains: query.search, mode: "insensitive" as const } }
+      : {};
+
+    const [data, total] = await Promise.all([
+      this.prisma.example.findMany({
+        where,
+        skip: (query.page - 1) * query.limit,
+        take: query.limit,
+        orderBy: { createdAt: "desc" },
+      }),
+      this.prisma.example.count({ where }),
+    ]);
+
+    return {
+      data,
+      pagination: {
+        page: query.page,
+        limit: query.limit,
+        total,
+        totalPages: Math.ceil(total / query.limit),
+      },
+    };
+  }
+
+  async create(data: { name: string }) {
+    return this.prisma.example.create({ data });
+  }
+
+  async getOne(id: string) {
+    const example = await this.prisma.example.findUnique({ where: { id } });
+    if (!example) {
+      throw new NotFoundException("Example not found");
+    }
+    return example;
+  }
+}

package/templates/backend/tsconfig.json.tpl

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "declaration": true,
+    "removeComments": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "allowSyntheticDefaultImports": true,
+    "target": "ES2021",
+    "sourceMap": true,
+    "outDir": "./dist",
+    "baseUrl": "./",
+    "incremental": true,
+    "skipLibCheck": true,
+    "strictNullChecks": true,
+    "noImplicitAny": false,
+    "strictBindCallApply": false,
+    "forceConsistentCasingInFileNames": false,
+    "noFallthroughCasesInSwitch": false,
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/common/.gitignore.tpl

@@ -0,0 +1,42 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+.next/
+out/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Prisma
+prisma/migrations/
+
+# TypeScript
+*.tsbuildinfo
+next-env.d.ts
+
+# Logs
+*.log
+
+# Temp
+tmp/
+temp/

package/templates/common/AGENTS.md.tpl

@@ -0,0 +1,58 @@
+# AGENTS.md - {{projectName}}
+
+## What this is
+
+{{description}}
+
+## Tech stack
+
+- **Frontend:** Next.js 16, React 19, TypeScript, Tailwind v4, shadcn, react-query v5, TanStack Table v8, react-hook-form, zod, next-auth v4, next-themes, socket.io-client
+- **Backend:** NestJS 11, Prisma 6, zod, Swagger/OpenAPI, passport-jwt, argon2, socket.io
+- **Database:** PostgreSQL
+
+## Folder structure
+
+```
+{{slug}}/
+├── frontend/          # Next.js web app
+│   ├── src/
+│   │   ├── app/       # App Router routes
+│   │   ├── components/
+│   │   │   ├── ui/    # Vendor primitives (shadcn) — do not edit
+│   │   │   └── shared/# Shared wrappers (AppButton, AppTable, etc.)
+│   │   ├── hooks/     # Custom React hooks
+│   │   ├── lib/       # Utilities, API client, query keys, validation
+│   │   └── modules/   # Feature modules (views, components, columns)
+│   └── package.json
+├── backend/           # NestJS API
+│   ├── prisma/        # Schema + migrations
+│   ├── src/
+│   │   ├── common/    # Guards, filters, interceptors, pipes, swagger
+│   │   ├── modules/   # Feature modules (controller, service, dto, module)
+│   │   ├── generated/ # Prisma + zod generated output
+│   │   └── main.ts
+│   └── package.json
+└── docs/              # Project documentation
+```
+
+## Build commands
+
+| Command | Location | Description |
+|---|---|---|
+| `npm run dev` | frontend/ | Start Next.js dev server |
+| `npm run build` | frontend/ | Build Next.js app |
+| `npm run dev` | backend/ | Start NestJS dev server |
+| `npm run build` | backend/ | Build NestJS app |
+| `npx prisma generate` | backend/ | Regenerate Prisma client |
+| `npx prisma migrate dev` | backend/ | Run migrations |
+
+## Conventions
+
+- Shared components use a consistent prefix (e.g., App*, or your own choice)
+- Use `data-slot="app-*"` attribute on shared components for styling hooks
+- Backend uses ZodValidationPipe for request validation
+- All endpoints return `{ success: true, data }` envelope
+- RBAC via `@Permissions()` decorator, `@Public()` for open routes
+- Query keys live in `src/lib/query-keys.ts`
+- Validation schemas live in `src/lib/validation/schemas.ts`
+- Loading states: every query view has skeleton + error + empty state

package/templates/common/docs/adr/README.md

@@ -0,0 +1,25 @@
+# Architecture Decision Records
+
+One file per decision, named `NNN-short-title.md` (e.g. `001-orm-choice.md`).
+
+Format for each ADR:
+
+```markdown
+# ADR-NNN: <Title>
+
+**Status:** proposed | accepted | superseded by ADR-MMM
+**Date:** YYYY-MM-DD
+
+## Context
+What problem or force drove this decision?
+
+## Decision
+What was decided, stated plainly.
+
+## Consequences
+What becomes easier, what becomes harder, what must now be true.
+```
+
+Write an ADR whenever a choice is expensive to reverse (ORM, validation
+strategy, folder layout, auth model). Agents working in this repo should
+read existing ADRs before proposing conflicting changes.