@aicgen/aicgen 1.0.0-beta.1 → 1.0.0-beta.2

package/.claude/guidelines/devops.md

@@ -1,226 +0,0 @@
-# DevOps
-
-# CI/CD Practices
-
-## Continuous Integration
-
-Run on every commit:
-
-```yaml
-# .github/workflows/ci.yml
-name: CI
-on: [push, pull_request]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'npm'
-      - run: npm ci
-      - run: npm run lint
-      - run: npm run typecheck
-      - run: npm test
-      - run: npm run build
-```
-
-## Continuous Deployment
-
-Deploy automatically after CI passes:
-
-```yaml
-deploy:
-  needs: build
-  if: github.ref == 'refs/heads/main'
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v4
-    - run: npm ci
-    - run: npm run build
-    - run: npm run deploy
-      env:
-        DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
-```
-
-## Deployment Strategies
-
-### Blue-Green Deployment
-Run two identical environments, switch traffic instantly.
-
-### Canary Releases
-Route small percentage of traffic to new version first.
-
-### Rolling Updates
-Gradually replace instances with new version.
-
-## Best Practices
-
-- Run fast tests first, slow tests later
-- Cache dependencies between runs
-- Use matrix builds for multiple versions/platforms
-- Keep secrets in secure storage
-- Automate database migrations
-- Include rollback procedures
-- Monitor deployments with health checks
-- Use feature flags for safer releases
-
-
----
-
-# DevOps Practices
-
-## Infrastructure as Code
-
-```text
-# Define infrastructure as code (e.g., Terraform, Pulumi)
-
-Resource S3Bucket "app-bucket":
-  Access: Private
-  Versioning: Enabled
-
-Resource LambdaFunction "api":
-  Runtime: Node.js / Python / Go
-  Handler: index.handler
-  Code: ./dist
-```
-
-## Containerization
-
-```dockerfile
-# Build Stage
-FROM base-image AS builder
-WORKDIR /app
-COPY dependency-files ./
-RUN install-dependencies
-COPY source-code .
-RUN build-application
-
-# Runtime Stage
-FROM runtime-image
-WORKDIR /app
-COPY --from=builder /app/dist ./dist
-EXPOSE 8080
-CMD ["run", "application"]
-```
-
-## Observability
-
-### Logging
-```json
-{
-  "level": "info",
-  "message": "Order created",
-  "orderId": "ord_123",
-  "customerId": "cust_456",
-  "total": 99.99,
-  "timestamp": "2023-10-27T10:00:00Z"
-}
-```
-
-### Metrics
-```text
-Metrics.Increment("orders.created")
-Metrics.Histogram("order.value", total)
-Metrics.Timing("order.processing_time", duration)
-```
-
-### Health Checks
-```text
-GET /health
-Response 200 OK:
-{
-  "status": "healthy",
-  "version": "1.2.3",
-  "uptime": 3600
-}
-```
-
-## Best Practices
-
-- Version control all infrastructure
-- Use immutable infrastructure
-- Implement proper secret management
-- Set up alerting for critical metrics
-- Use structured logging (JSON)
-- Include correlation IDs for tracing
-- Document runbooks for incidents
-
-
----
-
-# Observability
-
-## Overview
-
-Observability is the ability to understand the internal state of a system by examining its outputs. In modern distributed systems, it goes beyond simple monitoring to include logging, metrics, and tracing.
-
-## Three Pillars
-
-### 1. Structured Logging
-
-Logs should be machine-readable (JSON) and contain context.
-
-```json
-// ✅ Good: Structured JSON logging
-{
-  "level": "info",
-  "message": "Order processed",
-  "orderId": "ord_123",
-  "userId": "user_456",
-  "amount": 99.99,
-  "durationMs": 145,
-  "status": "success"
-}
-```
-```text
-// ❌ Bad: Unstructured text
-"Order processed: ord_123 for user_456"
-```
-
-### 2. Metrics
-
-Aggregatable data points for identifying trends and health.
-
-- **Counters**: Total requests, error counts (`http_requests_total`)
-- **Gauges**: Queue depth, memory usage (`memory_usage_bytes`)
-- **Histograms**: Request latency distribution (`http_request_duration_seconds`)
-
-### 3. Distributed Tracing
-
-Tracking requests as they propagate through services.
-
-- **Trace ID**: Unique ID for the entire request chain
-- **Span ID**: Unique ID for a specific operation
-- **Context Propagation**: Passing IDs between services (e.g., W3C Trace Context)
-
-## Implementation Strategy
-
-### OpenTelemetry (OTel)
-
-Use OpenTelemetry as the vendor-neutral standard for collecting telemetry data.
-
-```text
-# Initialize OpenTelemetry SDK
-SDK.Configure({
-  TraceExporter: Console/OTLP,
-  Instrumentations: [Http, Database, Grpc]
-})
-SDK.Start()
-```
-
-### Health Checks
-
-Expose standard health endpoints:
-
-- `/health/live`: Is the process running? (Liveness)
-- `/health/ready`: Can it accept traffic? (Readiness)
-- `/health/startup`: Has it finished initializing? (Startup)
-
-## Alerting Best Practices
-
-- **Alert on Symptoms, not Causes**: "High Error Rate" (Symptom) vs "CPU High" (Cause).
-- **Golden Signals**: Latency, Traffic, Errors, Saturation.
-- **Actionable**: Every alert should require a specific human action.

package/.claude/guidelines/error-handling.md

@@ -1,413 +0,0 @@
-# Error Handling
-
-# Error Handling Strategy
-
-## Custom Error Classes
-
-```typescript
-class AppError extends Error {
-  constructor(
-    message: string,
-    public statusCode: number = 500,
-    public code: string = 'INTERNAL_ERROR',
-    public details?: unknown
-  ) {
-    super(message);
-    this.name = this.constructor.name;
-    Error.captureStackTrace(this, this.constructor);
-  }
-}
-
-class NotFoundError extends AppError {
-  constructor(resource: string, id: string) {
-    super(`${resource} with id ${id} not found`, 404, 'NOT_FOUND', { resource, id });
-  }
-}
-
-class ValidationError extends AppError {
-  constructor(message: string, details: unknown) {
-    super(message, 400, 'VALIDATION_ERROR', details);
-  }
-}
-
-// Usage
-if (!user) {
-  throw new NotFoundError('User', userId);
-}
-```
-
-## Never Swallow Errors
-
-```typescript
-// ❌ Silent failure - dangerous!
-try {
-  await criticalOperation();
-} catch (error) {
-  // Error ignored
-}
-
-// ✅ Log and handle appropriately
-try {
-  await criticalOperation();
-} catch (error) {
-  logger.error('Critical operation failed', { error });
-  throw error; // Or handle gracefully
-}
-```
-
-## Specific Error Messages
-
-```typescript
-// ❌ Not actionable
-throw new Error('Something went wrong');
-
-// ✅ Specific and actionable
-throw new ValidationError('Email must be a valid email address', {
-  field: 'email',
-  value: userInput.email
-});
-```
-
-## Centralized Error Handler
-
-```typescript
-// Express error middleware
-app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
-  if (err instanceof AppError) {
-    return res.status(err.statusCode).json({
-      error: {
-        message: err.message,
-        code: err.code,
-        details: err.details
-      }
-    });
-  }
-
-  // Log unexpected errors
-  console.error('Unexpected error:', err);
-
-  // Don't expose internal details
-  res.status(500).json({
-    error: {
-      message: 'Internal server error',
-      code: 'INTERNAL_ERROR'
-    }
-  });
-});
-```
-
-## Async Error Wrapper
-
-```typescript
-// Wrap async handlers to catch errors automatically
-const asyncHandler = (fn: RequestHandler) => {
-  return (req: Request, res: Response, next: NextFunction) => {
-    Promise.resolve(fn(req, res, next)).catch(next);
-  };
-};
-
-// Usage
-app.get('/users/:id', asyncHandler(async (req, res) => {
-  const user = await getUser(req.params.id);
-  res.json(user);
-}));
-```
-
-## Result Type Pattern
-
-```typescript
-type Result<T, E = Error> =
-  | { success: true; value: T }
-  | { success: false; error: E };
-
-function parseJSON<T>(json: string): Result<T, string> {
-  try {
-    return { success: true, value: JSON.parse(json) };
-  } catch {
-    return { success: false, error: 'Invalid JSON' };
-  }
-}
-
-// Usage - forces explicit error handling
-const result = parseJSON<User>(data);
-if (result.success) {
-  console.log(result.value.name);
-} else {
-  console.error(result.error);
-}
-```
-
-## Error Boundaries (React)
-
-```typescript
-class ErrorBoundary extends React.Component {
-  state = { hasError: false };
-
-  static getDerivedStateFromError(error: Error) {
-    return { hasError: true };
-  }
-
-  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
-    logger.error('UI Error', { error, errorInfo });
-  }
-
-  render() {
-    if (this.state.hasError) {
-      return <FallbackUI />;
-    }
-    return this.props.children;
-  }
-}
-```
-
-## Retry with Limits
-
-```typescript
-// ❌ Infinite retries
-while (true) {
-  try {
-    await operation();
-    break;
-  } catch (error) {
-    // Retry forever - exhausts resources
-  }
-}
-
-// ✅ Limited retries with backoff
-const maxRetries = 3;
-for (let i = 0; i < maxRetries; i++) {
-  try {
-    await operation();
-    break;
-  } catch (error) {
-    if (i === maxRetries - 1) throw error;
-    await sleep(Math.pow(2, i) * 1000); // Exponential backoff
-  }
-}
-```
-
-
----
-
-# Error Handling Basics
-
-## Throwing Errors
-
-Use `throw` to signal when something goes wrong.
-
-```pseudocode
-function divide(a, b):
-    if b == 0:
-        throw Error("Cannot divide by zero")
-    return a / b
-```
-
-## Try-Catch
-
-Use `try-catch` to handle errors gracefully.
-
-```pseudocode
-try:
-    result = divide(10, 0)
-    print(result)
-catch error:
-    print("Error:", error.message)
-    // Continue with fallback behavior
-```
-
-## Always Provide Error Messages
-
-Make error messages clear and actionable.
-
-```pseudocode
-// ❌ Bad: Vague error
-throw Error("Invalid")
-
-// ✅ Good: Specific error
-throw Error("Email must be a valid email address")
-
-// ✅ Good: Include context
-throw Error("User with ID " + userId + " not found")
-```
-
-## Async Error Handling
-
-Always use try-catch with async operations.
-
-```pseudocode
-async function loadUser(id):
-    try:
-        user = await fetchUser(id)
-        return user
-    catch error:
-        log("Failed to load user:", error)
-        throw error  // Re-throw if caller should know
-```
-
-## When to Catch Errors
-
-### Catch When You Can Handle It
-
-```pseudocode
-// ✅ Good: Can provide fallback
-async function getUserName(id):
-    try:
-        user = await fetchUser(id)
-        return user.name
-    catch error:
-        return "Unknown User"  // Fallback value
-```
-
-### Don't Catch If You Can't Handle
-
-```pseudocode
-// ❌ Bad: Catching but doing nothing
-try:
-    await criticalOperation()
-catch error:
-    // Empty catch - error lost!
-
-// ✅ Good: Let it propagate
-await criticalOperation()  // Caller will handle
-```
-
-## Validate Input Early
-
-Check for problems before they cause errors.
-
-```pseudocode
-function createUser(email, age):
-    // Validate inputs first
-    if email is empty:
-        throw Error("Email is required")
-
-    if not email.contains("@"):
-        throw Error("Email must be valid")
-
-    if age < 0:
-        throw Error("Age cannot be negative")
-
-    // Now proceed with creation
-    return { email: email, age: age }
-```
-
-## Logging Errors
-
-Always log errors for debugging.
-
-```pseudocode
-try:
-    await processPayment(orderId)
-catch error:
-    // Log with context
-    log("Payment processing failed:", {
-        orderId: orderId,
-        error: error.message,
-        timestamp: currentTime()
-    })
-    throw error
-```
-
-## Error Handling Patterns
-
-### Return Error Status
-
-```pseudocode
-function parseNumber(input):
-    num = parseInt(input)
-    if isNaN(num):
-        return null  // Indicate failure without throwing
-    return num
-
-// Usage
-result = parseNumber(userInput)
-if result is null:
-    print("Invalid number")
-else:
-    print("Number:", result)
-```
-
-### Return Success/Error Object
-
-```pseudocode
-function safeDivide(a, b):
-    if b == 0:
-        return { success: false, error: "Cannot divide by zero" }
-    return { success: true, data: a / b }
-
-// Usage
-result = safeDivide(10, 2)
-if result.success:
-    print("Result:", result.data)
-else:
-    print("Error:", result.error)
-```
-
-## Common Mistakes
-
-### Don't Swallow Errors
-
-```pseudocode
-// ❌ Bad: Error disappears
-try:
-    await importantOperation()
-catch error:
-    // Nothing here - error lost!
-
-// ✅ Good: Log at minimum
-try:
-    await importantOperation()
-catch error:
-    log("Operation failed:", error)
-    throw error  // Or handle appropriately
-```
-
-### Don't Use Errors for Flow Control
-
-```pseudocode
-// ❌ Bad: Using errors for normal logic
-try:
-    user = findUser(id)
-    // ...
-catch error:
-    // User not found - this is expected, not an error!
-
-// ✅ Good: Return null for expected cases
-user = findUser(id)
-if user is null:
-    print("User not found")
-    return
-```
-
-### Don't Throw Non-Error Objects
-
-```pseudocode
-// ❌ Bad
-throw "Something went wrong"  // String
-throw { code: 500 }           // Plain object
-
-// ✅ Good
-throw Error("Something went wrong")
-```
-
-## Best Practices
-
-1. **Fail fast** - Validate input early and throw immediately
-2. **Be specific** - Provide detailed, actionable error messages
-3. **Log errors** - Always log for debugging
-4. **Don't hide errors** - Let them propagate if you can't handle them
-5. **Clean up resources** - Close connections, files in finally blocks
-
-```pseudocode
-file = null
-try:
-    file = await openFile("data.txt")
-    await processFile(file)
-catch error:
-    log("File processing failed:", error)
-    throw error
-finally:
-    // Always runs, even if error thrown
-    if file is not null:
-        await file.close()
-```