@strayl/agent 0.1.3 → 0.1.5

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@strayl/agent",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
   "main": "dist/index.js",
+  "files": [
+    "dist",
+    "skills"
+  ],
   "scripts": {
     "build": "esbuild src/index.ts --bundle --platform=node --target=node20 --format=esm --outfile=dist/agent.js --external:fsevents",
     "dev": "tsx watch src/index.ts"

package/skills/api-creation/SKILL.md

@@ -0,0 +1,631 @@
+---
+name: api-creation
+description: Create server-side API logic in a TanStack Start app using createServerFn, Drizzle ORM, and Zod validation. Use when the user needs backend endpoints, CRUD operations, data fetching, or server-side business logic.
+---
+
+# API Creation
+
+## When to Use
+
+- User asks to create an API, endpoint, server function, or backend logic
+- User needs CRUD operations (create, read, update, delete) for any entity
+- User wants to fetch data from the database and display it
+- User mentions "server function", "API", "backend", "endpoint", "CRUD"
+- User asks to "save data", "fetch data", "submit a form", "load from database"
+
+## When NOT to Use
+
+- User only needs client-side state (React state, localStorage, URL search params)
+- User is asking about authentication specifically — use the `authentication` skill
+- User wants to scaffold a new project — use `web-application-creation` skill
+- User only needs to create/modify database schema — use `database-management` skill
+
+## Prerequisites
+
+- A TanStack Start project (scaffolded with `web-application-creation` or existing)
+- A database with tables (via `database-management` skill)
+- If endpoints need auth protection, set up auth first with `authentication` skill
+
+## ⛔ RULE #1 — NEVER Use Dynamic Imports for Server Functions
+
+This is the most common mistake. It **breaks the build** every time.
+
+```typescript
+// ❌ BROKEN — dynamic import inside useEffect, onClick, or any async callback
+useEffect(() => {
+  const load = async () => {
+    const { getTasks } = await import('../server/tasks') // BUILD ERROR
+    setTasks(await getTasks({ userId }))
+  }
+  load()
+}, [userId])
+
+// ❌ BROKEN — same problem inside an event handler
+const handleCreate = async () => {
+  const { createTask } = await import('../server/tasks') // BUILD ERROR
+  await createTask({ ... })
+}
+```
+
+```typescript
+// ✅ CORRECT — static import at top of file, always
+import { getTasks } from '@/server/tasks'
+import { createTask } from '@/server/tasks'
+import { useServerFn } from '@tanstack/react-start'
+
+// GET data → call in route loader
+export const Route = createFileRoute('/tasks')({
+  loader: ({ context }) => getTasks({ userId: context.userId }),
+  component: TasksPage,
+})
+
+// POST mutation → wrap with useServerFn() in component
+function TasksPage() {
+  const create = useServerFn(createTask)
+  const handleCreate = async () => {
+    await create({ data: { title: 'New task', userId } })
+  }
+}
+```
+
+**Why it breaks:** TanStack Start analyzes static imports at build time to split client/server bundles. Dynamic `await import()` bypasses this — the bundler fails or leaks server-only code (DB, env vars) to the client.
+
+## ⛔ RULE #2 — Do NOT Use useEffect for Data Loading
+
+Never load server data inside `useEffect`. Always use route loaders:
+
+```typescript
+// ❌ BROKEN pattern — data fetching in useEffect
+function TasksPage() {
+  const [tasks, setTasks] = useState([])
+  useEffect(() => {
+    // DON'T DO THIS — use loader instead
+    getTasks({ userId }).then(setTasks)
+  }, [userId])
+}
+
+// ✅ CORRECT — data in loader, consumed with useLoaderData()
+export const Route = createFileRoute('/tasks')({
+  loader: ({ context }) => getTasks({ userId: context.userId }),
+  component: TasksPage,
+})
+function TasksPage() {
+  const tasks = Route.useLoaderData() // no useEffect needed
+}
+```
+
+## How to Pass Auth Context to Loaders
+
+When you need `userId` (or any auth data) in a route loader, use the router context — set it once in `__root.tsx` and it flows to all routes automatically:
+
+```typescript
+// src/routes/__root.tsx — use createRootRouteWithContext for TypeScript safety
+import { createRootRouteWithContext } from '@tanstack/react-router'
+import { getUser } from '@/server/auth'
+
+interface RouterContext {
+  user: Awaited<ReturnType<typeof getUser>> | null
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  beforeLoad: async () => {
+    const user = await getUser()
+    return { user } // available as context.user in ALL route loaders
+  },
+  // ...
+})
+
+// src/routes/tasks.tsx — access user in loader (no useEffect needed)
+import { getTasks } from '@/server/tasks'
+export const Route = createFileRoute('/tasks')({
+  loader: ({ context }) => {
+    if (!context.user) return []
+    return getTasks({ userId: context.user.id })
+  },
+  component: TasksPage,
+})
+function TasksPage() {
+  const tasks = Route.useLoaderData() // data from loader, fully typed
+  const { user } = Route.useRouteContext() // auth context in component
+}
+```
+
+This eliminates the need for useEffect-based data loading entirely.
+
+## Core API: createServerFn
+
+All backend logic goes through `createServerFn` from `@tanstack/react-start`. Server functions run on the server (Nitro) and are callable from loaders and client components.
+
+```typescript
+// ✅ CORRECT import path
+import { createServerFn } from "@tanstack/react-start";
+import { useServerFn } from "@tanstack/react-start";
+
+// ❌ WRONG — /server subpath is for entry-point utilities only (createStartHandler, setResponseStatus)
+import { createServerFn } from "@tanstack/react-start/server"; // BUILD ERROR
+```
+
+**Fluent API chain:** `createServerFn({ method }) .inputValidator(fn) .handler(fn)`
+
+- `method: "GET"` — for reads (loaders, data fetching)
+- `method: "POST"` — for mutations (create, update, delete)
+- `.inputValidator()` — validates and types input (use zod)
+- `.handler()` — receives `{ data }` (validated input), returns response
+
+## File Organization
+
+```
+src/
+├── lib/
+│   ├── db.ts              # Drizzle client (single instance)
+│   └── schema.ts          # All table definitions
+├── server/
+│   ├── auth.ts            # Auth functions (if authentication skill used)
+│   ├── posts.ts           # Post server functions
+│   ├── comments.ts        # Comment server functions
+│   └── {entity}.ts        # One file per entity/domain
+└── routes/
+    ├── posts.tsx           # List page (loader calls GET server fn)
+    ├── posts.$postId.tsx   # Detail page (loader with params)
+    └── _authed/
+        └── posts.new.tsx   # Create form (calls POST server fn)
+```
+
+**Convention:** Server functions in `src/server/{entity}.ts`. Routes import and call them. Keeps server logic separate from UI.
+
+## Setup (if not done)
+
+### Database Client
+
+**Check first** — `src/lib/db.ts` may already exist from `authentication` or `database-management`. If not:
+
+```typescript
+// src/lib/db.ts
+import { neon } from "@neondatabase/serverless";
+import { drizzle } from "drizzle-orm/neon-http";
+
+let _db: ReturnType<typeof drizzle>;
+export function db() {
+  if (!_db) {
+    _db = drizzle(neon(process.env.DATABASE_URL!));
+  }
+  return _db;
+}
+```
+
+### Schema
+
+Add table definitions to `src/lib/schema.ts` (edit if exists, create if not):
+
+```typescript
+import { pgTable, serial, text, timestamp, integer, boolean } from "drizzle-orm/pg-core";
+
+export const posts = pgTable("posts", {
+  id: serial("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content").notNull().default(""),
+  authorId: integer("author_id").notNull(),
+  published: boolean("published").notNull().default(false),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+});
+```
+
+After defining schema in code, **create the actual table** via migration:
+```
+universal({ tool: "prepare_database_migration", params: { migrationSql: "CREATE TABLE IF NOT EXISTS posts (...)" } })
+```
+
+## Patterns
+
+### GET — List All
+
+```typescript
+// src/server/posts.ts
+import { createServerFn } from "@tanstack/react-start";
+import { db } from "@/lib/db";
+import { posts } from "@/lib/schema";
+import { desc, eq } from "drizzle-orm";
+
+export const getPosts = createServerFn({ method: "GET" }).handler(async () => {
+  return db().select().from(posts).orderBy(desc(posts.createdAt));
+});
+```
+
+**In a route loader:**
+```typescript
+// src/routes/posts.tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { getPosts } from "@/server/posts";
+
+export const Route = createFileRoute("/posts")({
+  loader: () => getPosts(),
+  component: PostsPage,
+});
+
+function PostsPage() {
+  const posts = Route.useLoaderData();
+  return (
+    <div className="container mx-auto p-6">
+      {posts.map((post) => (
+        <div key={post.id}>{post.title}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+### GET — Single by ID
+
+```typescript
+export const getPost = createServerFn({ method: "GET" })
+  .inputValidator((id: number) => id)
+  .handler(async ({ data: id }) => {
+    const [post] = await db().select().from(posts).where(eq(posts.id, id)).limit(1);
+    if (!post) throw new Error("Post not found");
+    return post;
+  });
+```
+
+**In a route with params:**
+```typescript
+// src/routes/posts.$postId.tsx
+export const Route = createFileRoute("/posts/$postId")({
+  loader: ({ params }) => getPost({ data: Number(params.postId) }),
+  component: PostPage,
+});
+```
+
+### POST — Create with Validation
+
+```typescript
+import { z } from "zod";
+
+const createPostSchema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().max(50000).default(""),
+});
+
+export const createPost = createServerFn({ method: "POST" })
+  .inputValidator((d: unknown) => createPostSchema.parse(d))
+  .handler(async ({ data }) => {
+    const [post] = await db()
+      .insert(posts)
+      .values({ title: data.title, content: data.content, authorId: 1 })
+      .returning();
+    return post;
+  });
+```
+
+**Calling from a component:**
+```typescript
+import { useServerFn } from "@tanstack/react-start";
+import { useNavigate } from "@tanstack/react-router";
+import { createPost } from "@/server/posts";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+function CreatePostForm() {
+  const navigate = useNavigate();
+  const create = useServerFn(createPost);
+  const [error, setError] = useState("");
+
+  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    setError("");
+    const formData = new FormData(e.currentTarget);
+    try {
+      const post = await create({
+        data: {
+          title: formData.get("title") as string,
+          content: formData.get("content") as string,
+        },
+      });
+      navigate({ to: "/posts/$postId", params: { postId: String(post.id) } });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Something went wrong");
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-4">
+      {error && <p className="text-sm text-destructive">{error}</p>}
+      <div className="space-y-2">
+        <Label htmlFor="title">Title</Label>
+        <Input id="title" name="title" required />
+      </div>
+      <div className="space-y-2">
+        <Label htmlFor="content">Content</Label>
+        <textarea id="content" name="content" className="w-full rounded-md border bg-background p-3" />
+      </div>
+      <Button type="submit">Create Post</Button>
+    </form>
+  );
+}
+```
+
+### POST — Update
+
+```typescript
+const updatePostSchema = z.object({
+  id: z.number(),
+  title: z.string().min(1).max(200).optional(),
+  content: z.string().max(50000).optional(),
+  published: z.boolean().optional(),
+});
+
+export const updatePost = createServerFn({ method: "POST" })
+  .inputValidator((d: unknown) => updatePostSchema.parse(d))
+  .handler(async ({ data }) => {
+    const { id, ...updates } = data;
+    const setValues: Record<string, unknown> = { updatedAt: new Date() };
+    if (updates.title !== undefined) setValues.title = updates.title;
+    if (updates.content !== undefined) setValues.content = updates.content;
+    if (updates.published !== undefined) setValues.published = updates.published;
+
+    const [updated] = await db().update(posts).set(setValues).where(eq(posts.id, id)).returning();
+    if (!updated) throw new Error("Post not found");
+    return updated;
+  });
+```
+
+### POST — Delete
+
+```typescript
+export const deletePost = createServerFn({ method: "POST" })
+  .inputValidator((d: unknown) => z.object({ id: z.number() }).parse(d))
+  .handler(async ({ data }) => {
+    const [deleted] = await db().delete(posts).where(eq(posts.id, data.id)).returning({ id: posts.id });
+    if (!deleted) throw new Error("Post not found");
+    return { success: true };
+  });
+```
+
+### Auth-Protected Server Functions
+
+When `authentication` skill is set up, check session:
+
+```typescript
+import { useAppSession } from "@/lib/session";
+
+export const createPost = createServerFn({ method: "POST" })
+  .inputValidator((d: unknown) => createPostSchema.parse(d))
+  .handler(async ({ data }) => {
+    const session = await useAppSession();
+    if (!session.data.userId) {
+      return { error: "Not authenticated" };
+    }
+
+    const [post] = await db()
+      .insert(posts)
+      .values({ title: data.title, content: data.content, authorId: session.data.userId })
+      .returning();
+    return post;
+  });
+```
+
+For GET functions in loaders, return empty instead of throwing:
+```typescript
+export const getMyPosts = createServerFn({ method: "GET" }).handler(async () => {
+  const session = await useAppSession();
+  if (!session.data.userId) return [];
+  return db().select().from(posts).where(eq(posts.authorId, session.data.userId)).orderBy(desc(posts.createdAt));
+});
+```
+
+### Pagination
+
+```typescript
+import { sql } from "drizzle-orm";
+
+const listSchema = z.object({
+  page: z.number().int().min(1).default(1),
+  limit: z.number().int().min(1).max(100).default(20),
+});
+
+export const listPosts = createServerFn({ method: "GET" })
+  .inputValidator((d: unknown) => listSchema.parse(d))
+  .handler(async ({ data }) => {
+    const offset = (data.page - 1) * data.limit;
+    const [rows, countResult] = await Promise.all([
+      db().select().from(posts).orderBy(desc(posts.createdAt)).limit(data.limit).offset(offset),
+      db().select({ count: sql<number>`count(*)::int` }).from(posts),
+    ]);
+    return {
+      items: rows,
+      total: countResult[0].count,
+      page: data.page,
+      totalPages: Math.ceil(countResult[0].count / data.limit),
+    };
+  });
+```
+
+### Search / Filter
+
+```typescript
+import { ilike, and } from "drizzle-orm";
+
+export const searchPosts = createServerFn({ method: "GET" })
+  .inputValidator((d: unknown) => z.object({ query: z.string().default("") }).parse(d))
+  .handler(async ({ data }) => {
+    const conditions = [];
+    if (data.query) conditions.push(ilike(posts.title, `%${data.query}%`));
+    return db()
+      .select().from(posts)
+      .where(conditions.length > 0 ? and(...conditions) : undefined)
+      .orderBy(desc(posts.createdAt))
+      .limit(50);
+  });
+```
+
+### JOIN (Relations)
+
+```typescript
+export const getPostWithAuthor = createServerFn({ method: "GET" })
+  .inputValidator((id: number) => id)
+  .handler(async ({ data: id }) => {
+    const [result] = await db()
+      .select({
+        id: posts.id, title: posts.title, content: posts.content, createdAt: posts.createdAt,
+        author: { id: users.id, name: users.name, email: users.email },
+      })
+      .from(posts)
+      .innerJoin(users, eq(posts.authorId, users.id))
+      .where(eq(posts.id, id))
+      .limit(1);
+    if (!result) throw new Error("Post not found");
+    return result;
+  });
+```
+
+## Workflow
+
+When the user asks to create backend logic for an entity:
+
+1. **Understand the entity** — fields, access rules, operations needed
+2. **Check existing setup:**
+   ```
+   read_file("src/lib/db.ts")       # DB client exists?
+   read_file("src/lib/schema.ts")   # Existing tables?
+   ls("src/server")                 # Existing server functions?
+   ```
+3. **Create/migrate table** — `database-management` tools
+4. **Install deps if needed** — `@neondatabase/serverless drizzle-orm zod`
+5. **Add schema definition** — edit `src/lib/schema.ts`
+6. **Create server functions** — `src/server/{entity}.ts`
+7. **Create route files** — loaders + components using the server functions
+8. **Run build to catch import errors:**
+   ```
+   npm run build
+   ```
+   Fix any errors before continuing. Build errors here almost always mean a dynamic import or a server-only import leaking into client code.
+9. **Show preview**
+
+## Error Handling
+
+### In server functions — return errors for expected cases, throw for unexpected:
+
+```typescript
+export const createPost = createServerFn({ method: "POST" })
+  .inputValidator((d: unknown) => createPostSchema.parse(d))
+  .handler(async ({ data }) => {
+    try {
+      const [post] = await db().insert(posts).values(data).returning();
+      return post;
+    } catch (err: any) {
+      // Handle unique constraint violations gracefully
+      if (err.message?.includes("unique constraint")) {
+        return { error: "A post with this title already exists" };
+      }
+      throw err; // Re-throw unexpected errors
+    }
+  });
+```
+
+### In components — check for error in result:
+
+```typescript
+const result = await create({ data: formValues });
+if (result && "error" in result) {
+  setError(result.error);
+  return;
+}
+// Success — navigate or update UI
+```
+
+### Zod validation errors — catch in form handler:
+
+```typescript
+try {
+  await create({ data: formValues });
+} catch (err) {
+  if (err instanceof z.ZodError) {
+    setError(err.errors.map(e => e.message).join(", "));
+  } else {
+    setError(err instanceof Error ? err.message : "Something went wrong");
+  }
+}
+```
+
+## Drizzle Quick Reference
+
+### SQL-to-Drizzle Type Mapping
+
+| SQL Type | Drizzle | Notes |
+|----------|---------|-------|
+| `SERIAL` | `serial("col")` | Auto-increment integer PK |
+| `TEXT` | `text("col")` | Unbounded string |
+| `VARCHAR(N)` | `varchar("col", { length: N })` | Bounded string |
+| `INTEGER` | `integer("col")` | 32-bit integer |
+| `BOOLEAN` | `boolean("col")` | true/false |
+| `TIMESTAMPTZ` | `timestamp("col", { withTimezone: true })` | Always use `withTimezone: true` |
+| `JSONB` | `jsonb("col")` | JSON column |
+| `TEXT[]` | `text("col").array()` | Array column |
+| `REAL` | `real("col")` | Floating point |
+
+### Query Operations
+
+```typescript
+import { eq, ne, gt, gte, lt, lte, and, or, ilike, desc, asc, sql } from "drizzle-orm";
+
+// Select
+await db().select().from(posts);
+await db().select().from(posts).where(eq(posts.id, 1));
+await db().select({ id: posts.id, title: posts.title }).from(posts);
+
+// Insert
+const [post] = await db().insert(posts).values({ title: "Hi", authorId: 1 }).returning();
+
+// Batch insert
+await db().insert(posts).values([{ title: "A", authorId: 1 }, { title: "B", authorId: 1 }]).returning();
+
+// Upsert (create or update)
+await db().insert(posts).values({ id: 1, title: "Updated" })
+  .onConflictDoUpdate({ target: posts.id, set: { title: "Updated", updatedAt: new Date() } })
+  .returning();
+
+// Update
+const [updated] = await db().update(posts).set({ title: "New" }).where(eq(posts.id, 1)).returning();
+
+// Delete
+const [deleted] = await db().delete(posts).where(eq(posts.id, 1)).returning({ id: posts.id });
+
+// Join
+await db().select().from(posts).innerJoin(users, eq(posts.authorId, users.id));
+
+// Count
+await db().select({ count: sql<number>`count(*)::int` }).from(posts);
+```
+
+## Zod Quick Reference
+
+```typescript
+z.string().min(1).max(200)              // required bounded string
+z.string().email()                      // email validation
+z.string().url()                        // URL validation
+z.string().uuid()                       // UUID validation
+z.string().regex(/^[a-z]+$/)            // regex pattern
+z.number().int().min(1)                 // positive integer
+z.boolean().default(false)              // boolean with default
+z.string().optional()                   // optional
+z.enum(["draft", "published"])          // enum
+z.array(z.string())                     // array
+z.object({ key: z.string() })          // nested object
+z.union([z.string(), z.number()])       // union type
+z.string().transform(s => s.trim())     // transform value
+```
+
+**Always use `.inputValidator((d: unknown) => schema.parse(d))`** for proper type inference + runtime validation.
+
+## Important Notes
+
+- **Server functions run on the server only.** Database imports and `process.env` are safe inside `.handler()`.
+- **Validators run on both client and server.** Keep them pure — no DB calls, no `process.env`.
+- **GET** functions are for loaders. **POST** functions are for mutations via `useServerFn()`.
+- **Do NOT create Express-style API routes.** `createServerFn` replaces the need for a separate API server.
+- **Do NOT use `fetch("/api/...")`** patterns. Call server functions directly.
+- **NEVER use `await import()` to load server functions** — always static imports at file top. Dynamic imports break TanStack Start's build-time bundle analysis and cause hard-to-debug build failures.
+- **Schema in code must match the database.** After adding to `src/lib/schema.ts`, create the table via migration tools.
+- **Run `npm run build` after writing first server function + route.** Catches import errors early before you write more code on top of a broken foundation.
+- Use existing template UI components (Button, Input, Label, Card, etc.) for forms and data display. Add more via `npx shadcn@latest add <component>` — see `web-application-creation` skill for the full list.