cohere-db 1.0.0

package/templates/memory/checkpoint-patterns.md

@@ -0,0 +1,224 @@
+# Memory & Checkpoint Patterns
+
+> AUTO-GENERATED by cohere. Universal patterns with agent-specific notes.
+
+## Directory Structure
+
+```
+.ai/
+├── memory/
+│   ├── checkpoints/          # Session checkpoints
+│   │   └── checkpoint-{timestamp}.json
+│   ├── accumulated-learnings.md  # Cross-session knowledge
+│   ├── edge-cases.md         # Documented edge cases
+│   └── session-history.md    # Recent session notes
+```
+
+---
+
+## Checkpoint Pattern (Universal)
+
+```typescript
+interface AgentCheckpoint {
+  timestamp: string;
+  sessionId: string;
+  schemaVersion: string;
+  currentTask?: TaskContext;
+  discoveredPatterns: DiscoveredPattern[];
+  pendingQueries: PendingQuery[];
+  agentMemory: Record<string, unknown>;
+}
+
+interface TaskContext {
+  taskId: string;
+  status: 'in_progress' | 'paused' | 'completed';
+  lastAction?: string;
+  progress: number;
+}
+```
+
+### Save Checkpoint (Universal)
+```typescript
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+async function saveCheckpoint(
+  outputDir: string,
+  checkpoint: AgentCheckpoint
+): Promise<string> {
+  const filename = `checkpoint-${Date.now()}.json`;
+  const filepath = path.join(outputDir, 'memory', 'checkpoints', filename);
+  
+  await fs.mkdir(path.dirname(filepath), { recursive: true });
+  await fs.writeFile(filepath, JSON.stringify(checkpoint, null, 2));
+  
+  return filepath;
+}
+```
+
+### Restore Checkpoint (Universal)
+```typescript
+async function restoreLatestCheckpoint(
+  outputDir: string
+): Promise<AgentCheckpoint | null> {
+  const checkpointsDir = path.join(outputDir, 'memory', 'checkpoints');
+  
+  try {
+    const files = await fs.readdir(checkpointsDir);
+    const checkpointFiles = files
+      .filter(f => f.startsWith('checkpoint-') && f.endsWith('.json'))
+      .sort();
+    
+    if (checkpointFiles.length === 0) {
+      return null;
+    }
+    
+    const latest = checkpointFiles[checkpointFiles.length - 1];
+    const filepath = path.join(checkpointsDir, latest);
+    const content = await fs.readFile(filepath, 'utf-8');
+    
+    return JSON.parse(content) as AgentCheckpoint;
+  } catch (error) {
+    return null;
+  }
+}
+```
+
+---
+
+> [!NOTE|CLAUDE]
+> **CLAUDE CODE**: Built-in memory hooks available
+> - `claude mem save <content>` - Save to memory
+> - `claude mem list` - List memories
+> - Auto-loads `~/.Claude/CLAUDE.md` for user-level persistence
+> - Checkpoints integrate with `claude session restore`
+
+> [!NOTE|CODEX]
+> **CODEX CRITICAL**: No auto-memory persistence
+> - MUST explicitly save checkpoints
+> - MUST explicitly restore at session start:
+>   ```
+>   Read the .ai/memory/checkpoints directory. Find the latest checkpoint and restore context.
+>   ```
+> - AGENTS.md is NOT auto-loaded (see constraints.md)
+
+> [!NOTE|ANTIGRAVITY]
+> **ANTIGRAVITY**: Checkpoint coordination for parallel agents
+> - Share checkpoints via shared storage
+> - Use naming: `checkpoint-{agentId}-{timestamp}.json`
+> - Lock files to prevent race conditions
+
+> [!NOTE|XCODE]
+> **XCODE 26.3**: Different persistence model
+> - Use `ProjectDescription.plist` for project context
+> - Use `.xcuserdatad` for user-specific state
+> - Swift PM plugins don't persist across IDE sessions
+
+---
+
+## Session Handoff Pattern
+
+```typescript
+interface SessionHandoff {
+  fromSession: string;
+  toSession: string;
+  timestamp: string;
+  context: {
+    schemaHash: string;
+    pendingActions: string[];
+    discoveredRelationships: string[];
+    importantConstraints: string[];
+  };
+  summary: string;
+}
+
+async function createHandoff(
+  outputDir: string,
+  handoff: SessionHandoff
+): Promise<void> {
+  const handoffPath = path.join(outputDir, 'memory', 'handoff.json');
+  
+  await fs.writeFile(handoffPath, JSON.stringify(handoff, null, 2));
+}
+```
+
+---
+
+## Usage Examples
+
+### Claude Code
+```bash
+# Auto-save to memory
+claude mem save "Key pattern discovered: Use organization_id for tenant isolation"
+
+# Manual checkpoint
+npm run checkpoint:save
+```
+
+### Codex
+```bash
+# MUST be explicit
+codex exec "node -e 'import(\"./memory/checkpoint\").then(m => m.saveCheckpoint(\".ai\", {...}))'"
+```
+
+### Antigravity (Parallel)
+```bash
+# Agent A
+checkpoint:save --agent=a --shared=/shared/memory/
+
+# Agent B
+checkpoint:restore --agent=b --shared=/shared/memory/
+```
+
+---
+
+## Best Practices (All Agents)
+
+| Practice | Why |
+|----------|-----|
+| Checkpoint every 5-10 min | Prevent context loss |
+| Include schema hash | Detect schema drift |
+| Track pending queries | Resume incomplete work |
+| Document discoveries | Accumulate knowledge |
+
+---
+
+## Cross-Session Learning
+
+```typescript
+interface LearnedPattern {
+  timestamp: string;
+  category: 'query' | 'schema' | 'relationship' | 'edge-case';
+  description: string;
+  sqlExample?: string;
+  usageCount: number;
+}
+
+async function accumulateLearning(
+  outputDir: string,
+  learning: LearnedPattern
+): Promise<void> {
+  const memoryPath = path.join(outputDir, 'memory', 'accumulated-learnings.md');
+  
+  const newEntry = `
+## ${learning.timestamp}
+
+**Category:** ${learning.category}
+
+**Description:** ${learning.description}
+
+${learning.sqlExample ? `**Example:**
+\`\`\`sql
+${learning.sqlExample}
+\`\`\`` : ''}
+
+**Usage Count:** ${learning.usageCount}
+`;
+  
+  const existing = await fs.readFile(memoryPath, 'utf-8').catch(() => '');
+  await fs.writeFile(memoryPath, existing + newEntry);
+}
+```
+
+---
+*Pattern version: 1.0.0*

package/templates/query-template.md

@@ -0,0 +1,35 @@
+---
+name: {{name}}
+description: {{description}}
+category: {{category}}
+---
+
+# {{name}}
+
+{{description}}
+
+## Query
+
+\`\`\`sql
+{{query}}
+\`\`\`
+
+## Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+{{#each parameters}}
+| `{{name}}` | `{{type}}` | {{description}} |
+{{/each}}
+
+## Returns
+
+{{returns}}
+
+## Use Case
+
+{{useCase}}
+
+## Notes
+
+{{notes}}

package/templates/state/CURRENT_STATE.md

@@ -0,0 +1,117 @@
+# Current State
+
+> AUTO-GENERATED by cohere. This is the active progress snapshot.
+
+## Session Status
+
+| Field | Value |
+|-------|-------|
+| **Status** | `{status}` |
+| **Last Updated** | `{lastUpdated}` |
+| **Session ID** | `{sessionId}` |
+| **Agent ID** | `{agentId}` |
+
+---
+
+## Progress
+
+### Completed Steps
+
+```
+1. ✅ Step 1 - Completed at {timestamp1}
+2. ✅ Step 2 - Completed at {timestamp2}
+3. ✅ Step 3 - Completed at {timestamp3}
+```
+
+### Current Step
+
+> **Status**: {currentStatus}
+
+```
+{currentStepDescription}
+```
+
+### Remaining Steps
+
+```
+4. ⏳ Step 4 - Pending
+5. ⏳ Step 5 - Pending
+6. 📋 Step 6 - Planned
+```
+
+---
+
+## Work Queue
+
+### Pending Tasks
+
+| Priority | Task | Status | Dependencies |
+|----------|------|--------|--------------|
+| High | Task 1 | Pending | None |
+| Medium | Task 2 | Pending | Task 1 |
+| Low | Task 3 | Pending | Task 1, Task 2 |
+
+### Blocked Tasks
+
+| Task | Blocker | Since |
+|------|---------|-------|
+| Task A | Dependency B | {date} |
+| Task B | Dependency C | {date} |
+
+---
+
+## Known Issues
+
+| Issue | Severity | Workaround |
+|-------|----------|------------|
+| Issue 1 | Critical | Workaround A |
+| Issue 2 | Minor | Workaround B |
+
+---
+
+## Variables & State
+
+### Active Variables
+
+```json
+{activeVariablesJson}
+```
+
+### Schema Modifications
+
+| Table | Modification | Timestamp |
+|-------|--------------|-----------|
+| users | Column added | {timestamp} |
+| orders | Index created | {timestamp} |
+
+---
+
+## Checkpoints
+
+| Checkpoint | Timestamp | Status |
+|------------|-----------|--------|
+| checkpoint-001 | {timestamp} | Valid |
+| checkpoint-002 | {timestamp} | Valid |
+
+---
+
+## Quick Actions
+
+```bash
+# Resume from current state
+db-ai handoff --resume {sessionId}
+
+# Record progress
+db-ai handoff --record
+
+# List available sessions
+db-ai handoff --list
+```
+
+---
+
+> [!NOTE|ALL]
+> **MULTI-AGENT**: When handoff to new agent:
+> 1. Read this file first
+> 2. Check `.ai/context/SESSION_CONTEXT.json` for full state
+> 3. Review `.ai/decisions/` for context

package/templates/test-templates/edge-cases.test.md

@@ -0,0 +1,230 @@
+# Edge Case Test Templates
+
+> AUTO-GENERATED by cohere. Copy to `.ai/test-templates/` and customize.
+
+---
+
+## Universal Test Patterns
+
+These tests work across all agents (Claude, Codex, Antigravity, Xcode).
+
+### Empty Result Set
+```typescript
+test('SELECT returns empty array when no rows match', async () => {
+  const result = await query(
+    'SELECT * FROM users WHERE email = $1',
+    ['nonexistent@example.com']
+  );
+  expect(result).toEqual([]);
+});
+```
+
+### Soft Delete Handling
+```typescript
+test('SELECT excludes soft-deleted records by default', async () => {
+  const result = await query(
+    'SELECT * FROM orders WHERE organization_id = $1',
+    [orgId]
+  );
+  expect(result.rows.every(r => r.deleted_at === null)).toBe(true);
+});
+```
+
+---
+
+> [!NOTE|CLAUDE]
+> Claude Code: Tests run via `npm test`. Use `claude test` for agent-specific testing.
+
+> [!NOTE|CODEX]
+> **CODEX SPECIFIC**: Codex requires explicit test file inclusion:
+> ```
+> I have edge case tests in .ai/test-templates/. Run them to verify.
+> ```
+> Tests won't run unless explicitly invoked.
+
+> [!NOTE|ANTIGRAVITY]
+> Antigravity: Parallel agents should run tests independently, share results via `.ai/memory/test-results/`.
+
+> [!NOTE|XCODE]
+> Xcode: Tests go in `Tests/` directory. Use XCTest framework.
+
+---
+
+## 1. CRUD Edge Cases
+
+### Empty Result Set
+```typescript
+test('SELECT returns empty array when no rows match', async () => {
+  const result = await query(
+    'SELECT * FROM users WHERE email = $1',
+    ['nonexistent@example.com']
+  );
+  expect(result).toEqual([]);
+});
+```
+
+### Single Row Edge Cases
+```typescript
+test('INSERT fails on duplicate primary key', async () => {
+  await expect(query(
+    'INSERT INTO users (id, email) VALUES ($1, $2)',
+    [existingId, 'new@example.com']
+  )).rejects.toThrow('duplicate_key');
+});
+
+test('UPDATE modifies correct row with unique constraint', async () => {
+  const result = await query(
+    'UPDATE users SET email = $1 WHERE id = $2',
+    ['updated@example.com', targetId]
+  );
+  expect(result.rowCount).toBe(1);
+});
+```
+
+---
+
+## 2. Foreign Key Edge Cases
+
+### Orphaned Records
+```typescript
+test('SELECT with JOIN skips orphaned foreign keys', async () => {
+  const result = await query(`
+    SELECT o.*, u.email 
+    FROM orders o
+    JOIN users u ON o.user_id = u.id
+    WHERE o.organization_id = $1
+  `, [orgId]);
+  // Only returns orders with valid user_id
+  expect(result.rows.every(r => r.user_id !== null)).toBe(true);
+});
+```
+
+### Cascade Delete
+```typescript
+test('Parent deletion cascades to children', async () => {
+  await query('DELETE FROM users WHERE id = $1', [parentId]);
+  
+  const childResult = await query(
+    'SELECT * FROM orders WHERE user_id = $1',
+    [parentId]
+  );
+  expect(childResult.rows.length).toBe(0);
+});
+```
+
+---
+
+## 3. Concurrency Edge Cases
+
+### Race Conditions
+```typescript
+test('Concurrent INSERTs with unique constraint', async () => {
+  const concurrentInserts = Array(5).fill(null).map(() =>
+    query(
+      'INSERT INTO unique_values (name) VALUES ($1) ON CONFLICT DO NOTHING',
+      ['unique_name']
+    )
+  );
+  
+  const results = await Promise.all(concurrentInserts);
+  const successfulInserts = results.filter(r => r.rowCount === 1);
+  
+  // Only one should succeed
+  expect(successfulInserts.length).toBe(1);
+});
+```
+
+> [!NOTE|ANTIGRAVITY]
+> **IMPORTANT**: Parallel agents must use transaction isolation. Test with:
+> ```sql
+> BEGIN ISOLATION LEVEL SERIALIZABLE;
+> -- operations
+> COMMIT;
+> ```
+
+---
+
+## 4. Data Type Edge Cases
+
+### NULL Handling
+```typescript
+test('NULL comparison in WHERE clause', async () => {
+  const result = await query(
+    'SELECT * FROM users WHERE email IS NULL',
+    []
+  );
+  expect(result.rows.every(r => r.email === null)).toBe(true);
+});
+
+test('NULL in NOT IN with empty subquery', async () => {
+  const result = await query(
+    'SELECT * FROM users WHERE id NOT IN (SELECT user_id FROM inactive_logins)',
+    []
+  );
+  // Should return all users, not filtered by NULL subquery
+  expect(result.rows.length).toBeGreaterThan(0);
+});
+```
+
+---
+
+## 5. Large Dataset Edge Cases
+
+### Pagination Boundaries
+```typescript
+test('First page returns correct results', async () => {
+  const result = await query(`
+    SELECT * FROM orders 
+    WHERE organization_id = $1
+    ORDER BY created_at DESC 
+    LIMIT 50 OFFSET 0
+  `, [orgId]);
+  expect(result.rows.length).toBeLessThanOrEqual(50);
+});
+
+test('Last page handles partial results', async () => {
+  const result = await query(`
+    SELECT * FROM orders 
+    WHERE organization_id = $1
+    ORDER BY created_at DESC 
+    LIMIT 50 OFFSET 950
+  `, [orgId]);
+  expect(result.rows.length).toBeLessThanOrEqual(50);
+});
+```
+
+---
+
+## 6. Duplicate Detection Tests
+
+### Primary Key Duplicates
+```typescript
+test('Detects exact duplicate records', async () => {
+  const duplicates = await query(`
+    SELECT email, COUNT(*) as cnt
+    FROM users
+    WHERE deleted_at IS NULL
+    GROUP BY email
+    HAVING COUNT(*) > 1
+  `, []);
+  expect(duplicates.rows.length).toBe(0);
+});
+```
+
+---
+
+## Running Tests (Universal)
+
+```bash
+# All agents: Standard command
+npm test -- --testPathPattern=test-templates
+
+# Claude-specific
+claude test run
+
+# Codex-specific (must be explicit)
+codex exec "npm test -- --testPathPattern=test-templates"
+```
+
+---
+*Template version: 1.0.0*