@codihaus/claude-skills 1.0.0 → 1.3.0

package/knowledge/stacks/directus/_index.md

@@ -0,0 +1,349 @@
+# Directus
+
+> Headless CMS and Backend-as-a-Service with auto-generated REST & GraphQL APIs
+
+## Overview
+
+**What it is:**
+- Headless CMS that wraps any SQL database
+- Auto-generates REST and GraphQL APIs for collections
+- Built-in auth, permissions, file storage, webhooks, flows
+
+**When to use:**
+- Content-driven applications
+- Admin panels / dashboards
+- APIs without writing backend code
+- Projects needing flexible content modeling
+
+**Key concepts:**
+- **Collections** = Database tables (managed via Directus Admin)
+- **Items** = Rows in collections
+- **Fields** = Columns with types and validation
+- **Roles & Permissions** = Granular access control
+- **Flows** = Automation (triggers → operations)
+- **Extensions** = Custom endpoints, hooks, interfaces
+
+## Best Practices
+
+### Data Modeling
+
+```
+DO:
+✓ Use Directus Admin to create/modify collections
+✓ Define relationships in Directus (M2O, O2M, M2M, M2A)
+✓ Use system fields: id (uuid), status, sort, created/updated timestamps
+✓ Set field validation in Directus (not just frontend)
+
+DON'T:
+✗ Modify database directly (bypasses Directus cache)
+✗ Create tables via migrations (use Directus schema)
+✗ Hardcode IDs (use relations)
+```
+
+### API Access
+
+```
+DO:
+✓ Use @directus/sdk for type-safe access
+✓ Use REST for simple CRUD, GraphQL for complex queries
+✓ Filter at API level, not in frontend
+✓ Use fields parameter to limit response size
+
+DON'T:
+✗ Fetch all fields when you need few
+✗ Filter large datasets client-side
+✗ Bypass Directus API for direct DB access
+```
+
+### Authentication
+
+```
+DO:
+✓ Use Directus auth endpoints (/auth/login, /auth/refresh)
+✓ Store access_token, refresh with refresh_token
+✓ Use static tokens for server-to-server
+✓ Set appropriate token expiry
+
+DON'T:
+✗ Build custom auth (use Directus)
+✗ Store tokens in localStorage (use httpOnly cookies)
+✗ Share admin tokens with frontend
+```
+
+### Permissions
+
+```
+DO:
+✓ Create roles for each user type
+✓ Use field-level permissions (hide sensitive data)
+✓ Use custom permissions with $CURRENT_USER
+✓ Test permissions with role preview
+
+DON'T:
+✗ Give Public role more than needed
+✗ Use Admin role for regular users
+✗ Forget to set permissions on new collections
+```
+
+### Flows (Automation)
+
+```
+DO:
+✓ Use Flows for: email notifications, data validation, sync
+✓ Use "Filter" trigger for conditional automation
+✓ Chain operations for complex workflows
+✓ Log flow runs for debugging
+
+DON'T:
+✗ Put business logic only in frontend
+✗ Create circular flow triggers
+✗ Use flows for heavy computation (use extensions)
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Better Approach |
+|--------------|---------|-----------------|
+| Direct DB writes | Bypasses cache, permissions | Use Directus SDK/API |
+| Fetching all items | Memory issues, slow | Use pagination, filters |
+| Frontend-only validation | Data integrity issues | Set validation in Directus fields |
+| Hardcoded collection names | Breaks if renamed | Use constants/config |
+| Admin token in frontend | Security risk | Use user auth or server proxy |
+| Ignoring relations | Redundant data, sync issues | Use proper M2O/O2M/M2M |
+
+## For /dev-specs
+
+### API Design
+
+When specifying Directus features:
+
+```markdown
+## Data Model (Directus Collections)
+
+### Collection: products
+| Field | Type | Notes |
+|-------|------|-------|
+| id | uuid | PK (auto) |
+| status | status | draft/published/archived |
+| name | string | Required |
+| price | decimal | Required |
+| category | m2o:categories | Relation |
+| images | files | M2M to directus_files |
+
+### Permissions
+| Role | Create | Read | Update | Delete |
+|------|--------|------|--------|--------|
+| Public | ✗ | status=published | ✗ | ✗ |
+| Customer | ✗ | ✓ | own items | ✗ |
+| Admin | ✓ | ✓ | ✓ | ✓ |
+```
+
+### Don't Specify
+
+- Custom REST endpoints (use Directus API)
+- Database migrations (use Directus schema)
+- Auth endpoints (use Directus auth)
+
+### Do Specify
+
+- Collection structure and relations
+- Permission rules per role
+- Flows for automation
+- Custom extensions if needed
+
+## For /dev-coding
+
+### SDK Setup (TypeScript)
+
+```typescript
+// lib/directus.ts
+import { createDirectus, rest, authentication } from '@directus/sdk';
+
+type Schema = {
+  products: Product[];
+  categories: Category[];
+};
+
+const directus = createDirectus<Schema>(process.env.DIRECTUS_URL!)
+  .with(rest())
+  .with(authentication());
+
+export default directus;
+```
+
+### CRUD Operations
+
+```typescript
+import { readItems, readItem, createItem, updateItem, deleteItem } from '@directus/sdk';
+
+// Read with filters
+const products = await directus.request(
+  readItems('products', {
+    filter: { status: { _eq: 'published' } },
+    fields: ['id', 'name', 'price', { category: ['name'] }],
+    limit: 10,
+  })
+);
+
+// Create
+const newProduct = await directus.request(
+  createItem('products', {
+    name: 'New Product',
+    price: 99.99,
+    category: 'category-uuid',
+  })
+);
+
+// Update
+await directus.request(
+  updateItem('products', 'product-uuid', { price: 89.99 })
+);
+
+// Delete
+await directus.request(deleteItem('products', 'product-uuid'));
+```
+
+### Authentication
+
+```typescript
+// Login
+const auth = await directus.login(email, password);
+// Returns: { access_token, refresh_token, expires }
+
+// Refresh
+await directus.refresh();
+
+// Logout
+await directus.logout();
+
+// Get current user
+import { readMe } from '@directus/sdk';
+const me = await directus.request(readMe());
+```
+
+### File Uploads
+
+```typescript
+import { uploadFiles } from '@directus/sdk';
+
+const formData = new FormData();
+formData.append('file', fileBlob);
+
+const uploaded = await directus.request(uploadFiles(formData));
+// Returns: { id, filename_download, ... }
+
+// Get file URL
+const url = `${DIRECTUS_URL}/assets/${uploaded.id}`;
+```
+
+### Realtime (WebSockets)
+
+```typescript
+import { createDirectus, realtime } from '@directus/sdk';
+
+const client = createDirectus<Schema>(DIRECTUS_URL).with(realtime());
+
+client.onWebSocket('message', (data) => {
+  if (data.type === 'subscription') {
+    console.log('Update:', data.data);
+  }
+});
+
+await client.subscribe('products', {
+  query: { fields: ['id', 'name', 'price'] },
+});
+```
+
+## For /dev-review
+
+### Security Checklist
+
+- [ ] No admin tokens exposed to frontend
+- [ ] Public role has minimal permissions
+- [ ] Sensitive fields have field-level permissions
+- [ ] File access restricted appropriately
+- [ ] CORS configured correctly
+- [ ] Rate limiting enabled
+
+### Performance Checklist
+
+- [ ] Using `fields` parameter (not fetching all)
+- [ ] Using `filter` at API level
+- [ ] Pagination for large collections
+- [ ] Caching strategy for static content
+- [ ] No N+1 queries (use nested fields)
+
+### Data Integrity Checklist
+
+- [ ] Required fields marked in Directus
+- [ ] Field validation set (regex, min/max)
+- [ ] Relationships properly defined
+- [ ] Status workflow configured
+- [ ] Soft delete vs hard delete decided
+
+### Common Mistakes
+
+| Mistake | Impact | Fix |
+|---------|--------|-----|
+| `fields: ['*']` | Over-fetching | List needed fields |
+| No pagination | Memory issues | Add `limit` + `offset` |
+| Direct DB queries | Cache inconsistency | Use SDK |
+| Frontend auth storage | Security risk | Use httpOnly cookies |
+| Missing error handling | Poor UX | Catch SDK errors |
+
+## Integration
+
+### With Nuxt.js
+
+```typescript
+// composables/useDirectus.ts
+export const useDirectus = () => {
+  const config = useRuntimeConfig();
+  return createDirectus<Schema>(config.public.directusUrl)
+    .with(rest())
+    .with(authentication());
+};
+
+// Usage in component
+const directus = useDirectus();
+const { data } = await useAsyncData('products', () =>
+  directus.request(readItems('products'))
+);
+```
+
+### With Next.js
+
+```typescript
+// lib/directus.ts (server-side)
+const directus = createDirectus<Schema>(process.env.DIRECTUS_URL!)
+  .with(rest())
+  .with(staticToken(process.env.DIRECTUS_TOKEN!));
+
+// app/products/page.tsx (Server Component)
+export default async function ProductsPage() {
+  const products = await directus.request(readItems('products'));
+  return <ProductList products={products} />;
+}
+```
+
+## Resources
+
+### Official Docs
+- Docs: https://docs.directus.io
+- SDK: https://docs.directus.io/reference/sdk/
+
+### Context7 Queries
+
+```
+Query: "Directus SDK TypeScript setup"
+Query: "Directus permissions best practices"
+Query: "Directus flows automation"
+Query: "Directus file uploads"
+```
+
+### MCP Tools
+
+If `directus` MCP available:
+- Can query collections directly
+- Can check permissions
+- Can test API endpoints