opencastle 0.33.9 → 0.34.0

package/src/orchestrator/plugins/coolify/references/docker-compose.md

@@ -0,0 +1,121 @@
+# Docker Compose
+
+## Deployment Modes
+
+| Mode | How | Constraints |
+|------|-----|-------------|
+| Raw (paste YAML) | Paste compose content directly | No `build:`, no external file mounts; use `image:` and `content:` for inline files |
+| Repository | git URL | Full Docker Compose features: `build:`, external mounts, multi-file |
+
+## Magic Variables
+
+Coolify auto-generates values for specially named env vars. Declare with port suffix, reference without.
+
+| Type | Declaration Example | Generated Value |
+|------|--------------------|-----------------| 
+| `PASSWORD` | `SERVICE_PASSWORD_DB` | Random password |
+| `PASSWORD_64` | `SERVICE_PASSWORD_64_KEY` | 64-char password |
+| `USER` | `SERVICE_USER_ADMIN` | Random 16-char string |
+| `URL` | `SERVICE_URL_APP_3000` | `https://app-uuid.example.com` + Traefik routing |
+| `FQDN` | `SERVICE_FQDN_APP` | `app-uuid.example.com` (no scheme) |
+
+**Declaration vs. Reference:**
+```yaml
+environment:
+  - SERVICE_URL_APP_3000    # Declare with port → activates proxy routing
+  - APP_URL=$SERVICE_URL_APP  # Reference without port → injects https://… URL
+```
+
+⚠️ Use hyphens before port numbers: `SERVICE_URL_MY-SERVICE_3000` ✅  NOT `SERVICE_URL_MY_SERVICE_3000` ❌
+
+**Shared credentials** — same `SERVICE_PASSWORD_*` identifier across services = same generated value:
+```yaml
+services:
+  db:   { environment: [SERVICE_PASSWORD_POSTGRES] }
+  app:  { environment: [DB_PASS=$SERVICE_PASSWORD_POSTGRES] }  # same value
+```
+
+## Env Var Syntax
+
+```yaml
+environment:
+  - NODE_ENV=production           # Hardcoded, hidden from UI
+  - API_KEY=${API_KEY}            # Editable in UI (empty default)
+  - LOG_LEVEL=${LOG_LEVEL:-info}  # Editable with default
+  - SECRET=${SECRET:?}            # Required — blocks deploy if empty
+```
+
+## Health Check Patterns
+
+```yaml
+healthcheck:
+  # HTTP
+  test: ["CMD-SHELL", "wget --spider -q http://localhost:8080"]
+  # PostgreSQL
+  test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+  # MySQL
+  test: ["CMD-SHELL", "healthcheck.sh --connect --innodb_initialized"]
+  # Redis
+  test: ["CMD-SHELL", "redis-cli ping"]
+  interval: 5s
+  timeout: 5s
+  retries: 10
+  start_period: 30s
+```
+
+## Coolify-Specific Extensions
+
+```yaml
+volumes:
+  - /data/config:/app/config      # standard bind mount
+  - source: /data/uploads
+    target: /app/uploads
+    is_directory: true            # Coolify creates the directory if missing
+
+  - source: coolify-config
+    target: /app/config/app.conf
+    content: |                    # Inline file content (raw mode only)
+      log_level = info
+      bind = 0.0.0.0:8080
+```
+
+```yaml
+# Exclude init/migration containers from health checks
+services:
+  migrate:
+    image: myapp:latest
+    command: ["migrate", "up"]
+    labels:
+      - "exclude_from_hc=true"
+```
+
+## Header Metadata (for community templates)
+
+```yaml
+# documentation: https://docs.example.com
+# slogan: "One-click app name"
+# category: self-hosted
+# tags: Notes,Productivity
+# logo: https://cdn.example.com/logo.png
+# port: 3000
+```
+
+## Conversion Checklist
+
+When converting a standard `docker-compose.yml` for Coolify:
+
+1. **Mode check** — `build:` directives → Raw mode: replace with `image:`; Repo mode: keep
+2. **Add header metadata** — `# documentation:`, `# slogan:`, `# category:`, `# tags:`, `# logo:`, `# port:`
+3. **Replace credentials** — hardcoded passwords/users → `SERVICE_PASSWORD_*` / `SERVICE_USER_*`
+4. **Replace URLs** — hardcoded URLs → `SERVICE_URL_*` variables
+5. **Remove `ports:`** — for proxied services (Traefik handles routing via `SERVICE_URL_*`)
+6. **Add health checks** — use patterns above; add `depends_on` with `condition: service_healthy`
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| "No Available Server" | Check `docker ps` for unhealthy containers |
+| Variables not editable in UI | Use `${VAR}` syntax — not `VAR=value` |
+| Magic variables not generating | Check spelling, `SERVICE_` prefix; requires Coolify ≥ v4.0.0-beta.411 |
+| Port routing broken | Use `SERVICE_URL_NAME_PORT`, hyphen before port, remove `ports:` |

package/src/orchestrator/plugins/coolify/references/infrastructure.md

@@ -0,0 +1,77 @@
+# Infrastructure & Diagnostics
+
+## Infrastructure Overview
+
+Always start here — returns all servers, projects, apps, databases, services in one call:
+
+```
+get_infrastructure_overview
+```
+
+## Server Management
+
+```bash
+# List servers (summaries)
+list_servers
+
+# Full details
+get_server uuid="<uuid>"
+
+# Check resources on a server
+server_resources uuid="<uuid>"
+
+# List domains
+server_domains uuid="<uuid>"
+
+# Validate SSH connection
+validate_server uuid="<uuid>"
+```
+
+## Diagnostics
+
+Smart lookup — accepts names, domains, or IPs (not just UUIDs):
+
+```bash
+# App diagnostics (by name or domain)
+diagnose_app identifier="my-app"
+diagnose_app identifier="example.com"
+
+# Server diagnostics (by name or IP)
+diagnose_server identifier="192.168.1.100"
+diagnose_server identifier="coolify-apps"
+
+# Scan all infrastructure
+find_issues
+```
+
+## Batch Operations
+
+```bash
+# Restart all apps in a project
+restart_project_apps project_uuid="<uuid>"
+
+# Redeploy all apps in a project
+redeploy_project project_uuid="<uuid>"
+
+# Emergency stop all apps (requires confirmation)
+stop_all_apps confirm=true
+
+# Bulk update env var across apps
+bulk_env_update key="API_URL" value="https://new-api.example.com" uuids=["<uuid1>","<uuid2>"]
+```
+
+## Response Pattern
+
+Coolify MCP returns HATEOAS-style `_actions` suggesting next steps:
+
+```json
+{
+  "data": { "uuid": "abc123", "status": "running" },
+  "_actions": [
+    { "tool": "application_logs", "args": { "uuid": "abc123" }, "hint": "View logs" },
+    { "tool": "control", "args": { "resource": "application", "action": "restart", "uuid": "abc123" }, "hint": "Restart" }
+  ]
+}
+```
+
+Follow `_actions` suggestions for efficient multi-step workflows.

package/src/orchestrator/plugins/drizzle/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: drizzle-orm
+description: "Drizzle ORM schema definition, type-safe queries, relational queries, CRUD operations, transactions, migrations with drizzle-kit, and database setup for PostgreSQL, MySQL, and SQLite. Use when defining database schemas, writing queries or joins, managing migrations, setting up a new Drizzle project, or working with drizzle-kit."
+---
+
+# Drizzle ORM
+
+## Topic Routing
+
+Read the matching reference before writing code for any of these topics:
+
+| Topic | Reference |
+|-------|-----------|
+| Schema definition & column types | `references/schema-patterns.md` |
+| Queries, joins, & CRUD operations | `references/query-patterns.md` |
+| Migrations & drizzle-kit | `references/migrations.md` |
+
+## Critical Rules
+
+**Schema**
+- Define schemas in dedicated `schema.ts` files using `pgTable` / `mysqlTable` / `sqliteTable` from the correct dialect package
+- Use `$inferSelect` and `$inferInsert` for TypeScript types — never duplicate type definitions manually
+- Foreign keys require explicit `references(() => table.column)` — omitting this creates an unconstrained column
+- Pass `{ schema }` to `drizzle()` when initializing the client to enable relational queries
+
+**Relations**
+- Define with `relations()` from `drizzle-orm` alongside the table definition
+- Relations are required for `db.query` relational API — the SQL-like API does not use them
+- Do not use relations as a substitute for foreign key constraints; define both
+
+**Queries**
+- Use SQL-like API (`db.select().from()`) for complex joins and aggregations
+- Use relational API (`db.query.table.findMany({ with: { ... } })`) for nested data fetching
+- Import `eq`, `and`, `or`, `gt`, `like`, `isNull` etc. from `drizzle-orm` for `where` clauses
+- Always use `returning()` to get the inserted, updated, or deleted rows back
+
+**Migrations**
+- Use `drizzle-kit` for all migrations: `npx drizzle-kit generate` then `npx drizzle-kit migrate`
+- Configure in `drizzle.config.ts` — connections string must be set before running commands
+- Never manually edit generated migration SQL files — regenerate if changes are needed
+- Use `npx drizzle-kit push` in development only; always use `migrate` for production
+
+**Transactions**
+- Wrap multi-step operations in `db.transaction(async (tx) => { ... })`
+- Use `tx` (the transaction argument) instead of `db` for all queries inside the callback
+
+**Performance**
+- Use `db.select({ col: table.col })` for partial selects — avoids loading unused columns
+- Add indexes in the schema definition for frequently queried columns
+- Use `.prepare()` for repeated queries (prepared statements)
+
+## Schema Definition
+
+```typescript
+import { pgTable, text, integer, timestamp, boolean } from 'drizzle-orm/pg-core';
+import { relations } from 'drizzle-orm';
+
+export const users = pgTable('users', {
+  id: text('id').primaryKey(),
+  email: text('email').notNull().unique(),
+  name: text('name').notNull(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+});
+
+export const posts = pgTable('posts', {
+  id: text('id').primaryKey(),
+  title: text('title').notNull(),
+  authorId: text('author_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+  published: boolean('published').default(false).notNull(),
+});
+
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+}));
+
+export const postsRelations = relations(posts, ({ one }) => ({
+  author: one(users, { fields: [posts.authorId], references: [users.id] }),
+}));
+
+// Type inference — no manual duplication
+export type User = typeof users.$inferSelect;
+export type NewUser = typeof users.$inferInsert;
+```
+
+## Query Patterns
+
+```typescript
+import { db } from './db';
+import { eq } from 'drizzle-orm';
+import { users, posts } from './schema';
+
+// SQL-like: select with join
+const results = await db
+  .select({ user: users, postCount: count(posts.id) })
+  .from(users)
+  .leftJoin(posts, eq(posts.authorId, users.id))
+  .groupBy(users.id);
+
+// Relational: nested fetch
+const usersWithPosts = await db.query.users.findMany({
+  where: eq(users.id, userId),
+  with: { posts: { where: eq(posts.published, true) } },
+});
+
+// Insert with returning
+const [newUser] = await db.insert(users).values({ id, email, name }).returning();
+```
+
+## Reference Files
+
+- `references/schema-patterns.md` — Table definitions, column types, constraints, indexes, relations, type inference
+- `references/query-patterns.md` — Select, joins, where clauses, relational API, CRUD, transactions, prepared statements
+- `references/migrations.md` — drizzle.config.ts, generate/migrate/push commands, migration workflow
+
+## Quick Workflow: Set up Drizzle in a project
+1. Install: `npm install drizzle-orm` + dialect driver (`postgres` / `@libsql/client` / `better-sqlite3`)
+2. Install drizzle-kit: `npm install -D drizzle-kit`
+3. Define schema in `src/db/schema.ts` using the correct dialect table builder
+4. Create `drizzle.config.ts` with database URL and schema path — verify the config before running commands
+5. Generate migration: `npx drizzle-kit generate` — inspect the SQL output before applying
+6. Apply migration: `npx drizzle-kit migrate`
+   - **If migration fails:** check DB connection string → verify schema matches existing tables → use `npx drizzle-kit push` for dev environments
+7. Initialize client: `const db = drizzle(pool, { schema })` and run a test query to confirm connectivity

package/src/orchestrator/plugins/drizzle/config.ts

@@ -0,0 +1,16 @@
+import type { PluginConfig } from '../types.js';
+
+export const config: PluginConfig = {
+  id: 'drizzle',
+  name: 'Drizzle ORM',
+  category: 'tech',
+  subCategory: 'database',
+  label: 'Drizzle ORM',
+  hint: 'Type-safe SQL ORM with migrations',
+  skillName: 'drizzle-orm',
+  authType: 'none',
+  envVars: [],
+  agentToolMap: {},
+  docsUrl: null,
+  officialDocs: 'https://orm.drizzle.team/',
+};

package/src/orchestrator/plugins/drizzle/references/migrations.md

@@ -0,0 +1,112 @@
+# Drizzle Migrations
+
+## drizzle.config.ts
+
+```typescript
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'postgresql',           // 'postgresql' | 'mysql' | 'sqlite'
+  schema: './src/db/schema.ts',    // path to your schema file(s)
+  out: './drizzle',                // output directory for migrations
+  dbCredentials: {
+    url: process.env.DATABASE_URL!, // never hardcode credentials
+  },
+  verbose: true,
+  strict: true,
+});
+```
+
+## Commands
+
+| Command | When to use |
+|---------|------------|
+| `npx drizzle-kit generate` | After schema changes — generates SQL migration files |
+| `npx drizzle-kit migrate` | Apply pending migrations to the database (production-safe) |
+| `npx drizzle-kit push` | Sync schema directly to DB without migrations (dev only) |
+| `npx drizzle-kit studio` | Open local DB browser UI |
+| `npx drizzle-kit check` | Validate migration history consistency |
+
+## Migration Workflow
+
+```bash
+# 1. Change schema in src/db/schema.ts
+# 2. Generate migration — inspect the SQL before applying
+npx drizzle-kit generate
+
+# 3. Review the generated .sql file in ./drizzle/
+# 4. Apply to database
+npx drizzle-kit migrate
+```
+
+**Never edit generated migration files.** If the generated SQL is wrong, adjust the schema and regenerate.
+
+## Handling Breaking Changes
+
+### Adding a required (non-nullable) column
+
+```typescript
+// Step 1: Add as nullable first
+newColumn: text('new_column'),
+
+// Step 2: Run migration to add the column → backfill data in a separate script/mutation
+// Step 3: Add .notNull() after backfill is complete
+newColumn: text('new_column').notNull(),
+
+// Step 4: Run migration again to add the NOT NULL constraint
+```
+
+### Renaming a column
+
+Drizzle Kit generates a DROP + ADD by default. To rename without data loss, use a custom migration:
+
+```sql
+-- drizzle/0002_rename_column.sql (manually created)
+ALTER TABLE users RENAME COLUMN old_name TO new_name;
+```
+
+Then run `npx drizzle-kit migrate` — it will apply the custom file.
+
+## Programmatic Migrations (CI / startup)
+
+```typescript
+import { drizzle } from 'drizzle-orm/postgres-js';
+import { migrate } from 'drizzle-orm/postgres-js/migrator';
+import postgres from 'postgres';
+
+const migrationClient = postgres(process.env.DATABASE_URL!, { max: 1 });
+await migrate(drizzle(migrationClient), { migrationsFolder: './drizzle' });
+await migrationClient.end();
+```
+
+## Database Client Setup
+
+```typescript
+// src/db/index.ts (PostgreSQL with postgres.js)
+import { drizzle } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+import * as schema from './schema';
+
+const pool = postgres(process.env.DATABASE_URL!);
+export const db = drizzle(pool, { schema });
+```
+
+```typescript
+// src/db/index.ts (SQLite with better-sqlite3)
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import Database from 'better-sqlite3';
+import * as schema from './schema';
+
+const sqlite = new Database('sqlite.db');
+export const db = drizzle(sqlite, { schema });
+```
+
+```typescript
+// src/db/index.ts (Turso / libSQL)
+import { drizzle } from 'drizzle-orm/libsql';
+import { createClient } from '@libsql/client';
+import * as schema from './schema';
+
+const client = createClient({ url: process.env.TURSO_URL!, authToken: process.env.TURSO_TOKEN! });
+export const db = drizzle(client, { schema });
+```

package/src/orchestrator/plugins/drizzle/references/query-patterns.md

@@ -0,0 +1,127 @@
+# Drizzle Query Patterns
+
+## SQL-like API (complex joins & aggregations)
+
+```typescript
+import { db } from './db';
+import { eq, and, or, gt, like, isNull, desc, count, sql } from 'drizzle-orm';
+import { users, posts } from './schema';
+
+// Basic select with where
+const activeUsers = await db
+  .select()
+  .from(users)
+  .where(and(eq(users.active, true), gt(users.age, 18)));
+
+// Partial select (avoids loading unused columns)
+const emails = await db
+  .select({ id: users.id, email: users.email })
+  .from(users);
+
+// Join
+const postsWithAuthors = await db
+  .select({ post: posts, author: users })
+  .from(posts)
+  .innerJoin(users, eq(posts.authorId, users.id))
+  .where(eq(posts.published, true))
+  .orderBy(desc(posts.createdAt))
+  .limit(20);
+
+// Aggregate
+const stats = await db
+  .select({ total: count(), avgAge: sql<number>`avg(${users.age})` })
+  .from(users);
+```
+
+## Relational API (nested data fetching)
+
+```typescript
+// Requires { schema } passed to drizzle() and relations defined in schema
+
+// findMany with nested includes
+const usersWithPosts = await db.query.users.findMany({
+  where: eq(users.active, true),
+  orderBy: desc(users.createdAt),
+  limit: 10,
+  with: {
+    posts: {
+      where: eq(posts.published, true),
+      columns: { id: true, title: true, createdAt: true }, // partial columns
+      orderBy: desc(posts.createdAt),
+    },
+  },
+});
+
+// findFirst
+const user = await db.query.users.findFirst({
+  where: eq(users.email, email),
+  with: { posts: true },
+});
+```
+
+## CRUD Operations
+
+```typescript
+// Insert — always use returning() to get back the created row
+const [newUser] = await db
+  .insert(users)
+  .values({ id: crypto.randomUUID(), email, name })
+  .returning();
+
+// Upsert (on conflict)
+const [upserted] = await db
+  .insert(users)
+  .values({ id, email, name })
+  .onConflictDoUpdate({
+    target: users.email,
+    set: { name, updatedAt: new Date() },
+  })
+  .returning();
+
+// Update
+const [updated] = await db
+  .update(users)
+  .set({ name: 'New Name', updatedAt: new Date() })
+  .where(eq(users.id, userId))
+  .returning();
+
+// Delete
+const [deleted] = await db
+  .delete(posts)
+  .where(and(eq(posts.authorId, userId), eq(posts.published, false)))
+  .returning();
+```
+
+## Transactions
+
+```typescript
+const result = await db.transaction(async (tx) => {
+  // Use tx instead of db inside the transaction
+  const [order] = await tx.insert(orders).values(orderData).returning();
+
+  await tx.insert(orderItems).values(
+    items.map((item) => ({ orderId: order.id, ...item }))
+  );
+
+  await tx
+    .update(inventory)
+    .set({ quantity: sql`${inventory.quantity} - 1` })
+    .where(eq(inventory.productId, productId));
+
+  return order;
+});
+```
+
+## Prepared Statements
+
+```typescript
+// Define once, reuse many times
+const getUserById = db
+  .select()
+  .from(users)
+  .where(eq(users.id, sql.placeholder('id')))
+  .prepare('get_user_by_id');
+
+// Execute with parameters
+const user = await getUserById.execute({ id: userId });
+```

package/src/orchestrator/plugins/drizzle/references/schema-patterns.md

@@ -0,0 +1,105 @@
+# Drizzle Schema Patterns
+
+## PostgreSQL
+
+```typescript
+import {
+  pgTable, text, integer, boolean, timestamp, numeric,
+  serial, uuid, jsonb, index, uniqueIndex,
+} from 'drizzle-orm/pg-core';
+import { relations, sql } from 'drizzle-orm';
+
+export const users = pgTable('users', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  email: text('email').notNull().unique(),
+  name: text('name').notNull(),
+  age: integer('age'),
+  active: boolean('active').default(true).notNull(),
+  metadata: jsonb('metadata').$type<Record<string, unknown>>(),
+  createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp('updated_at', { withTimezone: true })
+    .defaultNow()
+    .$onUpdate(() => new Date())
+    .notNull(),
+}, (table) => [
+  index('users_email_idx').on(table.email),
+  uniqueIndex('users_active_email_idx').on(table.active, table.email),
+]);
+```
+
+## MySQL
+
+```typescript
+import { mysqlTable, varchar, int, boolean, datetime } from 'drizzle-orm/mysql-core';
+
+export const products = mysqlTable('products', {
+  id: int('id').autoincrement().primaryKey(),
+  name: varchar('name', { length: 255 }).notNull(),
+  price: int('price').notNull(), // store in cents
+  inStock: boolean('in_stock').default(true),
+  createdAt: datetime('created_at').default(sql`now()`),
+});
+```
+
+## SQLite
+
+```typescript
+import { sqliteTable, text, integer, real } from 'drizzle-orm/sqlite-core';
+import { sql } from 'drizzle-orm';
+
+export const notes = sqliteTable('notes', {
+  id: integer('id', { mode: 'number' }).primaryKey({ autoIncrement: true }),
+  title: text('title').notNull(),
+  body: text('body'),
+  score: real('score').default(0),
+  createdAt: integer('created_at', { mode: 'timestamp' })
+    .default(sql`(unixepoch())`)
+    .notNull(),
+});
+```
+
+## Foreign Keys & Constraints
+
+```typescript
+export const posts = pgTable('posts', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  authorId: uuid('author_id')
+    .notNull()
+    .references(() => users.id, { onDelete: 'cascade', onUpdate: 'cascade' }),
+  categoryId: uuid('category_id')
+    .references(() => categories.id, { onDelete: 'set null' }), // nullable FK
+});
+```
+
+## Relations
+
+```typescript
+import { relations } from 'drizzle-orm';
+
+// One-to-many
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+}));
+
+export const postsRelations = relations(posts, ({ one, many }) => ({
+  author: one(users, { fields: [posts.authorId], references: [users.id] }),
+  comments: many(comments),
+}));
+
+// Many-to-many (via junction table)
+export const postTagsRelations = relations(postTags, ({ one }) => ({
+  post: one(posts, { fields: [postTags.postId], references: [posts.id] }),
+  tag: one(tags, { fields: [postTags.tagId], references: [tags.id] }),
+}));
+```
+
+## Type Inference
+
+```typescript
+// Always use $inferSelect and $inferInsert — never write these types manually
+export type User = typeof users.$inferSelect;
+export type NewUser = typeof users.$inferInsert;
+
+// Partial insert type (e.g. when ID is generated externally)
+export type CreateUserInput = Omit<NewUser, 'id' | 'createdAt' | 'updatedAt'>;
+```