insforge 0.3.1

package/docs/deprecated/insforge-debug.md

@@ -0,0 +1,65 @@
+# Insforge Debug Guide
+
+## When Your API Code Fails
+
+**Start here** → `get-instructions` and `get-backend-metadata` (understand system state)
+**Read docs** → `get-db-api`, `get-auth-api`, `get-storage-api` (read ALL of them)
+**Check table** → `get-table-schema` with your table name
+**Test endpoint** → Use curl with exact API format from docs
+
+## Critical Rule: Read Documentation First
+
+Before debugging, you MUST read all documentation to understand how the API works.
+
+## Common API Issues
+
+**Table created but API fails** → Check field names match schema exactly
+**Array required** → PostgREST requires POST requests as arrays `[{...}]`
+**Foreign key error** → Parent record must exist before child
+**Permission denied** → Write operations need `Authorization: Bearer <accessToken>`
+**JWSError** → JWT token expired or invalid - user needs to login again
+**PATCH increment fails** → PostgREST doesn't support SQL expressions like `count + 1`
+
+## Debug Workflow
+
+1. **Always** call `get-backend-metadata` first
+2. Read the relevant API documentation completely
+3. Check your table schema matches your API calls
+4. Test with curl using exact format from docs
+5. Verify response matches documentation
+
+### Example Debug Tests
+
+```bash
+# Test GET endpoint
+# Windows PowerShell: use curl.exe
+curl -X GET http://localhost:7130/api/database/records/your_table \
+  -H "Authorization: Bearer YOUR_TOKEN" | jq .
+
+# Test POST with array format
+# Mac/Linux
+curl -X POST http://localhost:7130/api/database/records/your_table \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Prefer: return=representation' \
+  -d '[{"field": "value"}]' | jq .
+
+# Windows PowerShell (use curl.exe) - different quotes for nested JSON
+curl.exe -X POST http://localhost:7130/api/database/records/your_table \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Prefer: return=representation" \
+  -d '[{\"field\": \"value\"}]' | jq .
+```
+
+## Key Rules
+
+- Backend runs on port 7130
+- **READ operations**: No authentication required
+- **WRITE operations**: Need `Authorization: Bearer <accessToken>` header
+- POST requests must be arrays `[{...}]`
+- System tables (prefixed with _) need special APIs
+- No escaped characters in JSON
+- Login/register returns JWT tokens directly in `accessToken` field
+
+**Remember**: MCP creates the structure, but you must follow API documentation exactly to use it.

package/docs/deprecated/insforge-instructions.md

@@ -0,0 +1,124 @@
+# Insforge OSS Instructions
+
+## What Insforge OSS Does
+
+Backend-as-a-service with database, authentication, and file storage. 
+
+**Key Concept**: InsForge replaces your traditional backend - implement business logic by calling database operations directly. Instead of building API endpoints, use our database API as your application's backend.
+
+## 🚨 Project Setup
+
+**Create your app in a NEW directory, not inside `insforge/`**
+
+The `insforge/` directory is the BaaS platform. Your app should live elsewhere:
+```
+~/projects/
+├── insforge/      # ← BaaS platform (don't work here)
+└── my-app/        # ← Your new app (work here)
+```
+
+## When to Use Tools
+
+**MUST DO FIRST** → Download project rules: `download-project-rules`
+**Start here** → `get-backend-metadata` (shows current database state)
+**Need docs** → `get-db-api`, `get-auth-api`, or `get-storage-api`
+**Create table** → `create-table` with explicit schema
+**Work with data** → Use database API endpoints directly
+
+## Critical Rule: 
+**MUST DO FIRST** → Call`download-project-rules` to download project ruless
+
+## Critical Rule: Check Metadata First
+
+Before ANY database operation, call `get-backend-metadata` to get the current database state.
+
+## Standard Workflow
+
+1. **Always** call `get-backend-metadata` first
+2. Check `get-instructions` if unfamiliar with the system
+3. Create tables with `create-table` if needed
+4. Use database API to insert/query/update/delete records
+5. Call `get-backend-metadata` again to verify changes
+
+## Key Rules
+
+- Frequently check `get-instructions` and `get-backend-metadata`
+- Always define explicit table schemas (no assumptions)
+- Every table gets auto ID, created_at, updated_at fields
+- **Database operations require**: JWT token (Authorization: Bearer header)
+- **API keys are for MCP testing** (use tokens for production)
+- File uploads work automatically with multipart/form-data
+
+## Authentication Requirements
+
+### Database Operations Need Authentication Token:
+1. **JWT Token**: `Authorization: Bearer your-jwt-token` - Authenticates the user
+
+**Important Note about API Keys:**
+- The `x-api-key` header is ONLY used for MCP (Model Context Protocol) testing
+- Production applications should NEVER use API keys
+- Always use JWT tokens from user/admin authentication for real applications
+
+Without the Bearer token, you'll get "permission denied" errors when trying to insert, update, or delete records.
+
+### Getting Authentication:
+```bash
+# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
+# 1. First login to get JWT token
+curl -X POST http://localhost:7130/api/auth/admin/sessions \
+  -H "Content-Type: application/json" \
+  -d "{\"email\":\"admin@example.com\",\"password\":\"your-password\"}"
+
+# Response includes token: {"accessToken": "eyJ...", "user": {...}}
+
+# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
+# 2. Use the auth token for database operations
+curl -X POST http://localhost:7130/api/database/records/products \
+  -H "Authorization: Bearer eyJ..." \
+  -H "Content-Type: application/json" \
+  -d "[{\"name\": \"Product\", \"price\": 99.99}]"
+```
+
+## Example: Comment Upvoting Feature
+
+- Check current tables: `get-backend-metadata`
+- Create comment_votes table: `create-table` with user_id, comment_id, vote_type fields
+- Frontend upvote action: `POST /api/database/records/comment_votes` with vote data
+- Frontend display scores: `GET /api/database/records/comment_votes?comment_id=eq.123` to count votes
+- No separate backend needed - frontend calls InsForge database API directly
+
+
+## Critical Rule: Test API Endpoints with curl
+
+After creating or modifying any API endpoint, always test it with curl to verify it works correctly.
+
+**Note:** Avoid special characters (!,$,`,\) in curl command data - they can cause bash interpretation issues. Use simple text for testing:
+
+```bash
+# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
+# Example: Test creating a record (requires JWT token)
+curl -X POST http://localhost:7130/api/database/records/posts \
+  -H "x-api-key: your-api-key" \
+  -H "Authorization: Bearer your-jwt-token" \
+  -H "Content-Type: application/json" \
+  -d '[{\"title\": \"Test Post\", \"content\": \"Test content\"}]'
+
+# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
+# Example: Test querying records (requires both API key and JWT token)
+curl http://localhost:7130/api/database/records/posts?id=eq.123 \
+  -H "x-api-key: your-api-key" \
+  -H "Authorization: Bearer your-jwt-token"
+
+# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
+# Example: Test authentication
+curl -X POST http://localhost:7130/api/auth/users \
+  -H "Content-Type: application/json" \
+  -d '{\"email\": \"test@example.com\", \"password\": \"testpass123\"}'
+```
+
+Always include:
+- **Both headers for database operations**: x-api-key AND Authorization: Bearer token
+- Correct HTTP method (GET, POST, PATCH, DELETE)
+- Valid JSON payload for POST/PATCH requests (remember: POST requires array format `[{...}]`)
+- Query parameters for filtering GET requests
+- Prefer: return=representation header if you want to see the created/updated records

package/docs/deprecated/insforge-project.md

@@ -0,0 +1,118 @@
+---
+description: Insforge AI Development Rules - Essential guidelines for BaaS platform development
+globs: 
+alwaysApply: true
+---
+
+# Insforge Development Rules
+
+## Core Identity
+You are an exceptional software developer using Insforge Backend to assist building the product. Make it visually stunning, content-rich, professional-grade UIs.
+
+## 🔴 MANDATORY: cURL Test at EVERY Step
+
+**For AI Agents: Test with cURL repeatedly throughout development:**
+
+1. **Before coding** → Test endpoint exists, check response format
+2. **During coding** → Test when confused about any API behavior  
+3. **After coding** → Test complete user journey end-to-end
+4. **When debugging** → Test to see actual vs expected responses
+
+```bash
+# Mac/Linux
+curl -X POST http://localhost:7130/api/[endpoint] \
+  -H 'Content-Type: application/json' \
+  -d '[{"key": "value"}]' | jq .
+
+# Windows PowerShell (use curl.exe) - different quotes for nested JSON
+curl.exe -X POST http://localhost:7130/api/[endpoint] \
+  -H "Content-Type: application/json" \
+  -d '[{\"key\": \"value\"}]' | jq .
+```
+
+**You WILL get it wrong without testing. Test early, test often.**
+
+## Critical Architecture Points
+
+When in doubt, read instructions documents again.
+
+## 🚨 CRUD Operations - PostgREST NOT RESTful
+### PostgREST Database API Behavior
+
+**Critical PostgREST Rules:**
+
+1. **POST requires array**: `[{...}]` even for single record
+2. **Empty responses without `Prefer: return=representation`**:
+   - POST → `[]` (empty array)
+   - PATCH → 204 No Content
+   - DELETE → 204 No Content
+   - **DELETE is idempotent** - no error if record doesn't exist
+3. **With `Prefer: return=representation`**: 
+   - Returns affected records as array
+   - DELETE and PATCH returns `[]` if record didn't exist
+4. **Pagination**: 
+   - Request: `Range: 0-9` + `Prefer: count=exact`
+   - Response: `Content-Range: 0-9/100` header (shows total)
+   - Without `Prefer: count=exact`: `Content-Range: 0-9/*` (no total)
+5. **Query syntax**: `?field=operator.value`
+   - `?id=eq.123` (equals)
+   - `?age=gt.30` (greater than)
+   - `?name=like.*john*` (pattern match)
+
+## Auth Operations:
+
+### 🚨 IMPORTANT: Correct Auth Endpoints
+- **Register**: `POST /api/auth/users` - Create new user account
+- **Login**: `POST /api/auth/sessions` - Authenticate existing user
+- **Admin Login**: `POST /api/auth/admin/sessions` - Admin authentication
+- **Current User**: `GET /api/auth/sessions/current` - Get authenticated user info
+- `/api/auth/sessions/current` returns `{"user": {...}}` - nested structure
+- Store JWT tokens and include as `Authorization: Bearer {accessToken}` header
+- **Note**: Login/register returns `{accessToken, user}` with JWT token
+
+### Regular API Response Format
+
+**⚠️ IMPORTANT: Frontend Error Handling**
+- **PARSE** backend responses and display user-friendly messages
+- **DO NOT** show raw API responses directly to users
+- **TRANSFORM** error details into readable, actionable messages
+
+- Success: Data directly (object/array)
+- Error: `{error, message, statusCode}`
+- Empty POST/PATCH/DELETE: Add `Prefer: return=representation`
+
+### 🚨 Storage API Rules
+- **Upload Methods**: 
+  - **PUT** `/api/storage/buckets/{bucket}/objects/{filename}` - Upload with specific key
+  - **POST** `/api/storage/buckets/{bucket}/objects` - Upload with auto-generated key
+- **Authentication**: Upload operations require `Authorization: Bearer {accessToken}`
+- **Generate Unique Filenames**: Use POST for auto-generated keys to prevent overwrites
+- **Multipart Form**: Use FormData for file uploads
+- **URL Format**: Storage returns **ABSOLUTE URLs** (e.g., `http://localhost:7130/api/storage/buckets/{bucket}/objects/{filename}`)
+  - **IMPORTANT**: URLs are complete and ready to use - no need to prepend host or path
+  - Use the URL directly in `<img src>` or fetch requests
+
+## 🔥 Test EVERY Endpoint
+
+**Backend runs on port 7130**
+
+Always test with cURL before UI integration:
+- Include `Authorization: Bearer {accessToken}` for auth
+- Add `Prefer: return=representation` to see created data
+- Windows PowerShell: use curl.exe
+
+```bash
+# Mac/Linux
+curl -X POST http://localhost:7130/api/database/records/posts \
+  -H 'Authorization: Bearer TOKEN' \
+  -H 'Content-Type: application/json' \
+  -H 'Prefer: return=representation' \
+  -d '[{"user_id": "from-localStorage", "caption": "Test"}]'
+
+# Windows PowerShell (use curl.exe) - different quotes for nested JSON
+curl.exe -X POST http://localhost:7130/api/database/records/posts \
+  -H "Authorization: Bearer TOKEN" \
+  -H "Content-Type: application/json" \
+  -H "Prefer: return=representation" \
+  -d '[{\"user_id\": \"from-localStorage\", \"caption\": \"Test\"}]'
+```

package/docs/deprecated/insforge-storage-api.md

@@ -0,0 +1,279 @@
+# Insforge OSS Storage API Documentation
+
+## API Basics
+
+**Base URL:** `http://localhost:7130`  
+**Authentication:**
+- **Upload operations (PUT/POST/DELETE):** Requires `Authorization: Bearer <token>` header
+- **Download from public buckets:** No authentication required
+- **List/manage buckets:** Requires authentication 
+- **API keys are for MCP testing** (use tokens for production)
+**System:** Bucket-based storage with public/private access control
+
+### 🔴 CRITICAL: URL Format
+**Storage returns ABSOLUTE URLs** that are ready to use directly:
+- Response `url` field contains complete URL: `http://localhost:7130/api/storage/buckets/{bucket}/objects/{filename}`
+- **DO NOT prepend host or modify the URL** - use it exactly as returned
+- URLs work directly in `<img src>`, `<video src>`, or fetch requests
+- Example: `"url": "http://localhost:7130/api/storage/buckets/avatars/objects/user123.jpg"`
+
+
+## Bucket Operations (Use MCP Tools)
+
+### Available MCP Tools
+1. **create-bucket** - Create bucket (`bucketName`, `isPublic`: true by default)
+2. **list-buckets** - List all buckets
+3. **delete-bucket** - Delete bucket
+
+## Object Operations (Use REST API)
+
+### Base URL
+`/api/storage/buckets/:bucketName/objects/:objectKey`
+
+### Upload Object with Specific Key
+**PUT** `/api/storage/buckets/:bucketName/objects/:objectKey`
+
+
+Send object as multipart/form-data:
+```javascript
+const formData = new FormData();
+formData.append('file', fileObject);
+```
+
+Returns:
+```json
+{
+  "bucket": "test-images",
+  "key": "test.txt", 
+  "size": 30,
+  "mimeType": "text/plain",
+  "uploadedAt": "2025-07-18T04:32:13.801Z",
+  "url": "http://localhost:7130/api/storage/buckets/test-images/objects/test.txt"
+}
+```
+
+Example curl:
+```bash
+# Windows PowerShell: use curl.exe
+curl -X PUT http://localhost:7130/api/storage/buckets/avatars/objects/user123.jpg \
+  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
+  -F "file=@/path/to/image.jpg"
+```
+
+### Upload Object with Auto-Generated Key
+**POST** `/api/storage/buckets/:bucketName/objects`
+
+Request:
+```bash
+# Windows PowerShell: use curl.exe
+curl -X POST http://localhost:7130/api/storage/buckets/posts/objects \
+  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
+  -F "file=@/path/to/image.jpg"
+```
+
+Response:
+```json
+{
+  "bucket": "avatars",
+  "key": "image-1737546841234-a3f2b1.jpg", 
+  "size": 15234,
+  "mimeType": "image/jpeg",
+  "uploadedAt": "2025-07-18T04:32:13.801Z",
+  "url": "http://localhost:7130/api/storage/buckets/avatars/objects/image-1737546841234-a3f2b1.jpg"
+}
+```
+
+### Download Object
+**GET** `/api/storage/buckets/:bucketName/objects/:objectKey`
+
+Returns the actual object content with appropriate content-type headers.
+**Note:** Public buckets allow downloads without authentication.
+
+Example response: Raw object content (not JSON wrapped)
+
+### List Objects
+**GET** `/api/storage/buckets/:bucketName/objects`
+
+Query parameters:
+- `prefix` - Filter by key prefix
+- `limit` - Max results (default: 100)
+- `offset` - Pagination offset
+
+Returns:
+```json
+{
+  "bucketName": "test-images",
+  "prefix": null,
+  "objects": [
+    {
+      "bucket": "test-images",
+      "key": "test.txt",
+      "size": 30,
+      "mimeType": "text/plain",
+      "uploadedAt": "2025-07-18T04:32:13.801Z",
+      "url": "http://localhost:7130/api/storage/buckets/test-images/objects/test.txt"
+    }
+  ],
+  "pagination": {
+    "limit": 100,
+    "offset": 0,
+    "total": 1
+  },
+  "nextActions": "You can use PUT /api/storage/buckets/:bucketName/objects/:objectKey to upload with a specific key, or POST /api/storage/buckets/:bucketName/objects to upload with auto-generated key, and GET /api/storage/buckets/:bucketName/objects/:objectKey to download an object."
+}
+```
+
+Pagination headers:
+- `X-Total-Count`: Total number of objects
+- `X-Page`: Current page number
+- `X-Page-Size`: Number of items per page
+
+Example curl:
+```bash
+# Windows PowerShell: use curl.exe
+curl -X GET "http://localhost:7130/api/storage/buckets/avatars/objects?limit=10&prefix=users/" \
+  -H "Authorization: Bearer <token>"
+```
+
+### Delete Object
+**DELETE** `/api/storage/buckets/:bucketName/objects/:objectKey`
+
+Returns:
+```json
+{
+  "message": "Object deleted successfully"
+}
+```
+
+Example curl:
+```bash
+# Windows PowerShell: use curl.exe
+curl -X DELETE http://localhost:7130/api/storage/buckets/avatars/objects/user123.jpg \
+  -H "Authorization: Bearer <token>"
+```
+
+### Update Bucket
+**PATCH** `/api/storage/buckets/:bucketName`
+
+Request body:
+```json
+{ "isPublic": true }
+```
+
+Returns:
+```json
+{
+  "message": "Bucket visibility updated",
+  "bucket": "test-images",
+  "isPublic": false,
+  "nextActions": "Bucket is now PRIVATE - authentication is required to access objects."
+}
+```
+
+Example curl:
+```bash
+# Mac/Linux
+curl -X PATCH http://localhost:7130/api/storage/buckets/avatars \
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{"isPublic": true}'
+
+# Windows PowerShell (use curl.exe) - different quotes needed for nested JSON
+curl.exe -X PATCH http://localhost:7130/api/storage/buckets/avatars \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{\"isPublic\": true}'
+```
+
+## Database Integration
+
+### Option 1: Upload with Specific Key (PUT)
+```javascript
+// Step 1: Upload object with known key
+const formData = new FormData();
+formData.append('file', file);
+const upload = await fetch('/api/storage/buckets/images/objects/avatar.jpg', {
+  method: 'PUT',
+  headers: { 'Authorization': `Bearer ${token}` },
+  body: formData
+});
+
+// Step 2: Store metadata
+const records = [{
+  userId: 'user123',
+  image: await upload.json()  // Store object metadata
+}];
+await fetch('/api/database/profiles', {
+  method: 'POST',
+  headers: { 
+    'Authorization': `Bearer ${token}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify(records)
+});
+```
+
+### Option 2: Upload with Auto-Generated Key (POST)
+```javascript
+// Step 1: Upload object with auto-generated key
+const formData = new FormData();
+formData.append('file', file);
+const upload = await fetch('/api/storage/buckets/images/objects', {
+  method: 'POST',
+  headers: { 'Authorization': `Bearer ${token}` },
+  body: formData
+});
+const fileData = await upload.json();
+
+// Step 2: Store metadata with generated key
+const records = [{
+  userId: 'user123',
+  image: fileData  // Contains auto-generated key
+}];
+await fetch('/api/database/profiles', {
+  method: 'POST',
+  headers: { 
+    'Authorization': `Bearer ${token}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify(records)
+});
+```
+
+## Error Response Format
+
+All error responses follow this format:
+```json
+{
+  "error": "ERROR_CODE",
+  "message": "Human-readable error message",
+  "statusCode": 400,
+  "nextActions": "Suggested action to resolve the error"
+}
+```
+
+Example error:
+```json
+{
+  "error": "BUCKET_NOT_FOUND",
+  "message": "Bucket 'nonexistent' does not exist",
+  "statusCode": 404,
+  "nextActions": "Create the bucket first"
+}
+```
+
+## Important Rules
+
+1. **Object Operations**
+   - Upload uses multipart/form-data
+   - Database stores metadata only
+   - Use `json` column type for object metadata
+
+2. **Bucket Names**
+   - Must be valid identifiers
+   - Cannot start with underscore
+
+3. **Remember**
+   - Bucket management uses MCP tools
+   - Object operations use REST API
+   - All operations need API key