teamshare-bridge 0.22.7 → 0.22.8

package/skills/teamshare-scaffold/SKILL.md

@@ -1,38 +1,38 @@
----
-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 |
-
+---
+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.
-
+- 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
@@ -43,91 +43,91 @@ Standards enforcement for TeamShare codebases. Use when scaffolding a new repo,
 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
+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

@@ -1,13 +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}}"
+# 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

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

package/templates/backend/package.json.tpl

@@ -1,41 +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"
-  }
-}
+{
+  "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

@@ -1,39 +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")
-}
+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

@@ -1,24 +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 {}
+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

@@ -1,59 +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";
-  }
-}
+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";
+  }
+}