bunsane 0.2.0 → 0.2.2

package/CLAUDE.md

@@ -0,0 +1,152 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+BunSane is an experimental TypeScript API framework for Bun using Entity-Component-System (ECS) architecture with PostgreSQL storage. It provides GraphQL Yoga integration with automatic schema generation from decorated services.
+
+**Stack**: Bun, TypeScript, PostgreSQL, GraphQL Yoga, GQLoom, Zod 4.x, Pino logging
+
+## Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Build (includes studio + typecheck)
+bun run build
+
+# Typecheck only
+tsc --noEmit
+
+# Tests (requires PostgreSQL)
+bun test                    # Unit + integration + GraphQL tests
+bun run test:unit           # Unit tests only
+bun run test:integration    # Integration tests only
+bun run test:graphql        # GraphQL schema tests only
+
+# Tests with PGlite (no PostgreSQL required)
+bun run test:pglite         # All tests with PGlite
+bun run test:pglite:unit    # Unit tests only with PGlite
+
+# E2E and stress tests
+bun run test:e2e            # HTTP tests (no DB needed)
+bun run test:stress         # Performance benchmarks
+
+# Run single test file
+bun test path/to/file.test.ts
+
+# Run tests matching pattern
+bun test --grep "pattern"
+```
+
+## Architecture
+
+### ECS Model
+- **Entities**: Generic containers with UUID, stored in `entities` table
+- **Components**: Data containers attached to entities, stored in `components` table with JSONB data
+- **Services**: Business logic with GraphQL operations
+
+### Core Classes
+
+**Entity** (`core/Entity.ts`):
+```typescript
+const entity = Entity.Create();
+entity.add(Position, { x: 0, y: 0 });    // Add component
+await entity.set(Position, { x: 10 });   // Update component
+const pos = await entity.get(Position);  // Get component data
+await entity.save();
+```
+
+**BaseComponent** (`core/components/BaseComponent.ts`):
+```typescript
+@Component
+class Position extends BaseComponent {
+    @CompData() x: number = 0;
+    @CompData({ indexed: true }) y: number = 0;  // Creates DB index
+}
+```
+
+**BaseArcheType** (`core/ArcheType.ts`):
+- Predefined entity templates with required components
+- Auto-generates GraphQL types and CRUD operations
+
+**Query** (`query/Query.ts`):
+```typescript
+const entities = await new Query()
+    .with(Position)                       // Require component
+    .with(Velocity, { filters: [...] })   // With filters
+    .populate()                           // Load all components
+    .limit(10)
+    .exec();
+```
+
+**BaseService** (`service/Service.ts`):
+```typescript
+class UserService extends BaseService {
+    @GraphQLOperation({ type: "Query", input: { id: t.id() }, output: User })
+    async getUser(input: { id: string }, ctx: GraphQLContext) { ... }
+}
+```
+
+### GraphQL
+
+- Schema generated automatically from decorated services and archetypes
+- Input types use Schema DSL (`gql/schema/index.ts`) via `t.` API
+- Operations: `@GraphQLOperation`, `@GraphQLSubscription`
+- Archetypes: `@ArcheTypeFunction` for computed fields
+
+### Database
+
+- PostgreSQL with Bun's native SQL driver (`Bun.SQL`)
+- Auto-migrations on startup for base tables
+- Component data stored as JSONB
+- Indexed fields create GIN indexes automatically
+
+### Caching
+
+- Multi-level cache: L1 (memory) + L2 (Redis)
+- `CacheManager.initialize(config)` is async - always await it
+- Strategies: write-through, write-invalidate
+- Cross-instance invalidation via Redis pub/sub
+
+### File Uploads
+
+- `UploadManager` handles file validation and storage
+- `S3StorageProvider` for S3-compatible storage (AWS, MinIO, R2)
+- REST: `handleUpload(req)` from `upload/RestUpload.ts`
+- GraphQL: `@Upload()` decorator
+
+## Critical Rules
+
+### Import Style
+**ALWAYS use relative imports** (`./`, `../`) for internal modules. Never use bare imports like `from "core/Logger"` - this breaks consumer typechecking.
+
+### Architecture Decisions
+- No Dependency Injection - uses singletons + global exports
+- Singleton access: `CacheManager.getInstance()`, `EntityManager.instance`, etc.
+- Services registered via `ServiceRegistry.register()`
+
+### Test Database Setup
+- Tests require `.env.test` with PostgreSQL config (or use PGlite mode)
+- `bunfig.toml` preloads `tests/setup.ts`
+- PGlite: `CREATE INDEX CONCURRENTLY` must check `process.env.USE_PGLITE`
+- PGlite JSONB: pass JS objects directly, never `JSON.stringify() + ::jsonb`
+
+## Directory Structure
+
+```
+core/           # ECS core: Entity, Component, ArcheType, App
+  cache/        # CacheManager, Redis, Memory caches
+  components/   # BaseComponent, decorators, registry
+  middleware/   # HTTP middleware (AccessLog, RequestId, SecurityHeaders)
+database/       # DatabaseHelper, SQL utilities
+gql/            # GraphQL generation, Schema DSL
+  schema/       # t.* Schema DSL for inputs
+query/          # Fluent Query builder, FilterBuilder
+service/        # BaseService, ServiceRegistry
+upload/         # File uploads, S3StorageProvider
+scheduler/      # Cron-style task scheduling
+tests/          # Unit, integration, GraphQL, E2E, stress tests
+```

package/gql/index.ts

@@ -114,6 +114,15 @@ const maskError = (error: any, message: string): GraphQLError => {
         }
     }
     
+    // Pass through known application-level GraphQL error codes
+    const isGQLError = (e: any): e is GraphQLError =>
+        e instanceof GraphQLError ||
+        (e !== null && typeof e === 'object' && 'extensions' in e && 'message' in e && typeof e.message === 'string');
+    const knownCodes = ['FORBIDDEN', 'NOT_FOUND', 'BAD_USER_INPUT', 'BAD_REQUEST'];
+    if (isGQLError(error) && knownCodes.includes(error.extensions?.code as string)) {
+        return error instanceof GraphQLError ? error : new GraphQLError(error.message, { extensions: error.extensions });
+    }
+
     if (process.env.NODE_ENV === 'production') {
         logger.error("GraphQL Error:", error);
         // Mask sensitive error details in production
@@ -124,7 +133,7 @@ const maskError = (error: any, message: string): GraphQLError => {
         });
     }
     // In development, return the original error
-    return error instanceof GraphQLError ? error : new GraphQLError(message, { originalError: error });
+    return isGQLError(error) ? (error instanceof GraphQLError ? error : new GraphQLError(error.message, { extensions: error.extensions })) : new GraphQLError(message, { originalError: error });
 };
 
 export interface YogaInstanceOptions {

package/gql/visitors/SchemaGeneratorVisitor.ts

@@ -255,21 +255,20 @@ export class SchemaGeneratorVisitor extends GraphVisitor {
             }
         }
         
-        // Handle output exactly like V1
-        const outputType = this.extractOutputType(output);
+        // Handle output
+        const outputType = this.extractOutputType(output, name);
         fieldDef += `: ${outputType}`;
-        
+
         return fieldDef;
     }
-    
+
     /**
-     * Extract output type exactly like V1
+     * Extract output type from operation metadata
      */
-    private extractOutputType(output: any): string {
+    private extractOutputType(output: any, operationName: string): string {
         if (typeof output === 'string') {
             return output;
         } else if (Array.isArray(output)) {
-            // Handle array of archetypes: [serviceAreaArcheType]
             const archetypeInstance = output[0];
             const typeName = this.getArchetypeTypeName(archetypeInstance);
             if (typeName) {
@@ -279,7 +278,6 @@ export class SchemaGeneratorVisitor extends GraphVisitor {
                 return '[Any]';
             }
         } else if (output instanceof BaseArcheType) {
-            // Handle single archetype instance: serviceAreaArcheType
             const typeName = this.getArchetypeTypeName(output);
             if (typeName) {
                 return typeName;
@@ -288,11 +286,16 @@ export class SchemaGeneratorVisitor extends GraphVisitor {
                 return 'Any';
             }
         } else if (typeof output === 'object' && output !== null) {
-            // Legacy object output format - V1 would generate an output type
-            // For now, return String as fallback (V1 would create outputName+"Output")
-            return 'String';
+            // Inline object output — generate a named GraphQL output type
+            const capitalizedName = operationName.charAt(0).toUpperCase() + operationName.slice(1);
+            const outputTypeName = `${capitalizedName}Output`;
+            if (!this.definedTypes.has(outputTypeName)) {
+                const outputTypeDef = `type ${outputTypeName} {\n${Object.entries(output).map(([k, v]) => `  ${k}: ${v}`).join('\n')}\n}\n`;
+                this.typeDefs += outputTypeDef;
+                this.definedTypes.add(outputTypeName);
+            }
+            return outputTypeName;
         } else {
-            // Default case when output is not specified - assume String (like V1)
             return 'String';
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bunsane",
-    "version": "0.2.0",
+    "version": "0.2.2",
     "author": {
         "name": "yaaruu"
     },

package/.claude/skills/update-memory.md

@@ -1,74 +0,0 @@
----
-name: update-memory
-description: Updating project memories with new information
-disable-model-invocation: false
-allowed-tools: Read, Grep
----
-
-# Update Memory Skill
-
-This skill helps you update Serena project memories with new or changed information.
-
-## When to Use
-
-Use `/update-memory` when you need to:
-- Record architectural decisions or patterns discovered during work
-- Update project conventions based on new practices
-- Document important findings from code exploration
-- Add new information to existing memory files
-- Create new memory files for undocumented aspects
-
-## Instructions
-
-1. **List existing memories** first to see what's available:
-   - Use `mcp__serena__list_memories` to see all memory files
-
-2. **Read the relevant memory** (if updating existing):
-   - Use `mcp__serena__read_memory` with the memory file name
-   - Understand the current content and structure
-
-3. **Determine the action**:
-   - **Update existing**: Use `mcp__serena__edit_memory` for targeted changes
-   - **Create new**: Use `mcp__serena__write_memory` for new topics
-   - **Delete obsolete**: Use `mcp__serena__delete_memory` (only if user confirms)
-
-4. **For updates**, use `edit_memory` with:
-   - `mode: "literal"` for exact string replacement
-   - `mode: "regex"` for pattern-based changes
-   - Keep the existing format and style
-
-5. **For new memories**, use descriptive kebab-case names:
-   - `project_overview` - General project info
-   - `architecture` - System architecture
-   - `code_style_and_conventions` - Coding standards
-   - `{feature}-implementation` - Feature-specific docs
-
-## Memory Naming Conventions
-
-| Pattern | Purpose |
-|---------|---------|
-| `project_overview` | High-level project description |
-| `architecture` | Directory structure, core concepts |
-| `code_style_and_conventions` | Formatting, naming, patterns |
-| `{topic}-decisions` | Architectural decisions on topic |
-| `{feature}-implementation` | How a feature works |
-| `suggested_commands` | Useful commands for the project |
-| `task_completion_checklist` | Steps to verify work is complete |
-
-## Example Usage
-
-```
-User: /update-memory Add that we use Bun for testing
-Assistant: [Lists memories, reads code_style_and_conventions, updates with new testing info]
-
-User: /update-memory Create a memory about the caching system
-Assistant: [Creates new memory file: caching-system.md with relevant information]
-```
-
-## Important Notes
-
-- Always read existing content before editing to preserve context
-- Use markdown format for memory content
-- Keep memories focused and organized
-- Ask for confirmation before deleting memories
-- After updating, summarize what was changed