@torus-engineering/tas-kit 1.5.1 → 1.7.0

package/.claude/rules/common/testing.md

@@ -0,0 +1,57 @@
+# Testing Requirements
+
+## Minimum Test Coverage: 80%
+
+Test Types (ALL required):
+1. **Unit Tests** - Individual functions, utilities, components
+2. **Integration Tests** - API endpoints, database operations
+3. **E2E Tests** - Critical user flows (framework chosen per language)
+
+## Test-Driven Development
+
+MANDATORY workflow:
+1. Write test first (RED)
+2. Run test - it should FAIL
+3. Write minimal implementation (GREEN)
+4. Run test - it should PASS
+5. Refactor (IMPROVE)
+6. Verify coverage (80%+)
+
+## Troubleshooting Test Failures
+
+1. Use **tdd-guide** agent
+2. Check test isolation
+3. Verify mocks are correct
+4. Fix implementation, not tests (unless tests are wrong)
+
+## Agent Support
+
+- **tdd-guide** - Use PROACTIVELY for new features, enforces write-tests-first
+
+## Test Structure (AAA Pattern)
+
+Prefer Arrange-Act-Assert structure for tests:
+
+```typescript
+test('calculates similarity correctly', () => {
+  // Arrange
+  const vector1 = [1, 0, 0]
+  const vector2 = [0, 1, 0]
+
+  // Act
+  const similarity = calculateCosineSimilarity(vector1, vector2)
+
+  // Assert
+  expect(similarity).toBe(0)
+})
+```
+
+### Test Naming
+
+Use descriptive names that explain the behavior under test:
+
+```typescript
+test('returns empty array when no markets match query', () => {})
+test('throws error when API key is missing', () => {})
+test('falls back to substring search when Redis is unavailable', () => {})
+```

package/.claude/rules/csharp/coding-style.md

@@ -0,0 +1,72 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csx"
+---
+# 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
+- Prefer explicit access modifiers on public and internal APIs
+- Keep files aligned with the primary type they define
+
+## Types and Models
+
+- Prefer `record` or `record struct` for immutable value-like models
+- Use `class` for entities or types with identity and lifecycle
+- Use `interface` for service boundaries and abstractions
+- Avoid `dynamic` in application code; prefer generics or explicit models
+
+```csharp
+public sealed record UserDto(Guid Id, string Email);
+
+public interface IUserRepository
+{
+    Task<UserDto?> FindByIdAsync(Guid id, CancellationToken cancellationToken);
+}
+```
+
+## Immutability
+
+- Prefer `init` setters, constructor parameters, and immutable collections for shared state
+- Do not mutate input models in-place when producing updated state
+
+```csharp
+public sealed record UserProfile(string Name, string Email);
+
+public static UserProfile Rename(UserProfile profile, string name) =>
+    profile with { Name = name };
+```
+
+## Async and Error Handling
+
+- Prefer `async`/`await` over blocking calls like `.Result` or `.Wait()`
+- Pass `CancellationToken` through public async APIs
+- Throw specific exceptions and log with structured properties
+
+```csharp
+public async Task<Order> LoadOrderAsync(
+    Guid orderId,
+    CancellationToken cancellationToken)
+{
+    try
+    {
+        return await repository.FindAsync(orderId, cancellationToken)
+            ?? throw new InvalidOperationException($"Order {orderId} was not found.");
+    }
+    catch (Exception ex)
+    {
+        logger.LogError(ex, "Failed to load order {OrderId}", orderId);
+        throw;
+    }
+}
+```
+
+## Formatting
+
+- Use `dotnet format` for formatting and analyzer fixes
+- Keep `using` directives organized and remove unused imports
+- Prefer expression-bodied members only when they stay readable

package/.claude/rules/csharp/hooks.md

@@ -0,0 +1,25 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csx"
+  - "**/*.csproj"
+  - "**/*.sln"
+  - "**/Directory.Build.props"
+  - "**/Directory.Build.targets"
+---
+# C# Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with C#-specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **dotnet format**: Auto-format edited C# files and apply analyzer fixes
+- **dotnet build**: Verify the solution or project still compiles after edits
+- **dotnet test --no-build**: Re-run the nearest relevant test project after behavior changes
+
+## Stop Hooks
+
+- Run a final `dotnet build` before ending a session with broad C# changes
+- Warn on modified `appsettings*.json` files so secrets do not get committed

package/.claude/rules/csharp/patterns.md

@@ -0,0 +1,50 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csx"
+---
+# C# Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with C#-specific content.
+
+## API Response Pattern
+
+```csharp
+public sealed record ApiResponse<T>(
+    bool Success,
+    T? Data = default,
+    string? Error = null,
+    object? Meta = null);
+```
+
+## Repository Pattern
+
+```csharp
+public interface IRepository<T>
+{
+    Task<IReadOnlyList<T>> FindAllAsync(CancellationToken cancellationToken);
+    Task<T?> FindByIdAsync(Guid id, CancellationToken cancellationToken);
+    Task<T> CreateAsync(T entity, CancellationToken cancellationToken);
+    Task<T> UpdateAsync(T entity, CancellationToken cancellationToken);
+    Task DeleteAsync(Guid id, CancellationToken cancellationToken);
+}
+```
+
+## Options Pattern
+
+Use strongly typed options for config instead of reading raw strings throughout the codebase.
+
+```csharp
+public sealed class PaymentsOptions
+{
+    public const string SectionName = "Payments";
+    public required string BaseUrl { get; init; }
+    public required string ApiKeySecretName { get; init; }
+}
+```
+
+## Dependency Injection
+
+- Depend on interfaces at service boundaries
+- Keep constructors focused; if a service needs too many dependencies, split responsibilities
+- Register lifetimes intentionally: singleton for stateless/shared services, scoped for request data, transient for lightweight pure workers

package/.claude/rules/csharp/security.md

@@ -0,0 +1,58 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csx"
+  - "**/*.csproj"
+  - "**/appsettings*.json"
+---
+# C# Security
+
+> This file extends [common/security.md](../common/security.md) with C#-specific content.
+
+## Secret Management
+
+- Never hardcode API keys, tokens, or connection strings in source code
+- Use environment variables, user secrets for local development, and a secret manager in production
+- Keep `appsettings.*.json` free of real credentials
+
+```csharp
+// BAD
+const string ApiKey = "sk-live-123";
+
+// GOOD
+var apiKey = builder.Configuration["OpenAI:ApiKey"]
+    ?? throw new InvalidOperationException("OpenAI:ApiKey is not configured.");
+```
+
+## SQL Injection Prevention
+
+- Always use parameterized queries with ADO.NET, Dapper, or EF Core
+- Never concatenate user input into SQL strings
+- Validate sort fields and filter operators before using dynamic query composition
+
+```csharp
+const string sql = "SELECT * FROM Orders WHERE CustomerId = @customerId";
+await connection.QueryAsync<Order>(sql, new { customerId });
+```
+
+## Input Validation
+
+- Validate DTOs at the application boundary
+- Use data annotations, FluentValidation, or explicit guard clauses
+- Reject invalid model state before running business logic
+
+## Authentication and Authorization
+
+- Prefer framework auth handlers instead of custom token parsing
+- Enforce authorization policies at endpoint or handler boundaries
+- Never log raw tokens, passwords, or PII
+
+## Error Handling
+
+- Return safe client-facing messages
+- Log detailed exceptions with structured context server-side
+- Do not expose stack traces, SQL text, or filesystem paths in API responses
+
+## References
+
+See skill: `security-review` for broader application security review checklists.

package/.claude/rules/csharp/testing.md

@@ -0,0 +1,46 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csx"
+  - "**/*.csproj"
+---
+# C# Testing
+
+> This file extends [common/testing.md](../common/testing.md) with C#-specific content.
+
+## Test Framework
+
+- Prefer **xUnit** for unit and integration tests
+- Use **FluentAssertions** for readable assertions
+- Use **Moq** or **NSubstitute** for mocking dependencies
+- Use **Testcontainers** when integration tests need real infrastructure
+
+## Test Organization
+
+- Mirror `src/` structure under `tests/`
+- Separate unit, integration, and end-to-end coverage clearly
+- Name tests by behavior, not implementation details
+
+```csharp
+public sealed class OrderServiceTests
+{
+    [Fact]
+    public async Task FindByIdAsync_ReturnsOrder_WhenOrderExists()
+    {
+        // Arrange
+        // Act
+        // Assert
+    }
+}
+```
+
+## ASP.NET Core Integration Tests
+
+- Use `WebApplicationFactory<TEntryPoint>` for API integration coverage
+- Test auth, validation, and serialization through HTTP, not by bypassing middleware
+
+## Coverage
+
+- Target 80%+ line coverage
+- Focus coverage on domain logic, validation, auth, and failure paths
+- Run `dotnet test` in CI with coverage collection enabled where available

package/.claude/rules/python/coding-style.md

@@ -0,0 +1,42 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Python Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Python specific content.
+
+## Standards
+
+- Follow **PEP 8** conventions
+- Use **type annotations** on all function signatures
+
+## Immutability
+
+Prefer immutable data structures:
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class User:
+    name: str
+    email: str
+
+from typing import NamedTuple
+
+class Point(NamedTuple):
+    x: float
+    y: float
+```
+
+## Formatting
+
+- **black** for code formatting
+- **isort** for import sorting
+- **ruff** for linting
+
+## Reference
+
+See skill: `python-patterns` for comprehensive Python idioms and patterns.

package/.claude/rules/python/hooks.md

@@ -0,0 +1,19 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Python Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Python specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **black/ruff**: Auto-format `.py` files after edit
+- **mypy/pyright**: Run type checking after editing `.py` files
+
+## Warnings
+
+- Warn about `print()` statements in edited files (use `logging` module instead)

package/.claude/rules/python/patterns.md

@@ -0,0 +1,39 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Python Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with Python specific content.
+
+## Protocol (Duck Typing)
+
+```python
+from typing import Protocol
+
+class Repository(Protocol):
+    def find_by_id(self, id: str) -> dict | None: ...
+    def save(self, entity: dict) -> dict: ...
+```
+
+## Dataclasses as DTOs
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class CreateUserRequest:
+    name: str
+    email: str
+    age: int | None = None
+```
+
+## Context Managers & Generators
+
+- Use context managers (`with` statement) for resource management
+- Use generators for lazy evaluation and memory-efficient iteration
+
+## Reference
+
+See skill: `python-patterns` for comprehensive patterns including decorators, concurrency, and package organization.

package/.claude/rules/python/security.md

@@ -0,0 +1,30 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Python Security
+
+> This file extends [common/security.md](../common/security.md) with Python specific content.
+
+## Secret Management
+
+```python
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+api_key = os.environ["OPENAI_API_KEY"]  # Raises KeyError if missing
+```
+
+## Security Scanning
+
+- Use **bandit** for static security analysis:
+  ```bash
+  bandit -r src/
+  ```
+
+## Reference
+
+See skill: `django-security` for Django-specific security guidelines (if applicable).

package/.claude/rules/python/testing.md

@@ -0,0 +1,38 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Python Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Python specific content.
+
+## Framework
+
+Use **pytest** as the testing framework.
+
+## Coverage
+
+```bash
+pytest --cov=src --cov-report=term-missing
+```
+
+## Test Organization
+
+Use `pytest.mark` for test categorization:
+
+```python
+import pytest
+
+@pytest.mark.unit
+def test_calculate_total():
+    ...
+
+@pytest.mark.integration
+def test_database_connection():
+    ...
+```
+
+## Reference
+
+See skill: `python-testing` for detailed pytest patterns and fixtures.

package/.claude/rules/typescript/coding-style.md

@@ -0,0 +1,199 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# 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.
+
+### Public APIs
+
+- Add parameter and return types to exported functions, shared utilities, and public class methods
+- Let TypeScript infer obvious local variable types
+- Extract repeated inline object shapes into named types or interfaces
+
+```typescript
+// WRONG: Exported function without explicit types
+export function formatUser(user) {
+  return `${user.firstName} ${user.lastName}`
+}
+
+// CORRECT: Explicit types on public APIs
+interface User {
+  firstName: string
+  lastName: string
+}
+
+export function formatUser(user: User): string {
+  return `${user.firstName} ${user.lastName}`
+}
+```
+
+### Interfaces vs. Type Aliases
+
+- Use `interface` for object shapes that may be extended or implemented
+- Use `type` for unions, intersections, tuples, mapped types, and utility types
+- Prefer string literal unions over `enum` unless an `enum` is required for interoperability
+
+```typescript
+interface User {
+  id: string
+  email: string
+}
+
+type UserRole = 'admin' | 'member'
+type UserWithRole = User & {
+  role: UserRole
+}
+```
+
+### Avoid `any`
+
+- Avoid `any` in application code
+- Use `unknown` for external or untrusted input, then narrow it safely
+- Use generics when a value's type depends on the caller
+
+```typescript
+// WRONG: any removes type safety
+function getErrorMessage(error: any) {
+  return error.message
+}
+
+// CORRECT: unknown forces safe narrowing
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message
+  }
+
+  return 'Unexpected error'
+}
+```
+
+### React Props
+
+- Define component props with a named `interface` or `type`
+- Type callback props explicitly
+- Do not use `React.FC` unless there is a specific reason to do so
+
+```typescript
+interface User {
+  id: string
+  email: string
+}
+
+interface UserCardProps {
+  user: User
+  onSelect: (id: string) => void
+}
+
+function UserCard({ user, onSelect }: UserCardProps) {
+  return <button onClick={() => onSelect(user.id)}>{user.email}</button>
+}
+```
+
+### JavaScript Files
+
+- In `.js` and `.jsx` files, use JSDoc when types improve clarity and a TypeScript migration is not practical
+- Keep JSDoc aligned with runtime behavior
+
+```javascript
+/**
+ * @param {{ firstName: string, lastName: string }} user
+ * @returns {string}
+ */
+export function formatUser(user) {
+  return `${user.firstName} ${user.lastName}`
+}
+```
+
+## Immutability
+
+Use spread operator for immutable updates:
+
+```typescript
+interface User {
+  id: string
+  name: string
+}
+
+// WRONG: Mutation
+function updateUser(user: User, name: string): User {
+  user.name = name // MUTATION!
+  return user
+}
+
+// CORRECT: Immutability
+function updateUser(user: Readonly<User>, name: string): User {
+  return {
+    ...user,
+    name
+  }
+}
+```
+
+## Error Handling
+
+Use async/await with try-catch and narrow unknown errors safely:
+
+```typescript
+interface User {
+  id: string
+  email: string
+}
+
+declare function riskyOperation(userId: string): Promise<User>
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message
+  }
+
+  return 'Unexpected error'
+}
+
+const logger = {
+  error: (message: string, error: unknown) => {
+    // Replace with your production logger (for example, pino or winston).
+  }
+}
+
+async function loadUser(userId: string): Promise<User> {
+  try {
+    const result = await riskyOperation(userId)
+    return result
+  } catch (error: unknown) {
+    logger.error('Operation failed', error)
+    throw new Error(getErrorMessage(error))
+  }
+}
+```
+
+## Input Validation
+
+Use Zod for schema-based validation and infer types from the schema:
+
+```typescript
+import { z } from 'zod'
+
+const userSchema = z.object({
+  email: z.string().email(),
+  age: z.number().int().min(0).max(150)
+})
+
+type UserInput = z.infer<typeof userSchema>
+
+const validated: UserInput = userSchema.parse(input)
+```
+
+## Console.log
+
+- No `console.log` statements in production code
+- Use proper logging libraries instead
+- See hooks for automatic detection

package/.claude/rules/typescript/hooks.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+# TypeScript/JavaScript Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with TypeScript/JavaScript specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **Prettier**: Auto-format JS/TS files after edit
+- **TypeScript check**: Run `tsc` after editing `.ts`/`.tsx` files
+- **console.log warning**: Warn about `console.log` in edited files
+
+## Stop Hooks
+
+- **console.log audit**: Check all modified files for `console.log` before session ends