teamshare-bridge 0.3.0 → 0.4.0

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.

package/templates/common/docs/api-contract.md.tpl

@@ -0,0 +1,72 @@
+# API Contract - {{projectName}}
+
+## Response envelope
+
+Every successful response returns:
+
+```json
+{
+  "success": true,
+  "data": { ... }
+}
+```
+
+Paginated responses include a `pagination` field:
+
+```json
+{
+  "success": true,
+  "data": [ ... ],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+```
+
+## Error envelope
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Resource not found",
+    "details": null
+  }
+}
+```
+
+Common error codes: `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `UNPROCESSABLE_ENTITY`, `TOO_MANY_REQUESTS`, `INTERNAL_ERROR`.
+
+## Authentication
+
+- Bearer token in `Authorization` header
+- JWT issued by `/api/auth/login`
+- Public routes marked with `@Public()` decorator
+
+## RBAC
+
+Route permissions declared via `@Permissions("resource:action")` decorator.
+Roles resolve against the addressed company scope.
+
+| Role | Description |
+|---|---|
+| owner | Full access |
+| admin | Manage members, settings |
+| member | Standard access |
+| viewer | Read-only |
+
+## Pagination
+
+Query params: `page` (default 1), `limit` (default 20, max 100).
+
+## Search
+
+`search` query param performs case-insensitive text matching.
+
+## Sorting
+
+`sort` and `order` query params (e.g. `?sort=createdAt&order=desc`).

package/templates/web/next.config.ts.tpl

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+};
+
+export default nextConfig;

package/templates/web/package.json.tpl

@@ -0,0 +1,37 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "{{description}}",
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "next-auth": "^4.24.0",
+    "next-themes": "^0.4.0",
+    "@tanstack/react-query": "^5.60.0",
+    "@tanstack/react-table": "^8.20.0",
+    "react-hook-form": "^7.53.0",
+    "@hookform/resolvers": "^3.9.0",
+    "zod": "^3.23.0",
+    "socket.io-client": "^4.8.0",
+    "iconsax-react": "^0.0.8",
+    "clsx": "^2.1.0",
+    "tailwind-merge": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.6.0",
+    "tailwindcss": "^4.0.0",
+    "@tailwindcss/postcss": "^4.0.0",
+    "postcss": "^8.4.0"
+  }
+}

package/templates/web/src/app/globals.css.tpl

@@ -0,0 +1,48 @@
+@import "tailwindcss";
+
+@theme inline {
+  --app-primary-50: #eff6ff;
+  --app-primary-100: #dbeafe;
+  --app-primary-200: #bfdbfe;
+  --app-primary-300: #93c5fd;
+  --app-primary-400: #60a5fa;
+  --app-primary-500: #3b82f6;
+  --app-primary-600: #2563eb;
+  --app-primary-700: #1d4ed8;
+  --app-primary-800: #1e40af;
+  --app-primary-900: #1e3a8a;
+
+  --app-bg-primary: #ffffff;
+  --app-bg-secondary: #f8fafc;
+  --app-bg-tertiary: #f1f5f9;
+  --app-bg-inverse: #0f172a;
+
+  --app-text-primary: #0f172a;
+  --app-text-secondary: #475569;
+  --app-text-tertiary: #94a3b8;
+  --app-text-inverse: #f8fafc;
+
+  --app-border-default: #e2e8f0;
+  --app-border-strong: #cbd5e1;
+
+  --app-radius: 0.5rem;
+
+  --color-background: var(--app-bg-primary);
+  --color-foreground: var(--app-text-primary);
+  --color-muted: var(--app-bg-secondary);
+  --color-muted-foreground: var(--app-text-secondary);
+  --color-border: var(--app-border-default);
+  --color-primary: var(--app-primary-600);
+  --color-primary-foreground: var(--app-text-inverse);
+}
+
+@custom-variant dark (&:is(.dark *));
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}

package/templates/web/src/app/layout.tsx.tpl

@@ -0,0 +1,25 @@
+import type { Metadata } from "next";
+import { Inter } from "next/font/google";
+import { Providers } from "@/lib/providers";
+import "./globals.css";
+
+const inter = Inter({ subsets: ["latin"] });
+
+export const metadata: Metadata = {
+  title: "{{projectName}}",
+  description: "{{description}}",
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className={inter.className}>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}

package/templates/web/src/components/shared/app-button.tsx.tpl

@@ -0,0 +1,59 @@
+import { Loader2 } from "lucide-react";
+import { type ButtonHTMLAttributes, forwardRef } from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-8",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+);
+
+export interface AppButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  loading?: boolean;
+}
+
+const AppButton = forwardRef<HTMLButtonElement, AppButtonProps>(
+  ({ className, variant, size, loading, disabled, children, ...props }, ref) => {
+    return (
+      <button
+        ref={ref}
+        data-slot="app-button"
+        className={cn(buttonVariants({ variant, size, className }))}
+        disabled={disabled || loading}
+        {...props}
+      >
+        {loading && <Loader2 className="h-4 w-4 animate-spin" variant="Outline" color="currentColor" />}
+        {children}
+      </button>
+    );
+  }
+);
+AppButton.displayName = "AppButton";
+
+export { AppButton, buttonVariants };