@martinffx/atelier 2.0.0 → 3.0.1

package/skills/typescript-drizzle-orm/references/sqlite.md

@@ -1,291 +0,0 @@
-# SQLite Patterns with Drizzle ORM
-
-SQLite-specific patterns, schema definition, and local testing with better-sqlite3.
-
-## Schema Definition
-
-```typescript
-import {
-  sqliteTable,
-  text,
-  integer,
-  blob,
-  index,
-  uniqueIndex,
-} from 'drizzle-orm/sqlite-core'
-
-export const users = sqliteTable('users', {
-  id: text('id').primaryKey(),
-  name: text('name').notNull(),
-  email: text('email').notNull(),
-  age: integer('age'),
-  isActive: integer('is_active', { mode: 'boolean' }).default(true),
-  createdAt: text('created_at').notNull(), // ISO 8601 string
-  updatedAt: text('updated_at').notNull(),
-}, (table) => [
-  uniqueIndex('idx_users_email').on(table.email),
-])
-
-export const posts = sqliteTable('posts', {
-  id: text('id').primaryKey(),
-  title: text('title').notNull(),
-  content: text('content'),
-  authorId: text('author_id')
-    .notNull()
-    .references(() => users.id, { onDelete: 'cascade' }),
-  createdAt: text('created_at').notNull(),
-}, (table) => [
-  index('idx_posts_author').on(table.authorId),
-])
-```
-
-## Key Differences from PostgreSQL
-
-| Feature | PostgreSQL | SQLite |
-|---------|-----------|--------|
-| Primary Key | `serial('id').primaryKey()` | `integer('id').primaryKey({ autoIncrement: true })` or `text('id').primaryKey()` |
-| UUID | `uuid('id').defaultRandom()` | `text('id')` (generate in app) |
-| Timestamp | `timestamp('created_at').defaultNow()` | `text('created_at')` (ISO 8601) or `integer({ mode: 'timestamp' })` |
-| Boolean | `boolean('is_active')` | `integer('is_active', { mode: 'boolean' })` |
-| JSON | `jsonb('metadata')` | `text('metadata')` or `blob('metadata', { mode: 'json' })` |
-| Enum | `pgEnum()` | `text('type', { enum: ['A', 'B'] })` |
-| Binary | `bytea('data')` | `blob('data')` |
-
-## Column Types
-
-### Integer Modes
-
-```typescript
-// Default (number)
-age: integer('age')
-
-// Boolean
-isActive: integer('is_active', { mode: 'boolean' })
-
-// Unix timestamp (seconds)
-createdAt: integer('created_at', { mode: 'timestamp' })
-
-// Unix timestamp (milliseconds)
-createdAt: integer('created_at', { mode: 'timestamp_ms' })
-```
-
-### Text Enums
-
-```typescript
-// Type-safe enum with inference
-type: text('type', { enum: ['ASSET', 'LIABILITY', 'INCOME', 'EXPENSE'] }).notNull()
-
-// Inferred as: "ASSET" | "LIABILITY" | "INCOME" | "EXPENSE"
-```
-
-### Blob Types
-
-```typescript
-// Buffer mode (default)
-data: blob('data')
-
-// JSON mode
-metadata: blob('metadata', { mode: 'json' }).$type<{ key: string }>()
-
-// BigInt mode
-bigNumber: blob('big_number', { mode: 'bigint' })
-```
-
-## Indexes and Constraints
-
-```typescript
-export const accounts = sqliteTable('accounts', {
-  id: text('id').primaryKey(),
-  code: text('code').notNull(),
-  name: text('name').notNull(),
-  parentId: text('parent_id'),
-}, (table) => [
-  // Unique index
-  uniqueIndex('idx_accounts_code').on(table.code),
-  // Regular index
-  index('idx_accounts_parent').on(table.parentId),
-  // Composite index
-  index('idx_accounts_code_parent').on(table.code, table.parentId),
-])
-
-// Composite primary key
-export const postTags = sqliteTable('post_tags', {
-  postId: text('post_id').notNull().references(() => posts.id),
-  tagId: text('tag_id').notNull().references(() => tags.id),
-}, (table) => [
-  primaryKey({ columns: [table.postId, table.tagId] }),
-])
-```
-
-## Migrations Configuration
-
-```typescript
-// drizzle.config.ts
-import { defineConfig } from 'drizzle-kit'
-
-export default defineConfig({
-  schema: './src/db/schema.ts',
-  out: './drizzle',
-  dialect: 'sqlite',
-  dbCredentials: {
-    url: './local.db', // File path for local SQLite
-  },
-})
-```
-
-```bash
-# Generate migration
-npx drizzle-kit generate
-
-# Apply migrations
-npx drizzle-kit migrate
-
-# Open Drizzle Studio
-npx drizzle-kit studio
-```
-
-## Local Testing with better-sqlite3
-
-For D1 apps or local development, use `better-sqlite3` for fast in-memory testing:
-
-```typescript
-import Database from 'better-sqlite3'
-import { drizzle } from 'drizzle-orm/better-sqlite3'
-import { migrate } from 'drizzle-orm/better-sqlite3/migrator'
-import * as schema from './schema'
-
-// In-memory database (fast, isolated tests)
-const sqlite = new Database(':memory:')
-const db = drizzle(sqlite, { schema })
-
-// Run migrations
-migrate(db, { migrationsFolder: './drizzle' })
-
-// Use in tests
-test('user creation', async () => {
-  const [user] = await db.insert(schema.users).values({
-    id: crypto.randomUUID(),
-    name: 'Alice',
-    email: 'alice@example.com',
-    createdAt: new Date().toISOString(),
-    updatedAt: new Date().toISOString(),
-  }).returning()
-
-  expect(user.name).toBe('Alice')
-})
-```
-
-### File-Based Database
-
-```typescript
-// Persistent database file
-const sqlite = new Database('./test.db')
-const db = drizzle(sqlite, { schema })
-```
-
-### Test Setup Helper
-
-```typescript
-import { beforeEach, afterEach } from 'vitest'
-import Database from 'better-sqlite3'
-import { drizzle } from 'drizzle-orm/better-sqlite3'
-import * as schema from './schema'
-
-let sqlite: Database.Database
-let db: ReturnType<typeof drizzle>
-
-beforeEach(() => {
-  sqlite = new Database(':memory:')
-  db = drizzle(sqlite, { schema })
-  migrate(db, { migrationsFolder: './drizzle' })
-})
-
-afterEach(() => {
-  sqlite.close()
-})
-
-export { db }
-```
-
-## Date Handling
-
-SQLite doesn't have native date types. Use ISO 8601 strings or Unix timestamps:
-
-```typescript
-// ISO 8601 strings (recommended)
-createdAt: text('created_at').notNull()
-// Store: new Date().toISOString()
-// Parse: new Date(record.createdAt)
-
-// Unix timestamps (integer)
-createdAt: integer('created_at', { mode: 'timestamp' }).notNull()
-// Store: Math.floor(Date.now() / 1000)
-// Parse: new Date(record.createdAt * 1000)
-```
-
-## Schema Design Patterns
-
-### UUID Primary Keys
-
-```typescript
-export const users = sqliteTable('users', {
-  id: text('id').primaryKey(), // Generate with crypto.randomUUID()
-  name: text('name').notNull(),
-})
-
-// In your entity or repository
-const id = crypto.randomUUID()
-await db.insert(users).values({ id, name: 'Alice' })
-```
-
-### Auto-Increment Integer Keys
-
-```typescript
-export const users = sqliteTable('users', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  name: text('name').notNull(),
-})
-
-// SQLite generates the ID
-const [user] = await db.insert(users).values({ name: 'Alice' }).returning()
-console.log(user.id) // 1, 2, 3, ...
-```
-
-### Hierarchical Data
-
-```typescript
-export const categories = sqliteTable('categories', {
-  id: text('id').primaryKey(),
-  name: text('name').notNull(),
-  parentId: text('parent_id'),
-}, (table) => [
-  index('idx_categories_parent').on(table.parentId),
-])
-
-export const categoriesRelations = relations(categories, ({ one, many }) => ({
-  parent: one(categories, {
-    fields: [categories.parentId],
-    references: [categories.id],
-    relationName: 'parentChild',
-  }),
-  children: many(categories, {
-    relationName: 'parentChild',
-  }),
-}))
-```
-
-## When to Use SQLite
-
-- **Embedded applications** - Desktop, mobile, edge computing
-- **Single-writer scenarios** - One process writes, multiple read
-- **Cloudflare D1** - Managed SQLite for Workers
-- **Durable Objects** - Per-object isolated storage
-- **Local development** - Fast, zero-config testing
-- **Small to medium datasets** - Under 1TB
-
-## Limitations
-
-- No concurrent writers (one writer at a time)
-- Limited network access (file-based)
-- No stored procedures
-- No built-in replication (use D1 or Turso for distributed)

package/skills/typescript-dynamodb-toolbox/SKILL.md

@@ -1,370 +0,0 @@
----
-name: typescript-dynamodb-toolbox
-description: DynamoDB single-table design using dynamodb-toolbox v2. Use when creating entities, defining key patterns, designing GSIs, writing queries, implementing pagination, or working with any DynamoDB data layer in TypeScript projects.
-user-invocable: false
----
-
-# DynamoDB with dynamodb-toolbox v2
-
-Type-safe DynamoDB interactions with Entity and Table abstractions for single-table design.
-
-## When to Use DynamoDB
-
-✓ **Use when:**
-- Access patterns are known upfront and stable
-- Need predictable sub-10ms performance at scale
-- Microservice with clear data boundaries
-- Willing to commit to single-table design
-
-✗ **Avoid when:**
-- Prototyping with fluid requirements
-- Need ad-hoc analytical queries
-- Team lacks DynamoDB expertise
-- GraphQL resolvers drive access patterns
-
-> DynamoDB inverts the relational paradigm: design for known access patterns, not flexible querying.
-
-## Modeling Checklist
-
-Before implementing:
-1. **Define Entity Relationships** - Create ERD with all entities and relationships
-2. **Create Entity Chart** - Map each entity to PK/SK patterns
-3. **Design GSI Strategy** - Plan secondary access patterns
-4. **Document Access Patterns** - List every query the application needs
-
-See [references/modeling.md](references/modeling.md) for detailed methodology.
-
-## Table Configuration
-
-```typescript
-import { Table } from 'dynamodb-toolbox/table'
-
-const AppTable = new Table({
-  name: process.env.TABLE_NAME || "AppTable",
-  partitionKey: { name: "PK", type: "string" },
-  sortKey: { name: "SK", type: "string" },
-  indexes: {
-    GSI1: {
-      type: "global",
-      partitionKey: { name: "GSI1PK", type: "string" },
-      sortKey: { name: "GSI1SK", type: "string" },
-    },
-    GSI2: {
-      type: "global",
-      partitionKey: { name: "GSI2PK", type: "string" },
-      sortKey: { name: "GSI2SK", type: "string" },
-    },
-    GSI3: {
-      type: "global",
-      partitionKey: { name: "GSI3PK", type: "string" },
-      sortKey: { name: "GSI3SK", type: "string" },
-    },
-  },
-  entityAttributeSavedAs: "_et", // default, customize if needed
-});
-```
-
-### Index Purpose
-
-| Index | Purpose |
-|-------|---------|
-| Main Table (PK/SK) | Primary entity access |
-| GSI1 | Collection queries (issues by repo, members by org) |
-| GSI2 | Entity-specific queries and relationships (forks) |
-| GSI3 | Hierarchical queries with temporal sorting (repos by owner) |
-
-## Entity Definition (v2 syntax)
-
-### Basic Pattern with Linked Keys
-
-```typescript
-import { Entity } from 'dynamodb-toolbox/entity'
-import { item } from 'dynamodb-toolbox/schema/item'
-import { string } from 'dynamodb-toolbox/schema/string'
-
-const UserEntity = new Entity({
-  name: "USER",
-  table: AppTable,
-  schema: item({
-    // Business attributes
-    username: string().required().key(),
-    email: string().required(),
-    bio: string().optional(),
-  }).and(_schema => ({
-    // Computed keys (PK/SK/GSI keys derived from business attributes)
-    PK: string().key().link<typeof _schema>(
-      ({ username }) => `ACCOUNT#${username}`
-    ),
-    SK: string().key().link<typeof _schema>(
-      ({ username }) => `ACCOUNT#${username}`
-    ),
-    GSI1PK: string().link<typeof _schema>(
-      ({ username }) => `ACCOUNT#${username}`
-    ),
-    GSI1SK: string().link<typeof _schema>(
-      ({ username }) => `ACCOUNT#${username}`
-    ),
-  })),
-});
-```
-
-### With Validation
-
-```typescript
-const RepoEntity = new Entity({
-  name: "REPO",
-  table: AppTable,
-  schema: item({
-    owner: string()
-      .required()
-      .validate((value: string) => /^[a-zA-Z0-9_-]+$/.test(value))
-      .key(),
-    repo_name: string()
-      .required()
-      .validate((value: string) => /^[a-zA-Z0-9_-]+$/.test(value))
-      .key(),
-    description: string().optional(),
-    is_private: boolean().default(false),
-  }).and(_schema => ({
-    PK: string().key().link<typeof _schema>(
-      ({ owner, repo_name }) => `REPO#${owner}#${repo_name}`
-    ),
-    SK: string().key().link<typeof _schema>(
-      ({ owner, repo_name }) => `REPO#${owner}#${repo_name}`
-    ),
-    // GSI3 for temporal sorting (repos by owner, newest first)
-    GSI3PK: string().link<typeof _schema>(
-      ({ owner }) => `ACCOUNT#${owner}`
-    ),
-    GSI3SK: string()
-      .default(() => `#${new Date().toISOString()}`)
-      .savedAs("GSI3SK"),
-  })),
-});
-```
-
-## Entity Chart (Key Patterns)
-
-| Entity | PK | SK | Purpose |
-|--------|----|----|---------|
-| User | `ACCOUNT#{username}` | `ACCOUNT#{username}` | Direct access |
-| Repository | `REPO#{owner}#{name}` | `REPO#{owner}#{name}` | Direct access |
-| Issue | `ISSUE#{owner}#{repo}#{padded_num}` | Same as PK | Direct access + enumeration |
-| Comment | `REPO#{owner}#{repo}` | `ISSUE#{padded_num}#COMMENT#{id}` | Comments under issue |
-| Star | `ACCOUNT#{username}` | `STAR#{owner}#{repo}#{timestamp}` | Adjacency list pattern |
-
-**Key Pattern Rules:**
-- `ENTITY#{id}` - Simple identifier
-- `PARENT#{id}#CHILD#{id}` - Hierarchy
-- `TYPE#{category}#{identifier}` - Categorization
-- `#{timestamp}` - Temporal sorting (# prefix ensures ordering)
-
-## Type Safety
-
-```typescript
-import { type InputItem, type FormattedItem } from 'dynamodb-toolbox/entity'
-
-// Type exports
-type UserRecord = typeof UserEntity
-type UserInput = InputItem<typeof UserEntity>      // For writes
-type UserFormatted = FormattedItem<typeof UserEntity> // For reads
-
-// Usage in entities
-class User {
-  static fromRecord(record: UserFormatted): User { /* ... */ }
-  toRecord(): UserInput { /* ... */ }
-}
-```
-
-See [references/entity-layer.md](references/entity-layer.md) for transformation patterns.
-
-## Repository Pattern
-
-```typescript
-import { PutItemCommand, GetItemCommand, DeleteItemCommand } from 'dynamodb-toolbox'
-
-class UserRepository {
-  constructor(private entity: UserRecord) {}
-
-  // CREATE with duplicate check
-  async create(user: User): Promise<User> {
-    try {
-      const result = await this.entity
-        .build(PutItemCommand)
-        .item(user.toRecord())
-        .options({
-          condition: { attr: "PK", exists: false }, // Prevent duplicates
-        })
-        .send()
-
-      return User.fromRecord(result.ToolboxItem)
-    } catch (error) {
-      if (error instanceof ConditionalCheckFailedException) {
-        throw new DuplicateEntityError("User", user.username)
-      }
-      throw error
-    }
-  }
-
-  // GET by key
-  async get(username: string): Promise<User | undefined> {
-    const result = await this.entity
-      .build(GetItemCommand)
-      .key({ username })
-      .send()
-
-    return result.Item ? User.fromRecord(result.Item) : undefined
-  }
-
-  // UPDATE with existence check
-  async update(user: User): Promise<User> {
-    try {
-      const result = await this.entity
-        .build(PutItemCommand)
-        .item(user.toRecord())
-        .options({
-          condition: { attr: "PK", exists: true }, // Must exist
-        })
-        .send()
-
-      return User.fromRecord(result.ToolboxItem)
-    } catch (error) {
-      if (error instanceof ConditionalCheckFailedException) {
-        throw new EntityNotFoundError("User", user.username)
-      }
-      throw error
-    }
-  }
-
-  // DELETE
-  async delete(username: string): Promise<void> {
-    await this.entity.build(DeleteItemCommand).key({ username }).send()
-  }
-}
-```
-
-See [references/error-handling.md](references/error-handling.md) for error patterns.
-
-## Query Patterns
-
-### Query GSI
-
-```typescript
-import { QueryCommand } from 'dynamodb-toolbox/table/actions/query'
-
-// List issues for a repository using GSI1
-async listIssues(owner: string, repoName: string): Promise<Issue[]> {
-  const result = await this.table
-    .build(QueryCommand)
-    .entities(this.issueEntity)
-    .query({
-      partition: `ISSUE#${owner}#${repoName}`,
-      index: "GSI1",
-    })
-    .send()
-
-  return result.Items?.map(item => Issue.fromRecord(item)) || []
-}
-```
-
-### Query with Range Filter
-
-```typescript
-// List by status using beginsWith on SK
-async listOpenIssues(owner: string, repoName: string): Promise<Issue[]> {
-  const result = await this.table
-    .build(QueryCommand)
-    .entities(this.issueEntity)
-    .query({
-      partition: `ISSUE#${owner}#${repoName}`,
-      index: "GSI4",
-      range: {
-        beginsWith: "ISSUE#OPEN#", // Filter to open issues only
-      },
-    })
-    .send()
-
-  return result.Items?.map(item => Issue.fromRecord(item)) || []
-}
-```
-
-### Pagination
-
-```typescript
-// Encode/decode pagination tokens
-function encodePageToken(lastEvaluated?: Record<string, unknown>): string | undefined {
-  return lastEvaluated
-    ? Buffer.from(JSON.stringify(lastEvaluated)).toString("base64")
-    : undefined
-}
-
-function decodePageToken(token?: string): Record<string, unknown> | undefined {
-  return token ? JSON.parse(Buffer.from(token, "base64").toString()) : undefined
-}
-
-// Query with pagination
-async listReposByOwner(owner: string, limit = 50, offset?: string) {
-  const result = await this.table
-    .build(QueryCommand)
-    .entities(this.repoEntity)
-    .query({
-      partition: `ACCOUNT#${owner}`,
-      index: "GSI3",
-      range: { lt: "ACCOUNT#" }, // Filter to only repos (not account itself)
-    })
-    .options({
-      reverse: true,                              // Newest first
-      exclusiveStartKey: decodePageToken(offset), // Continue from cursor
-      limit,
-    })
-    .send()
-
-  return {
-    items: result.Items?.map(item => Repo.fromRecord(item)) || [],
-    nextOffset: encodePageToken(result.LastEvaluatedKey),
-  }
-}
-```
-
-## Transactions
-
-See [references/transactions.md](references/transactions.md) for:
-- Multi-entity transactions (PutTransaction + ConditionCheck)
-- Atomic counters with `$add(1)`
-- TransactionCanceledException handling
-
-## Testing
-
-See [references/testing.md](references/testing.md) for:
-- DynamoDB Local setup
-- Test fixtures and factories
-- Concurrency and temporal sorting tests
-
-## Quick Reference
-
-**Schema:**
-- Use `item({})` for schema definition
-- Mark key attributes with `.key()`
-- Separate business attributes from computed keys using `.and()`
-- Use `.link<typeof _schema>()` to compute PK/SK/GSI keys
-- Use `.validate()` for field validation
-- Use `.savedAs()` when DynamoDB name differs from schema name
-
-**Types:**
-- `InputItem<T>` for writes (excludes computed attributes)
-- `FormattedItem<T>` for reads (includes all attributes)
-
-**Repository:**
-- Use `PutItemCommand` with `{ attr: "PK", exists: false }` for creates
-- Use `PutItemCommand` with `{ attr: "PK", exists: true }` for updates
-- Use `GetItemCommand` with `.key()` for reads
-- Use `QueryCommand` with `.entities()` for type-safe queries
-
-**Errors:**
-- `ConditionalCheckFailedException` → DuplicateEntityError (create) or EntityNotFoundError (update)
-- Always catch and convert to domain errors
-
-**Testing:**
-- Use unique IDs per test run (timestamp-based)
-- Clean up test data after each test
-- Use DynamoDB Local for development