insforge 0.3.3 → 1.2.10

package/backend/tests/unit/response.test.ts

@@ -0,0 +1,58 @@
+import { successResponse, errorResponse, paginatedResponse } from '../../src/utils/response';
+import { Response } from 'express';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+describe('Response Utilities', () => {
+  let res: Partial<Response>;
+
+  beforeEach(() => {
+    res = {
+      status: vi.fn().mockReturnThis(),
+      json: vi.fn().mockReturnThis(),
+      setHeader: vi.fn().mockReturnThis(),
+    };
+  });
+
+  it('successResponse returns data with correct status', () => {
+    const data = { message: 'ok' };
+    successResponse(res as Response, data, 201);
+    expect(res.status).toHaveBeenCalledWith(201);
+    expect(res.json).toHaveBeenCalledWith(data);
+  });
+
+  it('errorResponse returns error with correct status', () => {
+    const error = 'ERROR';
+    const message = 'Something went wrong';
+    errorResponse(res as Response, error, message, 400, 'Retry');
+    expect(res.status).toHaveBeenCalledWith(400);
+    expect(res.json).toHaveBeenCalledWith({
+      error,
+      message,
+      statusCode: 400,
+      nextActions: 'Retry',
+    });
+  });
+
+  it('paginatedResponse sets headers and status correctly', () => {
+    const data = [1, 2, 3];
+    const total = 10;
+    const offset = 0;
+
+    paginatedResponse(res as Response, data, total, offset);
+
+    expect(res.setHeader).toHaveBeenCalledWith('Content-Range', '0-2/10');
+    expect(res.setHeader).toHaveBeenCalledWith('Preference-Applied', 'count=exact');
+    expect(res.status).toHaveBeenCalledWith(206); // partial content
+    expect(res.json).toHaveBeenCalledWith(data);
+  });
+
+  it('paginatedResponse returns 200 when all items returned', () => {
+    const data = [1, 2, 3];
+    const total = 3;
+    const offset = 0;
+
+    paginatedResponse(res as Response, data, total, offset);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+  });
+});

package/backend/tests/unit/sql-parser.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { parseSQLStatements } from '../../src/utils/sql-parser';
+
+describe('parseSQLStatements', () => {
+  it('splits multiple statements by semicolon', () => {
+    const sql = `
+      SELECT * FROM users;
+      INSERT INTO users (name) VALUES ('John');
+      DELETE FROM users WHERE id = 1;
+    `;
+    const result = parseSQLStatements(sql);
+    expect(result).toEqual([
+      'SELECT * FROM users',
+      "INSERT INTO users (name) VALUES ('John')",
+      'DELETE FROM users WHERE id = 1',
+    ]);
+  });
+
+  it('ignores line comments', () => {
+    const sql = `
+      -- This is a comment
+      SELECT * FROM users; -- Inline comment
+    `;
+    const result = parseSQLStatements(sql);
+    // Parser returns the statement with comments filtered out
+    expect(result).toHaveLength(1);
+    expect(result[0]).toContain('SELECT * FROM users');
+  });
+
+  it('ignores block comments', () => {
+    const sql = `
+      /* Block comment */
+      SELECT * FROM users;
+      /* Another comment */
+    `;
+    const result = parseSQLStatements(sql);
+    // Parser returns the statement with comments filtered out
+    expect(result).toHaveLength(1);
+    expect(result[0]).toContain('SELECT * FROM users');
+  });
+
+  it('handles semicolons inside string literals', () => {
+    const sql = `INSERT INTO messages (text) VALUES ('Hello; World')`;
+    const result = parseSQLStatements(sql);
+    // Parser includes the trailing semicolon
+    expect(result).toEqual([`INSERT INTO messages (text) VALUES ('Hello; World')`]);
+  });
+
+  it('throws error on empty input', () => {
+    expect(() => parseSQLStatements('')).toThrow();
+  });
+
+  it('returns empty array for comments-only SQL', () => {
+    const sql = `
+      -- Only comment
+      /* Another comment */
+    `;
+    const result = parseSQLStatements(sql);
+    // Parser filters out comment-only content
+    expect(result).toEqual([]);
+  });
+
+  it('trims statements and removes empty results', () => {
+    const sql = `
+      SELECT * FROM users;
+      -- comment
+      INSERT INTO users (id) VALUES (1);
+    `;
+    const result = parseSQLStatements(sql);
+    expect(result.length).toBeGreaterThan(0);
+    expect(result[0]).toContain('SELECT * FROM users');
+    expect(result[result.length - 1] || result[0]).toContain('INSERT INTO users');
+  });
+});

package/backend/tests/unit/uuid.test.ts

@@ -0,0 +1,21 @@
+import { describe, test, expect } from 'vitest';
+import { generateUUID } from '../../src/utils/utils';
+
+describe('generateUUID', () => {
+  const uuidV4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+  test('returns a string', () => {
+    const uuid = generateUUID();
+    expect(typeof uuid).toBe('string');
+  });
+
+  test('returns a valid UUID v4', () => {
+    const uuid = generateUUID();
+    expect(uuid).toMatch(uuidV4Regex);
+  });
+
+  test('generates unique UUIDs on multiple calls', () => {
+    const uuids = new Set(Array.from({ length: 10 }, () => generateUUID()));
+    expect(uuids.size).toBe(10);
+  });
+});

package/backend/tests/unit/validations.test.ts

@@ -0,0 +1,80 @@
+import {
+  validateEmail,
+  validateIdentifier,
+  isValidIdentifier,
+  validateTableName,
+  getIdentifierErrorMessage,
+  escapeSqlLikePattern,
+  escapeRegexPattern,
+} from '../../src/utils/validations';
+import { AppError } from '../../src/api/middleware/error';
+import { describe, test, expect } from 'vitest';
+
+describe('Validations Utils', () => {
+  describe('validateEmail', () => {
+    test('valid email returns true', () => {
+      expect(validateEmail('test@example.com')).toBe(true);
+    });
+
+    test('invalid email returns false', () => {
+      expect(validateEmail('invalid-email')).toBe(false);
+    });
+  });
+
+  describe('validateIdentifier', () => {
+    test('valid identifier returns true', () => {
+      expect(validateIdentifier('my_table')).toBe(true);
+    });
+
+    test('empty identifier throws AppError', () => {
+      expect(() => validateIdentifier('')).toThrow(AppError);
+    });
+
+    test('identifier with quotes throws AppError', () => {
+      expect(() => validateIdentifier('bad"identifier')).toThrow(AppError);
+    });
+  });
+
+  describe('isValidIdentifier', () => {
+    test('valid identifier returns true', () => {
+      expect(isValidIdentifier('column1')).toBe(true);
+    });
+
+    test('invalid identifier returns false', () => {
+      expect(isValidIdentifier('')).toBe(false);
+      expect(isValidIdentifier('bad"identifier')).toBe(false);
+    });
+  });
+
+  describe('validateTableName', () => {
+    test('valid table name returns true', () => {
+      expect(validateTableName('users')).toBe(true);
+    });
+
+    test('table name starting with _ throws AppError', () => {
+      expect(() => validateTableName('_internal')).toThrow(AppError);
+    });
+  });
+
+  describe('getIdentifierErrorMessage', () => {
+    test('empty identifier returns proper message', () => {
+      expect(getIdentifierErrorMessage('')).toContain('cannot be empty');
+    });
+
+    test('bad identifier returns proper message', () => {
+      expect(getIdentifierErrorMessage('bad"identifier')).toContain('cannot contain quotes');
+    });
+  });
+
+  describe('escapeSqlLikePattern', () => {
+    test('escapes % and _ and \\', () => {
+      expect(escapeSqlLikePattern('50%_test\\')).toBe('50\\%\\_test\\\\');
+    });
+  });
+
+  describe('escapeRegexPattern', () => {
+    test('escapes regex metacharacters', () => {
+      expect(escapeRegexPattern('test.file(1)')).toBe('test\\.file\\(1\\)');
+    });
+  });
+});

package/backend/tsconfig.json

@@ -16,7 +16,7 @@
     "moduleResolution": "node",
     "resolveJsonModule": true,
     "allowSyntheticDefaultImports": true,
-    "types": ["node"]
+    "types": ["node","vitest" ]
   },
   "include": ["src/**/*", "../shared-schemas/src/**/*"],
   "exclude": ["node_modules", "dist"]

package/backend/vitest.config.ts

@@ -1,6 +1,16 @@
 import { defineConfig } from 'vitest/config';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 export default defineConfig({
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+      '@insforge/shared-schemas': path.resolve(__dirname, '../shared-schemas/src'),
+    },
+  },
   test: {
     environment: 'node',
     globals: true,
@@ -10,6 +20,7 @@ export default defineConfig({
       reporter: ['text', 'json', 'html'],
       exclude: ['node_modules/', 'dist/', 'frontend/', 'tests/', '**/*.d.ts', '**/*.config.*'],
     },
+
     testTimeout: 10000,
     // Run tests sequentially to avoid database conflicts
     pool: 'forks',

package/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "insforge",
+  "version": "1.0.0",
+  "description": "Official InsForge plugin for Claude Code with skills, templates, and commands for building full-stack applications with InsForge BaaS",
+  "author": {
+    "name": "InsForge Team"
+  },
+  "repository": "https://github.com/InsForge/InsForge",
+  "homepage": "https://insforge.com",
+  "keywords": [
+    "insforge",
+    "baas",
+    "backend-as-a-service",
+    "postgresql",
+    "postgrest",
+    "full-stack",
+    "react",
+    "database",
+    "storage",
+    "edge-functions",
+    "authentication"
+  ],
+  "license": "MIT"
+}

package/claude-plugin/README.md

@@ -0,0 +1,133 @@
+# InsForge Claude Plugin
+
+Official Claude Code plugin for building with InsForge.
+
+## What's Included
+
+**Skill: `insforge-schema-patterns`**
+- Social graph patterns (follows, likes)
+- Nested comments (self-referential)
+- Multi-tenant patterns
+- Best practices for foreign keys, indexes, and RLS
+
+This skill automatically activates when you're designing database schemas with Claude.
+
+## Installation
+
+### Method 1: From Marketplace (Recommended)
+
+The easiest way to install:
+
+```bash
+# In Claude Code, run:
+/plugin marketplace add InsForge/InsForge
+
+# Then browse available plugins:
+/plugin
+
+# Select "insforge" to install
+```
+
+### Method 2: Direct Install
+
+```bash
+# Create user plugins directory if needed
+mkdir -p ~/.claude/plugins/user
+
+# Clone the repository
+git clone https://github.com/InsForge/InsForge.git
+
+# Create symlink
+ln -s "$(pwd)/InsForge/claude-plugin" ~/.claude/plugins/user/insforge
+
+# Verify installation
+ls -la ~/.claude/plugins/user/insforge/
+```
+
+### Method 3: Local Development
+
+For contributing or testing local changes:
+
+```bash
+# Navigate to your local InsForge repo
+cd /path/to/your/InsForge
+
+# Create user plugins directory
+mkdir -p ~/.claude/plugins/user
+
+# Symlink your local development version
+ln -s "$(pwd)/claude-plugin" ~/.claude/plugins/user/insforge
+
+# Verify
+ls -la ~/.claude/plugins/user/insforge/
+```
+
+## Usage
+
+Once installed, the skill automatically activates when you ask Claude about database design:
+
+```
+You: "I need to build a social media app with follows and likes"
+
+Claude: [Automatically loads insforge-schema-patterns skill]
+"I'll use the Social Graph pattern from InsForge best practices..."
+```
+
+No special commands needed - Claude knows when to use it!
+
+## What's a Skill?
+
+Skills are folders with instructions that Claude automatically loads when relevant. They're like giving Claude domain expertise.
+
+## Verification
+
+Check if the plugin is installed correctly:
+
+```bash
+# Check plugin installation
+ls -la ~/.claude/plugins/user/insforge/
+
+# Should show:
+# .claude-plugin/
+# skills/
+# README.md
+
+# Check the skill is present
+cat ~/.claude/plugins/user/insforge/skills/insforge-schema-patterns/SKILL.md
+
+# Should display database schema patterns
+```
+
+## Test the Plugin
+
+In Claude Code, ask a database design question:
+
+```
+"Help me design a database for a social media app with follows and likes"
+```
+
+Claude should automatically load the `insforge-schema-patterns` skill and provide expert schema patterns with RLS policies, indexes, and SDK examples.
+
+## Troubleshooting
+
+**Plugin not found:**
+```bash
+# Remove old symlink if exists
+rm ~/.claude/plugins/user/insforge
+
+# Recreate with absolute path
+ln -s /absolute/path/to/InsForge/claude-plugin ~/.claude/plugins/user/insforge
+```
+
+**Skill not loading:**
+1. Verify SKILL.md has proper frontmatter (name and description)
+2. Restart Claude Code
+3. Ask a database design question explicitly
+
+## Contributing
+
+Want to add more skills? Check the [main InsForge repository](https://github.com/InsForge/InsForge).
+
+## License
+
+MIT

package/claude-plugin/skills/insforge-schema-patterns/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: insforge-schema-patterns
+description: Database schema patterns for InsForge including social graphs, e-commerce, content publishing, and multi-tenancy with RLS policies. Use when designing data models with relationships, foreign keys, or Row Level Security.
+---
+
+# InsForge Schema Patterns
+
+Expert patterns for designing PostgreSQL schemas optimized for InsForge's PostgREST backend.
+
+## Pattern 1: Social Graph (Follows)
+
+**Use when:** Building social features like Twitter, Instagram, LinkedIn connections
+
+**Schema:**
+```sql
+CREATE TABLE follows (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  follower_id UUID REFERENCES users(id) ON DELETE CASCADE,
+  following_id UUID REFERENCES users(id) ON DELETE CASCADE,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  UNIQUE(follower_id, following_id)
+);
+
+-- Index for fast lookups
+CREATE INDEX idx_follows_follower ON follows(follower_id);
+CREATE INDEX idx_follows_following ON follows(following_id);
+
+-- RLS: Users can read all follows but only create their own
+ALTER TABLE follows ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Anyone can read follows" ON follows
+  FOR SELECT USING (true);
+
+CREATE POLICY "Users can follow others" ON follows
+  FOR INSERT
+  TO authenticated
+  WITH CHECK (uid() = follower_id);
+
+CREATE POLICY "Users can unfollow" ON follows
+  FOR DELETE
+  TO authenticated
+  USING (uid() = follower_id);
+```
+
+**Query with InsForge SDK:**
+```javascript
+// Get users I follow with their profiles
+const { data: following } = await client.database
+  .from('follows')
+  .select('*, following:following_id(id, nickname, avatar_url, bio)')
+  .eq('follower_id', currentUserId);
+
+// Get my followers
+const { data: followers } = await client.database
+  .from('follows')
+  .select('*, follower:follower_id(id, nickname, avatar_url, bio)')
+  .eq('following_id', currentUserId);
+
+// Check if user1 follows user2
+const { data: isFollowing } = await client.database
+  .from('follows')
+  .select()
+  .eq('follower_id', user1Id)
+  .eq('following_id', user2Id)
+  .single();
+
+// Follow a user
+await client.database
+  .from('follows')
+  .insert([{ follower_id: currentUserId, following_id: targetUserId }]);
+```
+
+---
+
+## Pattern 2: Likes (Many-to-Many Junction Table)
+
+**Use when:** Users can like posts, comments, or other content
+
+**Schema:**
+```sql
+CREATE TABLE likes (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
+  post_id UUID REFERENCES posts(id) ON DELETE CASCADE,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  UNIQUE(user_id, post_id)  -- Prevent duplicate likes
+);
+
+CREATE INDEX idx_likes_post ON likes(post_id);
+CREATE INDEX idx_likes_user ON likes(user_id);
+
+ALTER TABLE likes ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Anyone can read likes" ON likes
+  FOR SELECT USING (true);
+
+CREATE POLICY "Users can like posts" ON likes
+  FOR INSERT
+  TO authenticated
+  WITH CHECK (uid() = user_id);
+
+CREATE POLICY "Users can unlike their likes" ON likes
+  FOR DELETE
+  TO authenticated
+  USING (uid() = user_id);
+```
+
+**Query with InsForge SDK:**
+```javascript
+// Get post with like count and whether current user liked it
+const { data: post } = await client.database
+  .from('posts')
+  .select(`
+    *,
+    likes(count),
+    user_like:likes!inner(id, user_id)
+  `)
+  .eq('id', postId)
+  .eq('user_like.user_id', currentUserId)
+  .single();
+
+// Like a post
+await client.database
+  .from('likes')
+  .insert([{ user_id: currentUserId, post_id: postId }]);
+
+// Unlike a post
+await client.database
+  .from('likes')
+  .delete()
+  .eq('user_id', currentUserId)
+  .eq('post_id', postId);
+```
+
+---
+
+## Pattern 3: Nested Comments (Self-Referential)
+
+**Use when:** Building comment threads, nested replies
+
+**Schema:**
+```sql
+CREATE TABLE comments (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  post_id UUID REFERENCES posts(id) ON DELETE CASCADE,
+  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
+  parent_comment_id UUID REFERENCES comments(id) ON DELETE CASCADE,
+  content TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX idx_comments_post ON comments(post_id);
+CREATE INDEX idx_comments_parent ON comments(parent_comment_id);
+
+ALTER TABLE comments ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Anyone can read comments" ON comments
+  FOR SELECT USING (true);
+
+CREATE POLICY "Authenticated users can comment" ON comments
+  FOR INSERT
+  TO authenticated
+  WITH CHECK (uid() = user_id);
+
+CREATE POLICY "Users can edit their comments" ON comments
+  FOR UPDATE
+  TO authenticated
+  USING (uid() = user_id)
+  WITH CHECK (uid() = user_id);
+
+CREATE POLICY "Users can delete their comments" ON comments
+  FOR DELETE
+  TO authenticated
+  USING (uid() = user_id);
+```
+
+**Query with InsForge SDK:**
+```javascript
+// Get top-level comments with author info
+const { data: comments } = await client.database
+  .from('comments')
+  .select('*, author:user_id(nickname, avatar_url)')
+  .eq('post_id', postId)
+  .is('parent_comment_id', null)
+  .order('created_at', { ascending: false });
+
+// Get replies to a comment
+const { data: replies } = await client.database
+  .from('comments')
+  .select('*, author:user_id(nickname, avatar_url)')
+  .eq('parent_comment_id', commentId)
+  .order('created_at', { ascending: true });
+```
+
+---
+
+## Pattern 4: Multi-Tenant (Organization Scoped)
+
+**Use when:** Building SaaS apps where data is scoped to organizations/workspaces
+
+**Schema:**
+```sql
+CREATE TABLE organizations (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE TABLE organization_members (
+  organization_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
+  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
+  role TEXT NOT NULL CHECK (role IN ('owner', 'admin', 'member')),
+  joined_at TIMESTAMPTZ DEFAULT NOW(),
+  PRIMARY KEY (organization_id, user_id)
+);
+
+CREATE TABLE projects (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  organization_id UUID REFERENCES organizations(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- RLS: Users can only see projects in their organizations
+ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Users see org projects" ON projects
+  FOR SELECT
+  TO authenticated
+  USING (
+    organization_id IN (
+      SELECT organization_id
+      FROM organization_members
+      WHERE user_id = uid()
+    )
+  );
+
+CREATE POLICY "Admins can create projects" ON projects
+  FOR INSERT
+  TO authenticated
+  WITH CHECK (
+    organization_id IN (
+      SELECT organization_id
+      FROM organization_members
+      WHERE user_id = uid()
+      AND role IN ('owner', 'admin')
+    )
+  );
+```
+
+---
+
+## Best Practices
+
+1. **Always add indexes** on foreign key columns for performance
+2. **Use UNIQUE constraints** on junction tables to prevent duplicates
+3. **Enable RLS** on all user-facing tables
+4. **Use ON DELETE CASCADE** for automatic cleanup
+5. **Foreign key expansion** in SDK uses the syntax: `table:column(fields)`
+6. **Count aggregations** use: `table(count)`
+7. **Filter nested tables** with: `nested_table!inner()` for inner join behavior
+
+## Common Mistakes to Avoid
+
+- ❌ Forgetting indexes on foreign keys → Slow queries
+- ❌ Not using UNIQUE on junction tables → Duplicate likes/follows
+- ❌ Missing RLS policies → Data leaks
+- ❌ Using `.single()` on queries that might return multiple rows → Errors
+- ❌ Not wrapping INSERT data in arrays → PostgREST error