worklow

Author: izadoesdev

.agents/skills/bun-fullstack/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: typescript-bun-drizzle-quality
+description: Build or review Bun fullstack TypeScript code with Drizzle-backed SQL. Use for backend or cross-layer changes touching API/domain logic, schema or query design, migrations, runtime/type debugging, and boundary validation between contracts, business rules, and persistence.
+---
+
+# TypeScript Bun Drizzle Quality
+
+Use this as an umbrella fullstack skill for Bun + TypeScript + Drizzle work.
+
+For slop-reduction/refactor passes focused on deleting custom helpers/types/assertions, use
+[`../desloppify/SKILL.md`](../desloppify/SKILL.md) alongside this skill.
+
+Deliver production-grade code by optimizing for:
+
+- type safety and clarity
+- predictable runtime behavior in Bun
+- correct and reversible data changes with Drizzle
+- clean contract boundaries between API, domain logic, and persistence
+
+## Repository Overrides (Required When Present)
+
+Always follow repository-level agent rules (for example `AGENTS.md`) when they are stricter than this skill.
+
+In this repository, enforce these defaults while using this skill:
+
+- keep things in one function unless extraction is clearly reusable
+- avoid `try`/`catch` where practical; prefer explicit control flow
+- avoid `else`; prefer early returns
+- avoid `any` and broad assertions
+- prefer single-word names when possible
+- avoid unnecessary destructuring; prefer dot access
+- prefer functional array methods over loops when practical
+- prefer Bun-native APIs like `Bun.file()` where practical
+- run tests from package directories, not repository root, when root test is guarded
+
+## Track Selection
+
+Choose the track before coding:
+
+1. App/API logic track
+   - Use when changing handlers, services, orchestration, auth, or domain rules.
+2. Data layer track
+   - Use when changing Drizzle schema, migrations, indexes, transactions, or query shape.
+3. Fullstack integration track
+   - Use when changes cross boundaries (API contract + domain behavior + database effects).
+
+If multiple tracks apply, run App/API first, then Data layer, then Integration checks.
+
+## 1) Define Constraints First
+
+Before coding, pin down:
+
+- runtime: Bun version and package manager commands
+- database: SQL dialect (Postgres/MySQL/SQLite/Turso) and migration flow
+- API shape: request/response contracts and error model
+- compatibility: expected behavior changes vs strict backward compatibility
+
+If context is missing, ask only for blocking details. Otherwise proceed with explicit assumptions.
+
+## 2) Adapt to the Host Repository
+
+Distill practices into the target repository instead of assuming fixed commands or structure.
+
+Before implementation or review:
+
+- inspect workspace scripts to discover quality gates (typecheck, lint/format, test)
+- inspect CI workflows to confirm which checks are required in pull requests
+- identify local test taxonomy and map commands to:
+  - unit tests
+  - integration tests
+  - e2e tests
+- run only the smallest relevant subset for touched code paths
+
+Do not assume naming conventions like `test:unit` or `test:e2e`; infer from scripts and workflow usage.
+
+## 3) Fullstack Testing with Bun (Required)
+
+Treat test design and test execution as first-class implementation work.
+
+Use this decision flow:
+
+1. classify repository test commands by behavior into unit, integration, and e2e
+2. map touched files/modules to the smallest package/service-local commands
+3. if root `test` is guarded (for example intentionally fails), do not run tests from root
+4. run required layers in order: unit -> integration -> e2e, based on scope/risk
+5. ensure CI-required checks for pull requests are represented in local verification
+6. if no explicit integration suite exists, treat boundary tests (API + real DB or equivalent) as integration coverage and call it out
+
+Technical expectations for Bun repositories:
+
+- use Bun test runner features intentionally (`bun test`, `--watch`, `--preload`, `--timeout`, path filters)
+- keep unit tests deterministic and fast; avoid network and global time randomness
+- for integration tests, run real migrations/schema setup and isolate test data
+- for e2e, run realistic app wiring and capture artifacts on failure
+
+Do not mark work complete unless one of these is true:
+
+- relevant tests were executed and results were recorded
+- execution was blocked by environment constraints and the block + residual risk were stated explicitly
+
+For deeper guidance, read `references/testing-patterns.md`.
+For copyable boundary snippets, read `references/examples/integration-boundary-test.md`.
+
+## 4) App/API Logic Track
+
+Prefer:
+
+- narrow, composable functions with explicit inputs and outputs
+- inferred types where clear, explicit types at boundaries (public functions, adapters, exported utilities)
+- discriminated unions for branching states
+- `unknown` + schema validation for untrusted input
+- early returns over deeply nested branching
+
+Avoid:
+
+- `any` unless unavoidable and scoped with justification
+- broad `as` assertions that bypass type checks
+- duplicated business logic between handlers, services, and tests
+
+Use Zod (or equivalent) to enforce runtime contracts at process boundaries.
+For copyable handler patterns, read `references/examples/api-boundary.md`.
+
+Use Bun-native patterns when they simplify runtime behavior:
+
+- file I/O: `Bun.file`, `Bun.write`
+- scripting and process execution: Bun shell APIs
+- tests and fixtures: Bun test runner patterns
+
+Keep Node compatibility shims only when required by dependencies or deployment targets.
+
+## 5) Data Layer Track
+
+When touching schema, models, or queries:
+
+- keep naming stable and consistent across schema and code
+- preserve backward compatibility unless migration plan explicitly breaks it
+- create reversible migrations where possible
+- include indexes/constraints intentionally, not implicitly
+- validate nullability/default changes against existing data
+
+For deeper patterns, read `references/drizzle-patterns.md`.
+For copyable transaction/query patterns, read `references/examples/drizzle-transaction.md`.
+
+## 6) Fullstack Integration Track
+
+When a change crosses boundaries, explicitly validate:
+
+- API contract to domain mapping (validation, defaults, and error translation)
+- domain rules to persistence behavior (transactions, consistency, rollback behavior)
+- persistence results to API output shape (including empty and partial data cases)
+- backward compatibility for clients and existing data
+- corresponding test coverage across unit/integration/e2e layers where applicable
+
+Use the review rubric in `references/quality-checklist.md` to structure findings.
+For end-to-end mapping examples, read `references/examples/fullstack-flow.md`.
+
+## Output Format
+
+Use this as the canonical output template for this skill:
+
+1. What changed and why
+2. Risk assessment (behavioral, data, performance)
+3. Verification performed or intentionally skipped
+4. Required fixes vs optional improvements
+5. Remaining gaps or follow-ups
+
+Keep output concise and concrete. Avoid generic "looks good" conclusions without evidence.
+
+## Canonical Documentation
+
+Use official docs when clarifying edge behavior:
+
+- Bun docs: https://bun.sh/docs
+- Drizzle ORM docs: https://orm.drizzle.team/docs/overview
+- Drizzle migrations docs: https://orm.drizzle.team/docs/migrations
+- Zod docs: https://zod.dev
+- Turbo docs: https://turbo.build/repo/docs

.agents/skills/bun-fullstack/references/drizzle-patterns.md

@@ -0,0 +1,52 @@
+# Drizzle Patterns
+
+Use this reference for schema, migration, and query quality decisions.
+
+## Canonical Documentation
+
+- Drizzle overview: https://orm.drizzle.team/docs/overview
+- Drizzle schema declaration: https://orm.drizzle.team/docs/sql-schema-declaration
+- Drizzle migrations: https://orm.drizzle.team/docs/migrations
+- Drizzle indexes and constraints: https://orm.drizzle.team/docs/indexes-constraints
+
+## Schema Design
+
+- Keep table and column names consistent and predictable.
+- Prefer explicit foreign keys and on-delete behavior.
+- Add unique constraints only when they represent real domain invariants.
+- Avoid overloading nullable columns to represent multiple states.
+
+## Migration Safety
+
+- Split risky migrations into phases:
+  1. Additive changes first (new columns/tables/indexes).
+  2. Backfill data in controlled steps.
+  3. Switch reads/writes.
+  4. Remove deprecated fields after validation.
+- Prefer reversible migrations when possible.
+- Document expected lock/performance impact for large tables.
+
+## Query Quality
+
+- Select only required columns on hot paths.
+- Encode filters and joins so intent is obvious to reviewers.
+- Keep pagination deterministic (stable ordering).
+- Treat optional relations explicitly to avoid accidental cartesian or null surprises.
+
+## Transaction Boundaries
+
+- Group related writes in a transaction when partial writes would corrupt state.
+- Keep transactions short and side-effect free.
+- Avoid calling external systems from inside a DB transaction.
+
+## Data Integrity Checks
+
+- Validate assumptions before destructive updates.
+- Include guard conditions in update/delete operations.
+- For one-off scripts, produce dry-run output before apply mode.
+
+## Testing Drizzle Changes
+
+- Add integration tests for query behavior and constraints.
+- Verify migration up/down (or rollback alternative) in non-prod environments.
+- Test with representative edge data: nulls, duplicates, missing relations, and large sets.

.agents/skills/bun-fullstack/references/examples/api-boundary.md

@@ -0,0 +1,42 @@
+# API Boundary Validation Example
+
+```ts
+import { z } from "zod";
+
+const in_schema = z.object({
+  email: z.email(),
+  role: z.enum(["admin", "member"]).default("member"),
+});
+
+const out_schema = z.object({
+  id: z.string(),
+  email: z.email(),
+  role: z.enum(["admin", "member"]),
+});
+
+type Ctx = {
+  req: {
+    json: () => Promise<unknown>;
+  };
+  json: (body: unknown, status?: number) => Response;
+};
+
+export async function post_user(ctx: Ctx) {
+  const raw = await ctx.req.json();
+  const parsed = in_schema.safeParse(raw);
+  if (!parsed.success)
+    return ctx.json({ error: "invalid_input", detail: parsed.error.issues }, 400);
+
+  const row = await create_user(parsed.data);
+  const out = out_schema.parse(row);
+  return ctx.json(out, 201);
+}
+
+async function create_user(input: z.infer<typeof in_schema>) {
+  return {
+    id: crypto.randomUUID(),
+    email: input.email,
+    role: input.role,
+  };
+}
+```

.agents/skills/bun-fullstack/references/examples/drizzle-transaction.md

@@ -0,0 +1,57 @@
+# Drizzle Transaction Example
+
+```ts
+import { and, eq, gte, sql } from "drizzle-orm";
+
+type Db = {
+  transaction: <T>(fn: (tx: Tx) => Promise<T>) => Promise<T>;
+};
+
+type Tx = {
+  query: {
+    account: {
+      findFirst: (q: unknown) => Promise<{ id: string; balance: number } | undefined>;
+    };
+  };
+  update: (table: unknown) => {
+    set: (values: Record<string, unknown>) => {
+      where: (clause: unknown) => Promise<{ rowsAffected: number }>;
+    };
+  };
+  insert: (table: unknown) => {
+    values: (row: Record<string, unknown>) => Promise<void>;
+  };
+};
+
+declare const account: unknown;
+declare const ledger: unknown;
+
+export async function debit(db: Db, account_id: string, amount: number) {
+  if (amount <= 0) throw new Error("amount must be positive");
+
+  return db.transaction(async (tx) => {
+    const row = await tx.query.account.findFirst({
+      where: eq(sql`id`, account_id),
+      columns: { id: true, balance: true },
+    });
+    if (!row) throw new Error("account not found");
+    if (row.balance < amount) throw new Error("insufficient funds");
+
+    const res = await tx
+      .update(account)
+      .set({ balance: row.balance - amount })
+      .where(and(eq(sql`id`, account_id), gte(sql`balance`, amount)));
+
+    if (res.rowsAffected !== 1) throw new Error("concurrent update conflict");
+
+    await tx.insert(ledger).values({
+      id: crypto.randomUUID(),
+      account_id,
+      amount: -amount,
+      created_at: Date.now(),
+    });
+
+    return { account_id, debited: amount };
+  });
+}
+```

.agents/skills/bun-fullstack/references/examples/fullstack-flow.md

@@ -0,0 +1,49 @@
+# Fullstack Request-to-Response Mapping Example
+
+```ts
+import { z } from "zod";
+
+const in_schema = z.object({
+  title: z.string().min(1),
+  done: z.boolean().default(false),
+});
+
+const out_schema = z.object({
+  id: z.string(),
+  title: z.string(),
+  done: z.boolean(),
+  created_at: z.number(),
+});
+
+type Db = {
+  insert: (table: unknown) => {
+    values: (row: Record<string, unknown>) => {
+      returning: () => Promise<unknown[]>;
+    };
+  };
+};
+
+declare const todos: unknown;
+
+export async function post_todo(body: unknown, db: Db) {
+  const parsed = in_schema.safeParse(body);
+  if (!parsed.success)
+    return { status: 400, body: { error: "invalid_input", detail: parsed.error.issues } };
+
+  const rows = await db
+    .insert(todos)
+    .values({
+      id: crypto.randomUUID(),
+      title: parsed.data.title,
+      done: parsed.data.done,
+      created_at: Date.now(),
+    })
+    .returning();
+
+  const row = rows.at(0);
+  if (!row) return { status: 500, body: { error: "insert_failed" } };
+
+  const out = out_schema.parse(row);
+  return { status: 201, body: out };
+}
+```