pixelcrew 0.2.2 → 0.2.6

package/src/backend/analyzer/threat-analyzer.js

@@ -0,0 +1,122 @@
+/**
+ * PIXEL CREW — Threat Model Analyzer
+ * 
+ * Conducts automated, lightweight STRIDE threat modeling on application requirements
+ * to derive required security controls, boundaries, and validation guards.
+ */
+
+export class ThreatAnalyzer {
+  /**
+   * Derive threat vectors and security controls from requirements
+   * @param {object} requirements - SystemRequirementsModel
+   * @param {object} ast - Semantic Project AST
+   * @returns {object} ThreatModel
+   */
+  static analyze(requirements = {}, ast = {}) {
+    const threats = [];
+    const controls = [];
+    const boundaries = [];
+
+    const users = requirements.users || {};
+    const data = requirements.data || {};
+    const security = requirements.security || {};
+    const api = requirements.api || {};
+
+    // 1. Boundary: External Client -> API Layer
+    boundaries.push({
+      name: 'Internet to API Gateway',
+      trustLevel: 'untrusted-to-trusted',
+      controls: ['HTTPS/TLS', 'Strict Rate Limiting', 'Zod Schema Validation', 'CORS Policy', 'Security Headers']
+    });
+
+    // 2. Authentication & Credential Theft Threats
+    if (users.authentication) {
+      threats.push({
+        id: 'THR-AUTH-001',
+        asset: 'User Credentials & Session',
+        category: 'Spoofing',
+        threat: 'Credential theft, brute-force login attacks, or session hijacking',
+        severity: 'High',
+        mitigation: 'Argon2id password hashing, HTTP-only secure SameSite cookies, progressive delay brute-force limiter'
+      });
+      controls.push('session-cookie-hardening', 'auth-rate-limiting', 'password-hashing');
+    }
+
+    // 3. Multi-Tenant Cross-Tenant Access Threats
+    if (security.tenantIsolation) {
+      boundaries.push({
+        name: 'Tenant Isolation Boundary',
+        trustLevel: 'tenant-scoped',
+        controls: ['Organization Context Middleware', 'Database WHERE organization_id filter', 'Policy Guard']
+      });
+
+      threats.push({
+        id: 'THR-TENANT-001',
+        asset: 'Tenant Data Isolation',
+        category: 'Elevation of Privilege / Information Disclosure',
+        threat: 'Cross-tenant IDOR (Insecure Direct Object Reference) access',
+        severity: 'Critical',
+        mitigation: 'Mandatory tenant context derived strictly from authenticated session; query-level organizationId scoping'
+      });
+      controls.push('tenant-context-extractor', 'query-tenant-scoper', 'tenant-policy-guard');
+    }
+
+    // 4. Data Tampering & Injection Threats
+    threats.push({
+      id: 'THR-DATA-001',
+      asset: 'Relational Database State',
+      category: 'Tampering / Injection',
+      threat: 'SQL Injection or unvalidated payload pollution',
+      severity: 'Critical',
+      mitigation: 'ORM parameterized queries (Prisma), strict Zod input schemas with unknown key stripping'
+    });
+    controls.push('parameterized-queries', 'strict-input-validation');
+
+    // 5. Transaction Race Conditions / Financial Double-Spend
+    if (data.transactions) {
+      threats.push({
+        id: 'THR-RACE-001',
+        asset: 'Financial / Inventory State',
+        category: 'Tampering',
+        threat: 'Concurrent race conditions causing double-spend or duplicate execution',
+        severity: 'High',
+        mitigation: 'ACID database transactions ($transaction), Idempotency-Key header validation, optimistic locking'
+      });
+      controls.push('idempotency-middleware', 'atomic-transactions', 'optimistic-locking');
+    }
+
+    // 6. Denial of Service / Resource Exhaustion
+    if (api.rateLimiting) {
+      threats.push({
+        id: 'THR-DOS-001',
+        asset: 'API Availability',
+        category: 'Denial of Service',
+        threat: 'API endpoint flooding and resource exhaustion',
+        severity: 'Medium',
+        mitigation: 'Token Bucket / Sliding Window rate limiting per IP / User / Tenant'
+      });
+      controls.push('rate-limiter');
+    }
+
+    // 7. Audit Log Tampering
+    if (security.auditLogging) {
+      threats.push({
+        id: 'THR-AUDIT-001',
+        asset: 'Compliance & Audit Trail',
+        category: 'Repudiation',
+        threat: 'Undetected administrative modifications or unauthorized data access',
+        severity: 'Medium',
+        mitigation: 'Append-only structured audit logs with actorId, IP, timestamp, and target entity metadata'
+      });
+      controls.push('audit-logger');
+    }
+
+    return {
+      boundaries,
+      threats,
+      controls: Array.from(new Set(controls)),
+      threatScore: threats.filter(t => t.severity === 'Critical').length * 25 + threats.filter(t => t.severity === 'High').length * 15,
+      complianceStandard: security.sensitiveData ? 'SOC2 / HIPAA aligned' : 'Standard Web Security'
+    };
+  }
+}

package/src/backend/api/api-designer.js

@@ -0,0 +1,90 @@
+/**
+ * PIXEL CREW — API Designer Engine
+ * 
+ * Designs capability-driven REST/RPC API contracts with pagination (cursor vs offset),
+ * filtering, sorting, authentication, and HTTP status codes.
+ */
+
+export class APIDesigner {
+  /**
+   * Design API endpoints for entities and workflows
+   * @param {Array<object>} entities 
+   * @param {Array<object>} workflows 
+   * @param {object} architecture 
+   * @returns {Array<object>} API Endpoints Specification
+   */
+  static designEndpoints(entities = [], workflows = [], architecture = {}) {
+    const endpoints = [];
+    const isMultiTenant = Boolean(architecture.database?.tenantIsolation);
+    const pagination = architecture.performance?.paginationStrategy || 'cursor';
+
+    entities.forEach(ent => {
+      const slug = ent.plural ? ent.plural.toLowerCase() : `${ent.name.toLowerCase()}s`;
+      const basePath = `/api/v1/${slug}`;
+
+      // 1. List / Search Collection
+      endpoints.push({
+        id: `api-list-${slug}`,
+        name: `List ${ent.title || ent.name}`,
+        method: 'GET',
+        path: basePath,
+        entity: ent.name,
+        type: 'collection',
+        pagination,
+        authRequired: architecture.authentication?.required ?? false,
+        summary: `Retrieve paginated list of ${ent.plural || ent.name} with filtering and sorting`
+      });
+
+      // 2. Get by ID
+      endpoints.push({
+        id: `api-get-${slug}-id`,
+        name: `Get ${ent.name} by ID`,
+        method: 'GET',
+        path: `${basePath}/:id`,
+        entity: ent.name,
+        type: 'item',
+        authRequired: architecture.authentication?.required ?? false,
+        summary: `Retrieve a single ${ent.name} record by unique identifier`
+      });
+
+      // 3. Create Entity
+      endpoints.push({
+        id: `api-create-${slug}`,
+        name: `Create ${ent.name}`,
+        method: 'POST',
+        path: basePath,
+        entity: ent.name,
+        type: 'mutation',
+        authRequired: architecture.authentication?.required ?? false,
+        requiresIdempotency: architecture.database?.transactions ?? false,
+        summary: `Create a new ${ent.name} record`
+      });
+
+      // 4. Update Entity
+      endpoints.push({
+        id: `api-update-${slug}-id`,
+        name: `Update ${ent.name}`,
+        method: 'PATCH',
+        path: `${basePath}/:id`,
+        entity: ent.name,
+        type: 'mutation',
+        authRequired: architecture.authentication?.required ?? false,
+        summary: `Update existing ${ent.name} fields`
+      });
+
+      // 5. Delete Entity
+      endpoints.push({
+        id: `api-delete-${slug}-id`,
+        name: `Delete ${ent.name}`,
+        method: 'DELETE',
+        path: `${basePath}/:id`,
+        entity: ent.name,
+        type: 'mutation',
+        authRequired: architecture.authentication?.required ?? false,
+        summary: `Delete ${ent.name} record`
+      });
+    });
+
+    return endpoints;
+  }
+}

package/src/backend/api/error-contract.js

@@ -0,0 +1,132 @@
+/**
+ * PIXEL CREW — RFC 7807 Problem Details Error Contract
+ * 
+ * Standardized HTTP problem details for APIs (RFC 7807).
+ * Prevents leaking stack traces, database credentials, or internal file paths in production.
+ */
+
+export class ErrorContract {
+  /**
+   * Synthesize TypeScript RFC 7807 Error Classes & Middleware
+   * @returns {string} TypeScript Error Contract source
+   */
+  static generateErrorClasses() {
+    return `/**
+ * RFC 7807 Problem Details Standard Error System
+ * Auto-generated by Pixel Crew Backend Synthesizer
+ */
+
+export interface ProblemDetails {
+  type: string;
+  title: string;
+  status: number;
+  detail: string;
+  instance?: string;
+  invalidParams?: Array<{ name: string; reason: string }>;
+  timestamp: string;
+}
+
+export class AppError extends Error {
+  public readonly status: number;
+  public readonly type: string;
+  public readonly title: string;
+  public readonly detail: string;
+  public readonly invalidParams?: Array<{ name: string; reason: string }>;
+
+  constructor(status: number, title: string, detail: string, type: string = "about:blank", invalidParams?: Array<{ name: string; reason: string }>) {
+    super(detail);
+    this.name = this.constructor.name;
+    this.status = status;
+    this.title = title;
+    this.detail = detail;
+    this.type = type;
+    this.invalidParams = invalidParams;
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  public toProblemDetails(instance?: string): ProblemDetails {
+    return {
+      type: this.type,
+      title: this.title,
+      status: this.status,
+      detail: this.detail,
+      instance,
+      invalidParams: this.invalidParams,
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(detail: string = "Invalid request payload", invalidParams?: Array<{ name: string; reason: string }>) {
+    super(422, "Unprocessable Entity", detail, "https://api.pixelcrew.dev/errors/validation-error", invalidParams);
+  }
+}
+
+export class AuthenticationError extends AppError {
+  constructor(detail: string = "Authentication is required to access this resource") {
+    super(401, "Unauthorized", detail, "https://api.pixelcrew.dev/errors/authentication-error");
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(detail: string = "You do not have permission to perform this action") {
+    super(403, "Forbidden", detail, "https://api.pixelcrew.dev/errors/forbidden-error");
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string = "Resource", id?: string) {
+    const detail = id ? \`\${resource} with ID '\${id}' was not found\` : \`\${resource} was not found\`;
+    super(404, "Not Found", detail, "https://api.pixelcrew.dev/errors/not-found");
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(detail: string = "Resource already exists or conflicting state detected") {
+    super(409, "Conflict", detail, "https://api.pixelcrew.dev/errors/conflict");
+  }
+}
+
+export class RateLimitError extends AppError {
+  constructor(retryAfterSeconds: number = 60) {
+    super(429, "Too Many Requests", \`Rate limit exceeded. Please retry in \${retryAfterSeconds}s\`, "https://api.pixelcrew.dev/errors/rate-limit");
+  }
+}
+
+export class InternalServerError extends AppError {
+  constructor(detail: string = "An unexpected error occurred while processing your request") {
+    super(500, "Internal Server Error", detail, "https://api.pixelcrew.dev/errors/internal-server-error");
+  }
+}
+
+/**
+ * Global API Error Response Formatter
+ */
+export function formatErrorResponse(error: unknown, instancePath?: string): { status: number; body: ProblemDetails } {
+  if (error instanceof AppError) {
+    return {
+      status: error.status,
+      body: error.toProblemDetails(instancePath)
+    };
+  }
+
+  // Hide internal exception details in production
+  const isDev = process.env.NODE_ENV !== "production";
+  const message = error instanceof Error ? error.message : "Unknown error";
+  
+  return {
+    status: 500,
+    body: {
+      type: "https://api.pixelcrew.dev/errors/internal-server-error",
+      title: "Internal Server Error",
+      status: 500,
+      detail: isDev ? message : "An internal server error occurred",
+      instance: instancePath,
+      timestamp: new Date().toISOString()
+    }
+  };
+}
+`;
+  }
+}

package/src/backend/api/route-generator.js

@@ -0,0 +1,92 @@
+/**
+ * PIXEL CREW — Route Handler Generator
+ * 
+ * Synthesizes Next.js App Router API Route handlers (route.ts) that delegate cleanly
+ * to controllers/services, avoiding inline database logic or unvalidated inputs.
+ */
+
+export class RouteGenerator {
+  /**
+   * Generate Next.js App Router route.ts file for an entity collection
+   * @param {object} entity 
+   * @returns {string} Route handler code
+   */
+  static generateCollectionRoute(entity) {
+    const name = entity.name;
+    const lowerName = name.toLowerCase();
+
+    return `import { NextRequest, NextResponse } from "next/server";
+import { ${name}Controller } from "@/modules/${lowerName}/${lowerName}.controller";
+import { formatErrorResponse } from "@/shared/errors";
+
+const controller = new ${name}Controller();
+
+export async function GET(request: NextRequest) {
+  try {
+    const result = await controller.list(request);
+    return NextResponse.json(result, { status: 200 });
+  } catch (error) {
+    const { status, body } = formatErrorResponse(error, request.nextUrl.pathname);
+    return NextResponse.json(body, { status });
+  }
+}
+
+export async function POST(request: NextRequest) {
+  try {
+    const result = await controller.create(request);
+    return NextResponse.json(result, { status: 201 });
+  } catch (error) {
+    const { status, body } = formatErrorResponse(error, request.nextUrl.pathname);
+    return NextResponse.json(body, { status });
+  }
+}
+`;
+  }
+
+  /**
+   * Generate Next.js App Router route.ts file for an individual entity item [id]
+   * @param {object} entity 
+   * @returns {string} Route handler code
+   */
+  static generateItemRoute(entity) {
+    const name = entity.name;
+    const lowerName = name.toLowerCase();
+
+    return `import { NextRequest, NextResponse } from "next/server";
+import { ${name}Controller } from "@/modules/${lowerName}/${lowerName}.controller";
+import { formatErrorResponse } from "@/shared/errors";
+
+const controller = new ${name}Controller();
+
+export async function GET(request: NextRequest, { params }: { params: { id: string } }) {
+  try {
+    const result = await controller.getById(params.id, request);
+    return NextResponse.json(result, { status: 200 });
+  } catch (error) {
+    const { status, body } = formatErrorResponse(error, request.nextUrl.pathname);
+    return NextResponse.json(body, { status });
+  }
+}
+
+export async function PATCH(request: NextRequest, { params }: { params: { id: string } }) {
+  try {
+    const result = await controller.update(params.id, request);
+    return NextResponse.json(result, { status: 200 });
+  } catch (error) {
+    const { status, body } = formatErrorResponse(error, request.nextUrl.pathname);
+    return NextResponse.json(body, { status });
+  }
+}
+
+export async function DELETE(request: NextRequest, { params }: { params: { id: string } }) {
+  try {
+    await controller.delete(params.id, request);
+    return new NextResponse(null, { status: 204 });
+  } catch (error) {
+    const { status, body } = formatErrorResponse(error, request.nextUrl.pathname);
+    return NextResponse.json(body, { status });
+  }
+}
+`;
+  }
+}

package/src/backend/api/schema-generator.js

@@ -0,0 +1,64 @@
+/**
+ * PIXEL CREW — Zod Input/Output Schema Generator
+ * 
+ * Generates runtime Zod validation schemas for request bodies, query parameters,
+ * and response models. Enforces strict input stripping and type safety.
+ */
+
+export class SchemaGenerator {
+  /**
+   * Generate Zod schemas for an entity
+   * @param {object} entity 
+   * @returns {string} TypeScript Zod schema file content
+   */
+  static generateZodSchema(entity) {
+    const name = entity.name;
+    const fields = entity.fields || [];
+
+    let code = `import { z } from "zod";
+
+/**
+ * Domain Schema for ${name}
+ * Auto-generated by Pixel Crew Backend Synthesizer
+ */
+
+export const ${name}Schema = z.object({\n`;
+
+    fields.forEach(f => {
+      let zodType = 'z.string()';
+      if (f.type === 'number') zodType = 'z.number()';
+      else if (f.type === 'boolean') zodType = 'z.boolean()';
+      else if (f.type === 'datetime') zodType = 'z.string().datetime()';
+      else if (f.type === 'json') zodType = 'z.record(z.any())';
+
+      if (!f.required) {
+        zodType += '.optional()';
+      }
+
+      code += `  ${f.name}: ${zodType},\n`;
+    });
+
+    code += `});
+
+export const Create${name}Schema = ${name}Schema.omit({\n  id: true,\n  createdAt: true,\n  updatedAt: true\n});
+
+export const Update${name}Schema = Create${name}Schema.partial();
+
+export const ${name}QuerySchema = z.object({
+  page: z.coerce.number().min(1).default(1),
+  limit: z.coerce.number().min(1).max(100).default(20),
+  cursor: z.string().optional(),
+  search: z.string().optional(),
+  sortBy: z.string().default("createdAt"),
+  sortOrder: z.enum(["asc", "desc"]).default("desc")
+});
+
+export type ${name}DTO = z.infer<typeof ${name}Schema>;
+export type Create${name}DTO = z.infer<typeof Create${name}Schema>;
+export type Update${name}DTO = z.infer<typeof Update${name}Schema>;
+export type ${name}QueryDTO = z.infer<typeof ${name}QuerySchema>;
+`;
+
+    return code;
+  }
+}

package/src/backend/architecture/adr-generator.js

@@ -0,0 +1,62 @@
+/**
+ * PIXEL CREW — Architecture Decision Record (ADR) Generator
+ * 
+ * Generates standard Markdown Architecture Decision Records (docs/architecture/ADR-*.md)
+ * making generated systems explainable, transparent, and maintainable by humans.
+ */
+
+import { TradeoffAnalyzer } from './tradeoff-analyzer.js';
+
+export class ADRGenerator {
+  /**
+   * Generate complete set of ADR Markdown files
+   * @param {object} spec - ArchitectureSpecification
+   * @returns {object} Map of filename -> Markdown content
+   */
+  static generateADRs(spec = {}) {
+    const tradeoffs = TradeoffAnalyzer.analyzeTradeoffs(spec);
+    const files = {};
+    const dateStr = new Date().toISOString().split('T')[0];
+
+    tradeoffs.forEach((t, index) => {
+      const num = String(index + 1).padStart(3, '0');
+      const slug = t.decision.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '').slice(0, 40);
+      const filename = `docs/architecture/ADR-${num}-${slug}.md`;
+
+      const md = `# ADR-${num}: ${t.decision}
+
+**Status:** Accepted  
+**Date:** ${dateStr}  
+**Context / Reason:** ${t.reason}  
+
+---
+
+## 1. Decision
+
+We will adopt:
+> **${t.decision}**
+
+## 2. Benefits & Positives
+
+${t.benefits.map(b => `- **Positive**: ${b}`).join('\n')}
+
+## 3. Costs & Overhead
+
+${t.costs.map(c => `- **Tradeoff**: ${c}`).join('\n')}
+
+## 4. Alternatives Considered
+
+${t.alternatives.map(a => `- ${a}`).join('\n')}
+
+## 5. Risk & Mitigation Strategy
+
+- **Identified Risk:** ${t.risk}
+- **Mitigation:** ${t.mitigation}
+`;
+
+      files[filename] = md;
+    });
+
+    return files;
+  }
+}

package/src/backend/architecture/architecture-reasoner.js

@@ -0,0 +1,119 @@
+/**
+ * PIXEL CREW — Backend Architecture Reasoner
+ * 
+ * Synthesizes a comprehensive ArchitectureSpecification from requirements and complexity analysis.
+ * Adheres strictly to the principle of "Minimum necessary complexity + Maximum necessary reliability".
+ */
+
+import { RequirementAnalyzer } from '../analyzer/requirement-analyzer.js';
+import { ComplexityAnalyzer } from '../analyzer/complexity-analyzer.js';
+import { ThreatAnalyzer } from '../analyzer/threat-analyzer.js';
+
+export class ArchitectureReasoner {
+  /**
+   * Derive an architecture specification from prompt & AST
+   * @param {string} prompt 
+   * @param {object} ast 
+   * @returns {object} ArchitectureSpecification
+   */
+  static reason(prompt = '', ast = {}) {
+    const requirements = RequirementAnalyzer.analyze(prompt, ast);
+    const complexity = ComplexityAnalyzer.analyze(requirements, ast);
+    const threatModel = ThreatAnalyzer.analyze(requirements, ast);
+
+    // 1. Architecture Topology Selection
+    let style = 'modular-monolith';
+    if (complexity.tier === 'high') {
+      style = 'distributed-modular-services';
+    } else if (requirements.backgroundJobs.required || complexity.tier === 'medium') {
+      style = 'modular-monolith-with-workers';
+    }
+
+    // 2. Database Selection
+    const dbType = requirements.application.expectedScale === 'high' || requirements.security.tenantIsolation
+      ? 'postgresql'
+      : 'postgresql'; // default to postgresql with sqlite dev fallback
+
+    // 3. Cache Selection
+    const cacheRequired = requirements.performance.caching;
+    const cacheTech = (complexity.tier === 'high' || requirements.backgroundJobs.required) ? 'redis' : 'in-memory-lru';
+
+    // 4. Queue Selection
+    const queueRequired = requirements.backgroundJobs.required;
+    const queueTech = queueRequired ? (cacheTech === 'redis' ? 'bullmq' : 'in-memory-async-queue') : 'none';
+
+    // 5. Auth Strategy
+    const authStrategy = requirements.users.authentication ? 'session-cookie' : 'none';
+    const authRoles = requirements.users.roles ? 'rbac' : 'none';
+
+    // 6. Observability
+    const logging = true;
+    const metrics = complexity.tier !== 'low';
+    const tracing = complexity.tier === 'high';
+
+    const architectureSpec = {
+      style,
+      tier: complexity.tier,
+      complexityScore: complexity.totalScore,
+
+      api: {
+        style: 'rest',
+        versioning: true,
+        routeStructure: 'app-router-modular',
+        errorHandling: 'rfc-7807',
+        validation: 'zod'
+      },
+
+      database: {
+        type: dbType,
+        orm: 'prisma',
+        transactions: requirements.data.transactions,
+        softDelete: requirements.data.softDelete,
+        auditLog: requirements.data.auditLog,
+        tenantIsolation: requirements.security.tenantIsolation
+      },
+
+      cache: {
+        required: cacheRequired,
+        technology: cacheTech,
+        ttlSeconds: 300
+      },
+
+      queue: {
+        required: queueRequired,
+        technology: queueTech,
+        tasks: requirements.backgroundJobs.tasks
+      },
+
+      authentication: {
+        required: requirements.users.authentication,
+        strategy: authStrategy
+      },
+
+      authorization: {
+        required: requirements.users.roles,
+        strategy: authRoles
+      },
+
+      security: {
+        rateLimiting: requirements.api.rateLimiting,
+        tenantIsolation: requirements.security.tenantIsolation,
+        sensitiveData: requirements.security.sensitiveData,
+        controls: threatModel.controls
+      },
+
+      observability: {
+        logging,
+        metrics,
+        tracing,
+        structuredJson: true
+      },
+
+      requirements,
+      complexity,
+      threatModel
+    };
+
+    return architectureSpec;
+  }
+}