@torus-engineering/tas-kit 1.11.1 → 1.13.0

package/{.claude → .tas}/rules/csharp/api-testing.md

@@ -1,171 +1,171 @@
----
-paths:
-  - "**/*.cs"
-  - "**/ApiTests/**"
-  - "**/Api.Tests/**"
----
-
-# C# API Automation Testing
-
-> Used by `/tas-api-test`. Extends [csharp/testing.md](./testing.md).
-
-## Tech Stack
-
-| Component | Choice |
-|---|---|
-| Framework | xUnit (default) — match project if already using MSTest/NUnit |
-| Assertions | FluentAssertions |
-| HTTP | System.Net.Http.HttpClient |
-| Config | Microsoft.Extensions.Configuration + JSON/EnvVars |
-
-```xml
-<!-- ApiTests.csproj packages -->
-<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.*" />
-<PackageReference Include="xunit" Version="2.*" />
-<PackageReference Include="xunit.runner.visualstudio" Version="2.*" />
-<PackageReference Include="FluentAssertions" Version="6.*" />
-<PackageReference Include="Microsoft.Extensions.Configuration" Version="8.*" />
-<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="8.*" />
-<PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="8.*" />
-```
-
-## Project Structure
-
-```
-tests/ApiTests/
-  appsettings.json          # base (no real secrets)
-  appsettings.Test.json     # Test env override
-  appsettings.Staging.json  # Staging env override
-  .gitignore                # appsettings.*.local.json
-  Shared/
-    ApiTestSettings.cs
-    TestBase.cs
-  v1/
-    UsersApiTests.cs
-  v2/                       # APPEND-ONLY: don't modify v1
-    UsersApiTests.cs
-```
-
-## Config
-
-```json
-// appsettings.json
-{
-  "ApiTest": {
-    "BaseUrl": "https://localhost:5001",
-    "TimeoutSeconds": 30,
-    "Auth": { "Type": "Bearer", "TokenEndpoint": "/api/auth/token", "Username": "", "Password": "" }
-  }
-}
-```
-
-```csharp
-// ApiTestSettings.cs
-public sealed class ApiTestSettings
-{
-    public required string BaseUrl { get; init; }
-    public int TimeoutSeconds { get; init; } = 30;
-    public required AuthSettings Auth { get; init; }
-}
-public sealed class AuthSettings
-{
-    public string Type { get; init; } = "Bearer";
-    public string TokenEndpoint { get; init; } = "/api/auth/token";
-    public string Username { get; init; } = "";
-    public string Password { get; init; } = "";
-}
-```
-
-```csharp
-// TestBase.cs
-public abstract class TestBase : IAsyncLifetime
-{
-    protected HttpClient Client { get; private set; } = null!;
-    protected ApiTestSettings Settings { get; private set; } = null!;
-
-    public async Task InitializeAsync()
-    {
-        var env = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") ?? "Test";
-        Settings = new ConfigurationBuilder()
-            .AddJsonFile("appsettings.json")
-            .AddJsonFile($"appsettings.{env}.json", optional: true)
-            .AddEnvironmentVariables("APITEST_")
-            .Build()
-            .GetRequiredSection("ApiTest").Get<ApiTestSettings>()!;
-
-        Client = new HttpClient { BaseAddress = new Uri(Settings.BaseUrl),
-            Timeout = TimeSpan.FromSeconds(Settings.TimeoutSeconds) };
-
-        if (!string.IsNullOrEmpty(Settings.Auth.Username))
-            await AuthenticateAsync();
-    }
-
-    public Task DisposeAsync() { Client.Dispose(); return Task.CompletedTask; }
-
-    protected async Task AuthenticateAsync(string? username = null, string? password = null)
-    {
-        var res = await Client.PostAsJsonAsync(Settings.Auth.TokenEndpoint,
-            new { username = username ?? Settings.Auth.Username, password = password ?? Settings.Auth.Password });
-        res.EnsureSuccessStatusCode();
-        var token = (await res.Content.ReadFromJsonAsync<TokenResponse>())!.AccessToken;
-        Client.DefaultRequestHeaders.Authorization =
-            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
-    }
-
-    private sealed record TokenResponse(string AccessToken);
-}
-```
-
-## Test Class Header (required)
-
-```csharp
-// ============================================================
-// {Resource} API Tests — v{N}
-// Spec: {spec-file}  |  Generated: {YYYY-MM-DD}  |  Story: {ID}
-// APPEND-ONLY: don't modify existing methods.
-// ============================================================
-namespace ApiTests.V{N};
-public sealed class {Resource}ApiTests : TestBase
-{
-    // Inline DTOs — don't import from production code
-    private sealed record {Resource}Dto(Guid Id, string Name);
-    private sealed record ListResponse<T>(IReadOnlyList<T> Data, int Total);
-}
-```
-
-## Test Naming
-
-```
-{HttpMethod}_{Resource}_Returns{Status}_When{Condition}
-```
-
-Example: `GetById_User_Returns200_WhenExists`, `Create_Order_Returns422_WhenEmailInvalid`
-
-AC test: comment `// AC: {text}` right below XML doc.
-
-## XML Doc (required on each test)
-
-```csharp
-/// <summary>Verify {METHOD} {path} → {status} when {condition}. Spec: {ref}</summary>
-[Fact]
-public async Task ...
-```
-
-## Coverage Matrix
-
-| Condition | Status | When |
-|---|---|---|
-| Valid, authenticated | 2xx | Always |
-| No token | 401 | Endpoint requires auth |
-| Insufficient permission | 403 | RBAC / ownership |
-| `{id}` doesn't exist | 404 | Has path param |
-| Required field missing/invalid | 400/422 | Has request body |
-| Business rule (from AC) | 4xx | Story has corresponding AC |
-
-## CI/CD Env Vars
-
-```
-ASPNETCORE_ENVIRONMENT=Test
-APITEST__AUTH__USERNAME=...   # double __ for nested key
-APITEST__AUTH__PASSWORD=...
-```
+---
+paths:
+  - "**/*.cs"
+  - "**/ApiTests/**"
+  - "**/Api.Tests/**"
+---
+
+# C# API Automation Testing
+
+> Used by `/tas-apitest`. Extends [csharp/testing.md](./testing.md).
+
+## Tech Stack
+
+| Component | Choice |
+|---|---|
+| Framework | xUnit (default) — match project if already using MSTest/NUnit |
+| Assertions | FluentAssertions |
+| HTTP | System.Net.Http.HttpClient |
+| Config | Microsoft.Extensions.Configuration + JSON/EnvVars |
+
+```xml
+<!-- ApiTests.csproj packages -->
+<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.*" />
+<PackageReference Include="xunit" Version="2.*" />
+<PackageReference Include="xunit.runner.visualstudio" Version="2.*" />
+<PackageReference Include="FluentAssertions" Version="6.*" />
+<PackageReference Include="Microsoft.Extensions.Configuration" Version="8.*" />
+<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="8.*" />
+<PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="8.*" />
+```
+
+## Project Structure
+
+```
+tests/ApiTests/
+  appsettings.json          # base (no real secrets)
+  appsettings.Test.json     # Test env override
+  appsettings.Staging.json  # Staging env override
+  .gitignore                # appsettings.*.local.json
+  Shared/
+    ApiTestSettings.cs
+    TestBase.cs
+  v1/
+    UsersApiTests.cs
+  v2/                       # APPEND-ONLY: don't modify v1
+    UsersApiTests.cs
+```
+
+## Config
+
+```json
+// appsettings.json
+{
+  "ApiTest": {
+    "BaseUrl": "https://localhost:5001",
+    "TimeoutSeconds": 30,
+    "Auth": { "Type": "Bearer", "TokenEndpoint": "/api/auth/token", "Username": "", "Password": "" }
+  }
+}
+```
+
+```csharp
+// ApiTestSettings.cs
+public sealed class ApiTestSettings
+{
+    public required string BaseUrl { get; init; }
+    public int TimeoutSeconds { get; init; } = 30;
+    public required AuthSettings Auth { get; init; }
+}
+public sealed class AuthSettings
+{
+    public string Type { get; init; } = "Bearer";
+    public string TokenEndpoint { get; init; } = "/api/auth/token";
+    public string Username { get; init; } = "";
+    public string Password { get; init; } = "";
+}
+```
+
+```csharp
+// TestBase.cs
+public abstract class TestBase : IAsyncLifetime
+{
+    protected HttpClient Client { get; private set; } = null!;
+    protected ApiTestSettings Settings { get; private set; } = null!;
+
+    public async Task InitializeAsync()
+    {
+        var env = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") ?? "Test";
+        Settings = new ConfigurationBuilder()
+            .AddJsonFile("appsettings.json")
+            .AddJsonFile($"appsettings.{env}.json", optional: true)
+            .AddEnvironmentVariables("APITEST_")
+            .Build()
+            .GetRequiredSection("ApiTest").Get<ApiTestSettings>()!;
+
+        Client = new HttpClient { BaseAddress = new Uri(Settings.BaseUrl),
+            Timeout = TimeSpan.FromSeconds(Settings.TimeoutSeconds) };
+
+        if (!string.IsNullOrEmpty(Settings.Auth.Username))
+            await AuthenticateAsync();
+    }
+
+    public Task DisposeAsync() { Client.Dispose(); return Task.CompletedTask; }
+
+    protected async Task AuthenticateAsync(string? username = null, string? password = null)
+    {
+        var res = await Client.PostAsJsonAsync(Settings.Auth.TokenEndpoint,
+            new { username = username ?? Settings.Auth.Username, password = password ?? Settings.Auth.Password });
+        res.EnsureSuccessStatusCode();
+        var token = (await res.Content.ReadFromJsonAsync<TokenResponse>())!.AccessToken;
+        Client.DefaultRequestHeaders.Authorization =
+            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
+    }
+
+    private sealed record TokenResponse(string AccessToken);
+}
+```
+
+## Test Class Header (required)
+
+```csharp
+// ============================================================
+// {Resource} API Tests — v{N}
+// Spec: {spec-file}  |  Generated: {YYYY-MM-DD}  |  Story: {ID}
+// APPEND-ONLY: don't modify existing methods.
+// ============================================================
+namespace ApiTests.V{N};
+public sealed class {Resource}ApiTests : TestBase
+{
+    // Inline DTOs — don't import from production code
+    private sealed record {Resource}Dto(Guid Id, string Name);
+    private sealed record ListResponse<T>(IReadOnlyList<T> Data, int Total);
+}
+```
+
+## Test Naming
+
+```
+{HttpMethod}_{Resource}_Returns{Status}_When{Condition}
+```
+
+Example: `GetById_User_Returns200_WhenExists`, `Create_Order_Returns422_WhenEmailInvalid`
+
+AC test: comment `// AC: {text}` right below XML doc.
+
+## XML Doc (required on each test)
+
+```csharp
+/// <summary>Verify {METHOD} {path} → {status} when {condition}. Spec: {ref}</summary>
+[Fact]
+public async Task ...
+```
+
+## Coverage Matrix
+
+| Condition | Status | When |
+|---|---|---|
+| Valid, authenticated | 2xx | Always |
+| No token | 401 | Endpoint requires auth |
+| Insufficient permission | 403 | RBAC / ownership |
+| `{id}` doesn't exist | 404 | Has path param |
+| Required field missing/invalid | 400/422 | Has request body |
+| Business rule (from AC) | 4xx | Story has corresponding AC |
+
+## CI/CD Env Vars
+
+```
+ASPNETCORE_ENVIRONMENT=Test
+APITEST__AUTH__USERNAME=...   # double __ for nested key
+APITEST__AUTH__PASSWORD=...
+```

package/{.claude → .tas}/rules/csharp/coding-style.md

@@ -5,8 +5,6 @@ paths:
 ---
 # C# Coding Style
 
-> This file extends [common/coding-style.md](../common/coding-style.md) with C#-specific content.
-
 ## Standards
 
 - Follow current .NET conventions and enable nullable reference types

package/{.claude → .tas}/rules/csharp/security.md

@@ -53,6 +53,16 @@ await connection.QueryAsync<Order>(sql, new { customerId });
 - Log detailed exceptions with structured context server-side
 - Do not expose stack traces, SQL text, or filesystem paths in API responses
 
+## Web / API Hardening
+
+- Enforce HTTPS in production (`app.UseHttpsRedirection()`)
+- Enable HSTS (`app.UseHsts()`)
+- Add security headers: `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Content-Security-Policy`
+- CORS policy must be restrictive — list allowed origins explicitly, never `AllowAnyOrigin()` in production
+- Anti-forgery token required for state-changing form posts (`[ValidateAntiForgeryToken]`)
+- File upload validation: check size limit, allowed MIME types, sanitize file name, scan for malware before persisting
+- Encrypt PII at rest (column-level encryption, Always Encrypted, or transparent data encryption)
+
 ## References
 
 See skill: `security-review` for broader application security review checklists.

package/{.claude → .tas}/rules/python/coding-style.md

@@ -5,8 +5,6 @@ paths:
 ---
 # Python Coding Style
 
-> This file extends [common/coding-style.md](../common/coding-style.md) with Python specific content.
-
 ## Standards
 
 - Follow **PEP 8** conventions

package/{.claude → .tas}/rules/typescript/coding-style.md

@@ -7,8 +7,6 @@ paths:
 ---
 # TypeScript/JavaScript Coding Style
 
-> This file extends [common/coding-style.md](../common/coding-style.md) with TypeScript/JavaScript specific content.
-
 ## Types and Interfaces
 
 Use types to make public APIs, shared models, and component props explicit, readable, and reusable.

package/.tas/rules/typescript/patterns.md

@@ -0,0 +1,142 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# TypeScript/JavaScript Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with TypeScript/JavaScript specific content.
+
+## API Response Format
+
+```typescript
+interface ApiResponse<T> {
+  success: boolean
+  data?: T
+  error?: string
+  meta?: {
+    total: number
+    page: number
+    limit: number
+  }
+}
+```
+
+## Custom Hooks Pattern
+
+```typescript
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value)
+
+  useEffect(() => {
+    const handler = setTimeout(() => setDebouncedValue(value), delay)
+    return () => clearTimeout(handler)
+  }, [value, delay])
+
+  return debouncedValue
+}
+```
+
+## Repository Pattern
+
+```typescript
+interface Repository<T> {
+  findAll(filters?: Filters): Promise<T[]>
+  findById(id: string): Promise<T | null>
+  create(data: CreateDto): Promise<T>
+  update(id: string, data: UpdateDto): Promise<T>
+  delete(id: string): Promise<void>
+}
+```
+
+## Performance Anti-Patterns
+
+Avoid these in Node.js backends:
+
+- **Sequential awaits that could be parallel**: use `Promise.all()` when calls are independent
+- **CPU-blocking on event loop**: offload heavy computation to worker threads
+- **Missing connection pooling**: never create a new DB connection per request — use pooled clients
+- **ORM N+1**: missing `include`/`select` in Prisma/Sequelize — use eager loading or DataLoader for GraphQL
+- **Large file reads without streaming**: avoid `fs.readFile` on large files — use streams instead
+
+## N+1 Query Prevention (Batch Fetch)
+
+```typescript
+// BAD: N+1 queries
+const markets = await getMarkets()
+for (const market of markets) {
+  market.creator = await getUser(market.creator_id)  // N queries
+}
+
+// GOOD: Batch fetch — 2 queries total
+const markets = await getMarkets()
+const creatorIds = markets.map(m => m.creator_id)
+const creators = await getUsers(creatorIds)
+const creatorMap = new Map(creators.map(c => [c.id, c]))
+markets.forEach(m => { m.creator = creatorMap.get(m.creator_id) })
+```
+
+## Centralized Error Handler
+
+Custom `ApiError` class + single error mapper for API routes.
+
+```typescript
+class ApiError extends Error {
+  constructor(public statusCode: number, message: string, public isOperational = true) {
+    super(message)
+    Object.setPrototypeOf(this, ApiError.prototype)
+  }
+}
+
+export function errorHandler(error: unknown): Response {
+  if (error instanceof ApiError) {
+    return NextResponse.json({ error: error.message }, { status: error.statusCode })
+  }
+  if (error instanceof z.ZodError) {
+    return NextResponse.json({ error: 'Validation failed', details: error.errors }, { status: 400 })
+  }
+  console.error('Unexpected error:', error)
+  return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+}
+```
+
+## Cache-Aside Pattern
+
+```typescript
+async function getMarketWithCache(id: string): Promise<Market> {
+  const cacheKey = `market:${id}`
+  const cached = await redis.get(cacheKey)
+  if (cached) return JSON.parse(cached)
+
+  const market = await db.markets.findUnique({ where: { id } })
+  if (!market) throw new ApiError(404, 'Market not found')
+
+  await redis.setex(cacheKey, 300, JSON.stringify(market))  // 5 min TTL
+  return market
+}
+```
+
+Invalidate on writes: `await redis.del(\`market:\${id}\`)` after update/delete.
+
+## Retry with Exponential Backoff
+
+```typescript
+async function fetchWithRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+  let lastError: Error
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn()
+    } catch (error) {
+      lastError = error as Error
+      if (i < maxRetries - 1) {
+        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000))  // 1s, 2s, 4s
+      }
+    }
+  }
+  throw lastError!
+}
+```
+
+Use for transient failures (network, upstream API). Do NOT retry on 4xx client errors.

package/.tas/rules/typescript/security.md

@@ -0,0 +1,88 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# TypeScript/JavaScript Security
+
+> This file extends [common/security.md](../common/security.md) with TypeScript/JavaScript specific content.
+
+## Secret Management
+
+```typescript
+// NEVER: Hardcoded secrets
+const apiKey = "sk-proj-xxxxx"
+
+// ALWAYS: Environment variables
+const apiKey = process.env.OPENAI_API_KEY
+
+if (!apiKey) {
+  throw new Error('OPENAI_API_KEY not configured')
+}
+```
+
+## JWT Token Validation
+
+```typescript
+import jwt from 'jsonwebtoken'
+
+interface JWTPayload {
+  userId: string
+  email: string
+  role: 'admin' | 'user'
+}
+
+export function verifyToken(token: string): JWTPayload {
+  try {
+    return jwt.verify(token, process.env.JWT_SECRET!) as JWTPayload
+  } catch {
+    throw new ApiError(401, 'Invalid token')
+  }
+}
+
+export async function requireAuth(request: Request): Promise<JWTPayload> {
+  const token = request.headers.get('authorization')?.replace('Bearer ', '')
+  if (!token) throw new ApiError(401, 'Missing authorization token')
+  return verifyToken(token)
+}
+```
+
+Always verify `JWT_SECRET` is set at boot. Never log tokens. Use short TTL (15min) + refresh tokens.
+
+## Role-Based Access Control (RBAC)
+
+```typescript
+type Permission = 'read' | 'write' | 'delete' | 'admin'
+
+const rolePermissions: Record<User['role'], Permission[]> = {
+  admin: ['read', 'write', 'delete', 'admin'],
+  moderator: ['read', 'write', 'delete'],
+  user: ['read', 'write'],
+}
+
+export function hasPermission(user: User, permission: Permission): boolean {
+  return rolePermissions[user.role].includes(permission)
+}
+
+export function requirePermission(permission: Permission) {
+  return (handler: (req: Request, user: User) => Promise<Response>) =>
+    async (req: Request) => {
+      const user = await requireAuth(req)
+      if (!hasPermission(user, permission)) throw new ApiError(403, 'Insufficient permissions')
+      return handler(req, user)
+    }
+}
+
+// Usage
+export const DELETE = requirePermission('delete')(async (req, user) => {
+  // handler with verified permission
+})
+```
+
+Check authorization at the route level (not inside business logic). Resource-level ownership checks (e.g., `if (resource.userId !== user.id)`) belong in service layer.
+
+## Agent Support
+
+- Use **security-reviewer** skill for comprehensive security audits

package/{.claude → .tas}/rules/typescript/testing.md

@@ -12,7 +12,3 @@ paths:
 ## E2E Testing
 
 Use **Playwright** as the E2E testing framework for critical user flows.
-
-## Agent Support
-
-- **e2e-runner** - Playwright E2E testing specialist

package/{.claude → .tas}/rules/web/coding-style.md

@@ -1,5 +1,3 @@
-> This file extends [common/coding-style.md](../common/coding-style.md) with web-specific frontend content.
-
 # Web Coding Style
 
 ## File Organization