@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/drizzle-orm/references/queries.md

@@ -1,318 +0,0 @@
-# Queries
-
-Load this when writing relational queries, SQL-like queries, transactions, prepared statements, or aggregation patterns with Drizzle ORM.
-
-## Relational query API
-
-### Basic findMany with relations
-
-```typescript
-// Load all active users with their team and posts
-const usersWithTeams = await db.query.users.findMany({
-  where: eq(users.isActive, true),
-  with: {
-    team: true,          // loads the related team (many-to-one)
-    posts: true,         // loads all posts (one-to-many)
-  },
-});
-// Type: { id: number; email: string; team: Team | null; posts: Post[] }[]
-```
-
-### Nested relations
-
-```typescript
-const usersWithNestedData = await db.query.users.findMany({
-  with: {
-    posts: {
-      with: {
-        comments: {
-          with: {
-            author: true,   // 3 levels deep
-          },
-        },
-      },
-      orderBy: [desc(posts.createdAt)],
-      limit: 10,
-    },
-  },
-});
-```
-
-### findFirst
-
-```typescript
-const user = await db.query.users.findFirst({
-  where: eq(users.id, userId),
-  with: { team: true },
-});
-// Type: { id: number; email: string; team: Team | null } | undefined
-```
-
-### Selecting specific columns
-
-```typescript
-const userEmails = await db.query.users.findMany({
-  columns: {
-    id: true,
-    email: true,
-    // Other columns excluded from result type
-  },
-  where: eq(users.isActive, true),
-});
-// Type: { id: number; email: string }[]
-```
-
-### Filtering relations
-
-```typescript
-const teamsWithActiveMembers = await db.query.teams.findMany({
-  with: {
-    members: {
-      where: eq(users.isActive, true),
-      orderBy: [asc(users.displayName)],
-      limit: 50,
-    },
-  },
-});
-```
-
-## SQL-like query API
-
-### Select with joins
-
-```typescript
-import { eq, and, or, gt, like, sql } from "drizzle-orm";
-
-// Inner join
-const results = await db
-  .select({
-    userName: users.displayName,
-    teamName: teams.name,
-  })
-  .from(users)
-  .innerJoin(teams, eq(users.teamId, teams.id))
-  .where(eq(users.isActive, true));
-
-// Left join (nullable team)
-const results = await db
-  .select()
-  .from(users)
-  .leftJoin(teams, eq(users.teamId, teams.id));
-// Type includes { users: User; teams: Team | null }
-```
-
-### Complex WHERE clauses
-
-```typescript
-const filtered = await db
-  .select()
-  .from(users)
-  .where(
-    and(
-      eq(users.isActive, true),
-      or(
-        like(users.email, "%@company.com"),
-        eq(users.role, "admin"),
-      ),
-      gt(users.createdAt, new Date("2024-01-01")),
-    )
-  );
-```
-
-### Insert
-
-```typescript
-// Single insert with returning
-const [newUser] = await db
-  .insert(users)
-  .values({
-    email: "new@example.com",
-    displayName: "New User",
-  })
-  .returning();
-
-// Bulk insert
-await db.insert(users).values([
-  { email: "a@example.com", displayName: "User A" },
-  { email: "b@example.com", displayName: "User B" },
-]);
-
-// Upsert (insert or update on conflict)
-await db
-  .insert(users)
-  .values({ email: "upsert@example.com", displayName: "Upserted" })
-  .onConflictDoUpdate({
-    target: users.email,
-    set: { displayName: "Upserted" },
-  });
-```
-
-### Update
-
-```typescript
-const [updated] = await db
-  .update(users)
-  .set({
-    displayName: "Updated Name",
-    updatedAt: new Date(),
-  })
-  .where(eq(users.id, userId))
-  .returning();
-```
-
-### Delete
-
-```typescript
-const [deleted] = await db
-  .delete(users)
-  .where(eq(users.id, userId))
-  .returning();
-```
-
-## Transactions
-
-```typescript
-// Basic transaction
-const result = await db.transaction(async (tx) => {
-  const [team] = await tx
-    .insert(teams)
-    .values({ name: "New Team" })
-    .returning();
-
-  const [user] = await tx
-    .update(users)
-    .set({ teamId: team.id })
-    .where(eq(users.id, userId))
-    .returning();
-
-  return { team, user };
-});
-
-// Transaction with rollback
-await db.transaction(async (tx) => {
-  await tx.insert(orders).values(orderData);
-  await tx.update(inventory).set({ quantity: sql`quantity - 1` })
-    .where(eq(inventory.productId, productId));
-
-  // Check constraint
-  const [item] = await tx
-    .select({ quantity: inventory.quantity })
-    .from(inventory)
-    .where(eq(inventory.productId, productId));
-
-  if (item.quantity < 0) {
-    tx.rollback();  // Explicit rollback
-  }
-});
-```
-
-- Always use transactions for multi-table writes.
-- Throwing inside the callback also triggers rollback.
-- The `tx` object has the same API as `db` but runs within the transaction.
-
-## Aggregations
-
-```typescript
-import { count, sum, avg, min, max, sql } from "drizzle-orm";
-
-// Count users per team
-const teamCounts = await db
-  .select({
-    teamId: users.teamId,
-    teamName: teams.name,
-    memberCount: count(users.id),
-  })
-  .from(users)
-  .innerJoin(teams, eq(users.teamId, teams.id))
-  .groupBy(users.teamId, teams.name);
-
-// Conditional aggregation
-const stats = await db
-  .select({
-    total: count(),
-    activeCount: sql<number>`count(*) filter (where ${users.isActive} = true)`,
-    avgNameLength: avg(sql`length(${users.displayName})`),
-  })
-  .from(users);
-```
-
-## Prepared statements
-
-```typescript
-// Define once (module scope or initialization)
-const getUserById = db.query.users
-  .findFirst({
-    where: eq(users.id, sql.placeholder("id")),
-    with: { team: true },
-  })
-  .prepare("get_user_by_id");
-
-// Execute many times (request scope)
-const user = await getUserById.execute({ id: 42 });
-```
-
-- Prepared statements skip SQL compilation on repeated calls.
-- Use for hot-path queries (auth checks, profile loads, list endpoints).
-- The placeholder name must match the execute parameter key.
-
-## Pagination patterns
-
-### Cursor-based (recommended)
-
-```typescript
-async function getUsers(cursor?: number, limit = 20) {
-  const conditions = [eq(users.isActive, true)];
-  if (cursor) {
-    conditions.push(gt(users.id, cursor));
-  }
-
-  const results = await db
-    .select()
-    .from(users)
-    .where(and(...conditions))
-    .orderBy(asc(users.id))
-    .limit(limit + 1);  // Fetch one extra to detect hasMore
-
-  const hasMore = results.length > limit;
-  const items = hasMore ? results.slice(0, -1) : results;
-  const nextCursor = hasMore ? items[items.length - 1].id : null;
-
-  return { items, nextCursor, hasMore };
-}
-```
-
-### Offset-based (simple but slow on large tables)
-
-```typescript
-const page = await db
-  .select()
-  .from(users)
-  .orderBy(asc(users.id))
-  .limit(20)
-  .offset(page * 20);
-```
-
-- Prefer cursor-based pagination. Offset scans and discards rows.
-- At offset 100,000, the database reads 100,020 rows to return 20.
-
-## Raw SQL escape hatch
-
-```typescript
-import { sql } from "drizzle-orm";
-
-// Typed raw SQL
-const result = await db.execute<{ count: number }>(
-  sql`SELECT count(*) as count FROM users WHERE created_at > ${cutoffDate}`
-);
-
-// Raw SQL in expressions
-const results = await db
-  .select({
-    id: users.id,
-    emailDomain: sql<string>`split_part(${users.email}, '@', 2)`,
-  })
-  .from(users);
-```
-
-- Use `sql` template tag to prevent SQL injection. Parameters are automatically escaped.
-- Use `sql<ReturnType>` generic to type the result of raw expressions.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/drizzle-orm/references/schema-definition.md

@@ -1,233 +0,0 @@
-# Schema Definition
-
-Load this when defining or refactoring Drizzle table schemas, column types, constraints, relations, or type inference patterns.
-
-## Table definition patterns
-
-### Postgres
-
-```typescript
-import {
-  pgTable, serial, text, varchar, integer, boolean,
-  timestamp, uuid, pgEnum, uniqueIndex, index,
-} from "drizzle-orm/pg-core";
-
-// Enum definition (Postgres native ENUM)
-export const roleEnum = pgEnum("role", ["admin", "member", "viewer"]);
-
-export const users = pgTable(
-  "users",
-  {
-    id: serial("id").primaryKey(),
-    email: varchar("email", { length: 255 }).notNull().unique(),
-    displayName: varchar("display_name", { length: 100 }).notNull(),
-    bio: text("bio"),  // nullable by default
-    role: roleEnum("role").notNull().default("member"),
-    isActive: boolean("is_active").notNull().default(true),
-    createdAt: timestamp("created_at", { withTimezone: true })
-      .notNull()
-      .defaultNow(),
-    updatedAt: timestamp("updated_at", { withTimezone: true }),
-  },
-  (table) => [
-    uniqueIndex("ix_users_email").on(table.email),
-  ]
-);
-```
-
-### SQLite
-
-```typescript
-import {
-  sqliteTable, integer, text,
-} from "drizzle-orm/sqlite-core";
-
-export const users = sqliteTable("users", {
-  id: integer("id").primaryKey({ autoIncrement: true }),
-  email: text("email").notNull().unique(),
-  displayName: text("display_name").notNull(),
-  role: text("role", { enum: ["admin", "member", "viewer"] })
-    .notNull()
-    .default("member"),
-  isActive: integer("is_active", { mode: "boolean" }).notNull().default(true),
-  createdAt: integer("created_at", { mode: "timestamp" })
-    .notNull()
-    .$defaultFn(() => new Date()),
-});
-```
-
-- Postgres uses `pgTable`, SQLite uses `sqliteTable`, MySQL uses `mysqlTable`. Never mix them.
-- SQLite has no native boolean or timestamp. Use `integer` with `mode` to get type-safe wrappers.
-- Column names in quotes are the database column names. The object key is the TypeScript property name.
-
-## Type inference
-
-```typescript
-// Infer types directly from schema — never define interfaces manually
-export type User = typeof users.$inferSelect;        // SELECT result type
-export type NewUser = typeof users.$inferInsert;      // INSERT input type
-
-// Use with function signatures
-async function createUser(data: NewUser): Promise<User> {
-  const [user] = await db.insert(users).values(data).returning();
-  return user;
-}
-
-// Partial updates
-type UserUpdate = Partial<Omit<NewUser, "id" | "createdAt">>;
-```
-
-- `$inferSelect` includes all columns with their nullability.
-- `$inferInsert` omits columns with defaults (serial, defaultNow, etc.) and makes them optional.
-- Never create manual `interface User { ... }`. It will drift from the schema.
-
-## Relations
-
-```typescript
-import { relations } from "drizzle-orm";
-
-export const teams = pgTable("teams", {
-  id: serial("id").primaryKey(),
-  name: varchar("name", { length: 100 }).notNull(),
-});
-
-export const users = pgTable("users", {
-  id: serial("id").primaryKey(),
-  email: varchar("email", { length: 255 }).notNull(),
-  teamId: integer("team_id").references(() => teams.id),
-});
-
-// Relation declarations (separate from table definitions)
-export const teamsRelations = relations(teams, ({ many }) => ({
-  members: many(users),
-}));
-
-export const usersRelations = relations(users, ({ one }) => ({
-  team: one(teams, {
-    fields: [users.teamId],
-    references: [teams.id],
-  }),
-}));
-```
-
-### Relation rules
-
-- `one()` = many-to-one or one-to-one. Requires `fields` and `references`.
-- `many()` = one-to-many. No `fields`/`references` needed (inferred from the other side).
-- Relations are declared separately from tables. They do NOT create database constraints.
-- Foreign keys (`.references()`) create database constraints. Relations are for the query API.
-- You need BOTH: `.references()` on the column for database integrity, `relations()` for the query API.
-
-## Many-to-many with junction table
-
-```typescript
-export const projects = pgTable("projects", {
-  id: serial("id").primaryKey(),
-  name: varchar("name", { length: 200 }).notNull(),
-});
-
-export const usersToProjects = pgTable(
-  "users_to_projects",
-  {
-    userId: integer("user_id")
-      .notNull()
-      .references(() => users.id),
-    projectId: integer("project_id")
-      .notNull()
-      .references(() => projects.id),
-  },
-  (table) => [
-    // Composite primary key
-    { primaryKey: { columns: [table.userId, table.projectId] } },
-  ]
-);
-
-export const usersToProjectsRelations = relations(
-  usersToProjects,
-  ({ one }) => ({
-    user: one(users, {
-      fields: [usersToProjects.userId],
-      references: [users.id],
-    }),
-    project: one(projects, {
-      fields: [usersToProjects.projectId],
-      references: [projects.id],
-    }),
-  })
-);
-
-export const usersRelations = relations(users, ({ many }) => ({
-  projects: many(usersToProjects),
-}));
-
-export const projectsRelations = relations(projects, ({ many }) => ({
-  members: many(usersToProjects),
-}));
-```
-
-- Drizzle does not have implicit M2M like Prisma. You always define the junction table.
-- Query through the junction: `db.query.users.findMany({ with: { projects: { with: { project: true } } } })`.
-
-## Constraints and indexes
-
-```typescript
-import { primaryKey, uniqueIndex, index } from "drizzle-orm/pg-core";
-
-export const auditLogs = pgTable(
-  "audit_logs",
-  {
-    id: serial("id").primaryKey(),
-    entityType: varchar("entity_type", { length: 50 }).notNull(),
-    entityId: integer("entity_id").notNull(),
-    tenantId: integer("tenant_id").notNull(),
-    action: varchar("action", { length: 20 }).notNull(),
-    createdAt: timestamp("created_at", { withTimezone: true })
-      .notNull()
-      .defaultNow(),
-  },
-  (table) => [
-    index("ix_audit_entity").on(table.entityType, table.entityId),
-    uniqueIndex("ix_audit_tenant_entity").on(
-      table.tenantId, table.entityType, table.entityId
-    ),
-  ]
-);
-```
-
-- Always name indexes and constraints explicitly. Autogenerated names differ across databases.
-- Use composite indexes for queries that filter on multiple columns together.
-
-## UUID primary keys
-
-```typescript
-import { uuid } from "drizzle-orm/pg-core";
-
-export const documents = pgTable("documents", {
-  id: uuid("id").primaryKey().defaultRandom(),
-  title: varchar("title", { length: 300 }).notNull(),
-});
-```
-
-- `defaultRandom()` generates UUID v4 at the database level.
-- For time-sortable UUIDs (UUID v7), use `$defaultFn(() => uuidv7())` with a library.
-
-## Schema organization
-
-```
-src/
-  db/
-    schema/
-      users.ts        # users table + relations
-      teams.ts        # teams table + relations
-      projects.ts     # projects table + relations
-      index.ts        # re-exports all tables and relations
-    index.ts          # drizzle() instance
-    migrate.ts        # migration runner
-drizzle/
-  migrations/         # generated migration SQL files
-drizzle.config.ts     # drizzle-kit configuration
-```
-
-- One file per domain entity (table + its relations).
-- Re-export from `schema/index.ts` so drizzle-kit can find all tables.
-- Keep the `drizzle()` instance in a separate file from schema definitions.

package/workflows/workflows/agent-environment-setup/platforms/codex/skills/electron-qa/SKILL.md

@@ -1,94 +0,0 @@
----
-name: electron-qa
-description: "Use when testing Electron apps with Playwright, validating IPC between main and renderer, checking native modules, verifying packaging, or setting up Electron CI."
----
-# Electron QA
-
-## Purpose
-
-You are the specialist for quality assurance of Electron desktop applications. Electron apps combine a Chromium renderer with a Node.js main process, creating a unique testing surface that web-only tools cannot fully cover. You handle E2E testing with Playwright's Electron support, IPC communication verification between main and renderer processes, native module compatibility testing, and packaging validation across Windows, macOS, and Linux.
-
-This skill exists because Electron testing requires expertise that spans web testing (DOM, network, browser APIs) and desktop testing (filesystem access, system tray, native menus, OS notifications, code signing). Standard web testing skills miss the main process entirely, and standard desktop testing tools do not understand web renderers.
-
-## When to Use
-
-- Writing E2E tests for an Electron application using Playwright's Electron API
-- Testing IPC communication (ipcMain/ipcRenderer, contextBridge, preload scripts)
-- Validating native Node.js modules work correctly inside Electron's runtime
-- Verifying packaged application binaries (installers, DMGs, AppImages) install and launch correctly
-- Setting up CI/CD pipelines for Electron builds with cross-platform testing
-- Debugging renderer crashes, main process hangs, or IPC deserialization failures
-- Reviewing test coverage for missing IPC edge cases, platform-specific bugs, or security boundary violations
-
-## Instructions
-
-1. **Map the application architecture** — Identify the main process entry point, preload scripts, renderer pages, and IPC channels, because Electron apps have at least two JavaScript execution contexts and tests must cover the boundary between them.
-
-2. **Choose the testing stack** — Use Playwright's built-in Electron support (`electron = await _electron.launch()`) as the primary E2E framework. Load `references/e2e-testing.md` for setup details, because Playwright provides first-class Electron APIs that Spectron (deprecated) and WebDriverIO lack.
-
-3. **Separate tests by process boundary** — Organize tests into main process, preload, and renderer categories, because each process runs in a different execution context with different available APIs. Tests that blur process boundaries produce false positives by accessing APIs unavailable in the actual runtime.
-
-4. **Test IPC handlers in isolation** — Mock `ipcMain` and `ipcRenderer` with typed channel contracts, because IPC is the primary communication boundary in Electron. Load `references/ipc-testing.md` for patterns. Testing handlers without full application startup verifies serialization, error handling, and response shapes in milliseconds.
-
-5. **Define typed IPC channel maps** — Create a shared TypeScript interface for all IPC channels and validate both sides against it, because IPC channels are stringly-typed by default. A shared type definition catches channel name mismatches, payload drift, and missing handlers at compile time.
-
-6. **Test preload scripts under production constraints** — Verify contextBridge behavior with `contextIsolation: true` and `sandbox: true`, because preload scripts bridge processes through `contextBridge.exposeInMainWorld`. Testing without security constraints masks API exposure bugs that fail in production builds.
-
-7. **Validate native modules** — Load `references/native-modules.md` and verify that native Node.js modules (better-sqlite3, node-pty, sharp) load and function inside Electron's runtime. Mock them at the boundary in unit tests for CI portability, because native modules compiled against standard Node.js may crash due to ABI differences.
-
-8. **Write platform-conditional tests** — Test system tray icons, native menus, global shortcuts, file associations, and OS notifications on each target platform, because these use platform-specific APIs and behave differently across Windows, macOS, and Linux.
-
-9. **Validate BrowserWindow configuration** — Assert on `webPreferences` after window creation, because misconfigured preferences (missing contextIsolation, enabled nodeIntegration, wrong preload path) are the most common Electron security vulnerabilities.
-
-10. **Verify packaging** — Load `references/packaging.md` and validate that packaged applications (DMG, NSIS, AppImage) install correctly, launch without errors, and include all required resources. Check ASAR archive contents because packaging errors are the most common Electron deployment failures.
-
-11. **Test auto-update flow** — Mock `electron-updater` responses with known version manifests, because testing against a real update server is non-deterministic. Verify the download, signature verification, and install-on-quit lifecycle.
-
-12. **Validate code signing** — Verify macOS notarization with `codesign --verify` and Windows Authenticode signatures, because unsigned binaries trigger OS security warnings that prevent installation.
-
-13. **Set up CI pipelines** — Load `references/ci-setup.md` and configure CI to build, test, and package on all target platforms. Electron CI requires display servers (Xvfb on Linux), platform-specific build tools, and significant disk/memory resources.
-
-14. **Test crash recovery** — Programmatically crash the renderer and verify the main process detects it via `webContents.on('render-process-gone')` and restarts gracefully, because untested crash handlers leave the application unresponsive.
-
-15. **Measure startup performance** — Assert on cold start time (process launch to first paint) and warm start time (window show to interactive), because Electron apps have perceptible startup cost from Chromium initialization and regression tests catch performance degradations early.
-
-16. **Test deep links and protocol handlers** — Simulate `app.on('open-url')` and custom protocol events, because deep links are a common integration point for single-instance enforcement and external auth flows that fail silently when untested.
-
-17. **Document the test matrix** — Create a table showing which tests run on which platforms, which require display servers, and which test packaging vs. development mode, because Electron test suites are more complex than web test suites.
-
-## Output Format
-
-Deliver:
-
-1. **Test suite configuration** — Playwright config with Electron launch setup
-2. **E2E test files** — Renderer UI tests using Playwright's Electron API
-3. **IPC test files** — Main-renderer communication verification with typed contracts
-4. **Native module tests** — Validation that native dependencies load correctly
-5. **Packaging validation script** — Automated checks for packaged binaries
-6. **CI pipeline config** — GitHub Actions or equivalent for cross-platform builds
-7. **Test matrix** — Table documenting platform coverage and test categories
-
-## References
-
-| File | Load when |
-| --- | --- |
-| `references/e2e-testing.md` | Setting up Playwright for Electron, launching the app, or writing renderer tests |
-| `references/ipc-testing.md` | Testing main-renderer IPC channels, contextBridge, or preload scripts |
-| `references/native-modules.md` | Validating native Node.js modules, rebuilding for Electron, or debugging ABI mismatches |
-| `references/packaging.md` | Building installers, verifying packaged apps, code signing, or auto-update testing |
-| `references/ci-setup.md` | Configuring CI pipelines for Electron builds, cross-platform testing, or artifact publishing |
-
-## Codex Platform Notes
-
-- Codex supports native subagents via `.codex/agents/*.toml` files with `name`, `description`, and `developer_instructions`.
-- Each subagent TOML can specify `model` and `model_reasoning_effort` to optimize cost per task difficulty:
-  - Light tasks (exploration, docs): `model = "gpt-5.3-codex-spark"`, `model_reasoning_effort = "medium"`
-  - Heavy tasks (security audit, orchestration): `model = "gpt-5.4"`, `model_reasoning_effort = "high"`
-  - Standard tasks (implementation): inherit parent model (omit `model` field).
-- Built-in agents: `default`, `worker`, `explorer`. Custom agents extend these via TOML definitions.
-- Codex operates under network restrictions — skills should not assume outbound HTTP access.
-- Use `$ARGUMENTS` to access user-provided arguments when the skill is invoked.
-- All skill guidance executes within the sandbox; file I/O is confined to the workspace.
-- Skills are installed at `.agents/skills/<skill-id>/SKILL.md`. Workflow skills can also be compiled to `.agents/skills/<workflow-id>/SKILL.md` as `generatedSkills`.
-- Codex supports three autonomy levels: `suggest`, `auto-edit`, `full-auto`.
-- MCP skill tools are available when the Cubis Foundry MCP server is connected.