opencastle 0.33.9 → 0.34.0

package/src/orchestrator/plugins/convex/references/auth-workos.md

@@ -0,0 +1,114 @@
+# WorkOS AuthKit
+
+Official docs:
+
+- https://docs.convex.dev/auth/authkit/
+- https://docs.convex.dev/auth/authkit/add-to-app
+- https://docs.convex.dev/auth/authkit/auto-provision
+
+Use this when the app already uses WorkOS or the user wants AuthKit specifically.
+
+## Workflow
+
+1. Confirm the user wants WorkOS AuthKit
+2. Determine whether they want:
+   - a Convex-managed WorkOS team
+   - an existing WorkOS team
+3. Ask whether the user wants local-only setup or production-ready setup now
+4. Read the official Convex and WorkOS AuthKit guide
+5. Create or update `convex.json` for the app's framework and real local port
+6. Follow the correct branch of the setup flow based on that choice
+7. Configure the required WorkOS environment variables
+8. Configure `convex/auth.config.ts` for WorkOS-issued JWTs
+9. Wire the client provider and callback flow
+10. Verify authenticated requests reach Convex
+11. If the user wants production-ready setup, make sure the production WorkOS configuration is covered too
+12. Only add `storeUser` or a `users` table if the app needs first-class user rows inside Convex
+
+## What To Do
+
+- Read the official Convex and WorkOS AuthKit guide before writing setup code
+- Determine whether the user wants a Convex-managed WorkOS team or an existing WorkOS team
+- Treat `convex.json` as a first-class part of the AuthKit setup, not an optional extra
+- Follow the current setup flow from the docs instead of relying on older examples
+
+## Key Setup Areas
+
+- package installation for the app's framework
+- `convex.json` with the `authKit` section for dev, and preview or prod if needed
+- environment variables such as `WORKOS_CLIENT_ID`, `WORKOS_API_KEY`, and redirect configuration
+- `convex/auth.config.ts` wiring for WorkOS-issued JWTs
+- client provider setup and token flow into Convex
+- login callback and redirect configuration
+
+## Files and Env Vars To Expect
+
+- `convex.json`
+- `convex/auth.config.ts`
+- frontend auth provider wiring
+- callback or redirect route setup where the framework requires it
+- WorkOS environment variables commonly include:
+  - `WORKOS_CLIENT_ID`
+  - `WORKOS_API_KEY`
+  - `WORKOS_COOKIE_PASSWORD`
+  - `VITE_WORKOS_CLIENT_ID`
+  - `VITE_WORKOS_REDIRECT_URI`
+  - `NEXT_PUBLIC_WORKOS_REDIRECT_URI`
+
+For a managed WorkOS team, `convex dev` can provision the AuthKit environment and write local env vars such as `VITE_WORKOS_CLIENT_ID` and `VITE_WORKOS_REDIRECT_URI` into `.env.local` for Vite apps.
+
+## Concrete Steps
+
+1. Choose Convex-managed or existing WorkOS team
+2. Create or update `convex.json` with the `authKit` section for the framework in use
+3. Make sure the dev `redirectUris`, `appHomepageUrl`, `corsOrigins`, and local redirect env vars match the app's actual local port
+4. For a managed WorkOS team, run `npx convex dev` and follow the interactive onboarding flow
+5. For an existing WorkOS team, get `WORKOS_CLIENT_ID` and `WORKOS_API_KEY` from the WorkOS dashboard and set them with `npx convex env set`
+6. Create or update `convex/auth.config.ts` for WorkOS JWT validation
+7. Run the normal Convex dev or deploy flow so backend config is synced
+8. Wire the WorkOS client provider in the app
+9. Configure callback and redirect handling
+10. Verify the user can sign in and return to the app
+11. Verify Convex sees the authenticated user after login
+12. If the user wants production-ready setup, configure the production client ID, API key, redirect URI, and deployment settings too
+
+## Gotchas
+
+- The docs split setup between Convex-managed and existing WorkOS teams, so ask which path the user wants if it is not obvious
+- Keep dev and prod WorkOS configuration separate where the docs call for different client IDs or API keys
+- Only add `storeUser` or a `users` table if the app needs first-class user rows inside Convex
+- Do not mix dev and prod WorkOS credentials or redirect URIs
+- If the repo already contains WorkOS setup, preserve the current tenant model unless the user wants to change it
+- For managed WorkOS setup, `convex dev` is interactive the first time. In non-interactive terminals, stop and ask the user to complete the onboarding prompts.
+- `convex.json` is not optional for the managed AuthKit flow. It drives redirect URI, homepage URL, CORS configuration, and local env var generation.
+- If the frontend starts on a different port than the one in `convex.json`, the hosted WorkOS sign-in flow will point to the wrong callback URL. Update `convex.json`, update the local redirect env var, and run `npx convex dev` again.
+- Vite can fall off `5173` if other apps are already running. Do not assume the default port still matches the generated AuthKit config.
+- A successful WorkOS sign-in should redirect back to the local callback route and then reach a Convex-authenticated state. Do not stop at "the hosted WorkOS page loaded."
+
+## Production
+
+- Ask whether the user wants dev-only setup or production-ready setup
+- If the answer is production-ready, make sure the production WorkOS client ID, API key, redirect URI, and Convex deployment config are all covered
+- Verify the production redirect and callback settings before calling the task complete
+- Do not silently write a notes file into the repo by default. If the user wants rollout or handoff docs, create one explicitly.
+
+## Validation
+
+- Verify the user can complete the login flow and return to the app
+- Verify the callback URL matches the real frontend port in local dev
+- Verify Convex receives authenticated requests after login
+- Verify `convex.json` matches the framework and chosen WorkOS setup path
+- Verify `convex/auth.config.ts` matches the chosen WorkOS setup path
+- Verify environment variables differ correctly between local and production where needed
+- If production-ready setup was requested, verify the production WorkOS configuration is also covered
+
+## Checklist
+
+- [ ] Confirm the user wants WorkOS AuthKit
+- [ ] Ask whether the user wants local-only setup or production-ready setup
+- [ ] Choose Convex-managed or existing WorkOS team
+- [ ] Create or update `convex.json`
+- [ ] Configure WorkOS environment variables
+- [ ] Configure `convex/auth.config.ts`
+- [ ] Verify authenticated requests reach Convex after login
+- [ ] If requested, configure the production deployment too

package/src/orchestrator/plugins/convex/references/components-advanced.md

@@ -0,0 +1,134 @@
+# Advanced Component Patterns
+
+Additional patterns for Convex components that go beyond the basics covered in the main skill file.
+
+## Function Handles for callbacks
+
+When the app needs to pass a callback function to the component, use function handles. This is common for components that run app-defined logic on a schedule or in a workflow.
+
+```ts
+// App side: create a handle and pass it to the component
+import { createFunctionHandle } from "convex/server";
+
+export const startJob = mutation({
+  handler: async (ctx) => {
+    const handle = await createFunctionHandle(internal.myModule.processItem);
+    await ctx.runMutation(components.workpool.enqueue, {
+      callback: handle,
+    });
+  },
+});
+```
+
+```ts
+// Component side: accept and invoke the handle
+import { v } from "convex/values";
+import type { FunctionHandle } from "convex/server";
+import { mutation } from "./_generated/server.js";
+
+export const enqueue = mutation({
+  args: { callback: v.string() },
+  handler: async (ctx, args) => {
+    const handle = args.callback as FunctionHandle<"mutation">;
+    await ctx.scheduler.runAfter(0, handle, {});
+  },
+});
+```
+
+## Deriving validators from schema
+
+Instead of manually repeating field types in return validators, extend the schema validator:
+
+```ts
+import { v } from "convex/values";
+import schema from "./schema.js";
+
+const notificationDoc = schema.tables.notifications.validator.extend({
+  _id: v.id("notifications"),
+  _creationTime: v.number(),
+});
+
+export const getLatest = query({
+  args: {},
+  returns: v.nullable(notificationDoc),
+  handler: async (ctx) => {
+    return await ctx.db.query("notifications").order("desc").first();
+  },
+});
+```
+
+## Static configuration with a globals table
+
+A common pattern for component configuration is a single-document "globals" table:
+
+```ts
+// schema.ts
+export default defineSchema({
+  globals: defineTable({
+    maxRetries: v.number(),
+    webhookUrl: v.optional(v.string()),
+  }),
+  // ... other tables
+});
+```
+
+```ts
+// lib.ts
+export const configure = mutation({
+  args: { maxRetries: v.number(), webhookUrl: v.optional(v.string()) },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db.query("globals").first();
+    if (existing) {
+      await ctx.db.patch(existing._id, args);
+    } else {
+      await ctx.db.insert("globals", args);
+    }
+    return null;
+  },
+});
+```
+
+## Class-based client wrappers
+
+For components with many functions or configuration options, a class-based client provides a cleaner API. This pattern is common in published components.
+
+```ts
+// src/client/index.ts
+import type { GenericMutationCtx, GenericDataModel } from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+
+type MutationCtx = Pick<GenericMutationCtx<GenericDataModel>, "runMutation">;
+
+export class Notifications {
+  constructor(
+    private component: ComponentApi,
+    private options?: { defaultChannel?: string },
+  ) {}
+
+  async send(ctx: MutationCtx, args: { userId: string; message: string }) {
+    return await ctx.runMutation(this.component.lib.send, {
+      ...args,
+      channel: this.options?.defaultChannel ?? "default",
+    });
+  }
+}
+```
+
+```ts
+// App usage
+import { Notifications } from "@convex-dev/notifications";
+import { components } from "./_generated/api";
+
+const notifications = new Notifications(components.notifications, {
+  defaultChannel: "alerts",
+});
+
+export const send = mutation({
+  args: { message: v.string() },
+  handler: async (ctx, args) => {
+    const userId = await getAuthUserId(ctx);
+    await notifications.send(ctx, { userId, message: args.message });
+  },
+});
+```

package/src/orchestrator/plugins/convex/references/components.md

@@ -0,0 +1,171 @@
+# Convex Component Creation
+
+Create reusable Convex components with clear boundaries and a small app-facing API.
+
+## Core Concepts
+
+Components are isolated units of backend logic with their own tables and functions. They must be justified — prefer normal app code if the feature doesn't need isolated tables or reusable persistent state.
+
+**Golden Rule — Top-Down Execution:** Data and context always flow from app to component, never from component to app. The component cannot access `ctx.auth`, cannot read `process.env`, and cannot call app functions.
+
+## Architecture Choice
+
+| Goal | Shape | Reference |
+|------|-------|-----------|
+| Component for this app only | Local | Default |
+| Publish or share across apps | Packaged | `references/components-advanced.md` |
+| Not sure | Default to local | — |
+
+Default: put under `convex/components/<componentName>/`
+
+## Component Skeleton
+
+```ts
+// convex/components/notifications/convex.config.ts
+import { defineComponent } from "convex/server";
+export default defineComponent("notifications");
+```
+
+```ts
+// convex/components/notifications/schema.ts
+export default defineSchema({
+  notifications: defineTable({
+    userId: v.string(),
+    message: v.string(),
+    read: v.boolean(),
+  }).index("by_user", ["userId"]),
+});
+```
+
+```ts
+// convex/components/notifications/lib.ts
+import { mutation, query } from "./_generated/server.js";
+
+export const send = mutation({
+  args: { userId: v.string(), message: v.string() },
+  returns: v.id("notifications"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("notifications", {
+      userId: args.userId,
+      message: args.message,
+      read: false,
+    });
+  },
+});
+```
+
+```ts
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import notifications from "./components/notifications/convex.config.js";
+
+const app = defineApp();
+app.use(notifications);
+export default app;
+```
+
+```ts
+// convex/notifications.ts — app-side wrapper
+export const sendNotification = mutation({
+  args: { message: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const userId = await getAuthUserId(ctx);
+    if (!userId) throw new Error("Not authenticated");
+    await ctx.runMutation(components.notifications.lib.send, {
+      userId,
+      message: args.message,
+    });
+    return null;
+  },
+});
+```
+
+Note: a function in `convex/components/notifications/lib.ts` is called as `components.notifications.lib.send`.
+
+## Critical Rules
+
+- **Auth stays in the app** — `ctx.auth` is not available inside components. Resolve auth in the app and pass the userId.
+- **Env access stays in the app** — component functions cannot read `process.env`.
+- **Parent IDs cross the boundary as strings** — use `v.string()`, not `v.id("parentTable")` for app-owned tables inside component args.
+- **Import from component's own generated files** — use `./_generated/server` not the app's generated files.
+- **Never expose component functions directly to clients** — create app wrappers when client access is needed.
+- **HTTP routes stay in the app** — if the component defines HTTP handlers, mount them in `convex/http.ts`.
+- **Use `paginator` from `convex-helpers`** for pagination across component boundaries — built-in `.paginate()` doesn't work across the boundary.
+- **Add `args` and `returns` validators to all public component functions** — the boundary requires explicit type contracts.
+
+## Key Patterns
+
+### Auth and Env Access
+
+```ts
+// Good: app resolves auth and env, passes explicit values
+const userId = await getAuthUserId(ctx);
+if (!userId) throw new Error("Not authenticated");
+
+await ctx.runAction(components.translator.translate, {
+  userId,
+  apiKey: process.env.OPENAI_API_KEY,
+  text: args.text,
+});
+```
+
+### IDs Across the Boundary
+
+```ts
+// Bad: parent app table IDs are not valid component validators
+args: { userId: v.id("users") }
+
+// Good: treat parent-owned IDs as strings at the boundary
+args: { userId: v.string() }
+```
+
+### Client-Facing API
+
+```ts
+// Bad: component function directly callable by clients
+export const send = components.notifications.send;
+
+// Good: re-export through an app mutation
+export const sendNotification = mutation({
+  args: { message: v.string() },
+  handler: async (ctx, args) => {
+    const userId = await getAuthUserId(ctx);
+    if (!userId) throw new Error("Not authenticated");
+    await ctx.runMutation(components.notifications.lib.send, { userId, message: args.message });
+    return null;
+  },
+});
+```
+
+## Step-by-Step Workflow
+
+1. Plan what tables the component owns, what public functions it exposes, what data must be passed from the app, and what stays in the app as wrappers
+2. Create `convex.config.ts`, `schema.ts`, and function files under `convex/components/<name>/`
+3. Import `query`, `mutation`, `action` from the component's own `./_generated/server`
+4. Wire into the app with `app.use(...)` in `convex/convex.config.ts`
+5. Call the component from the app through `components.<name>` using `ctx.runQuery`/`ctx.runMutation`/`ctx.runAction`
+6. Create app wrapper functions for any client access needed
+7. Run `npx convex dev` and fix codegen/type issues
+
+## Validation
+
+Try validation in this order:
+1. `npx convex codegen --component-dir convex/components/<name>`
+2. `npx convex codegen`
+3. `npx convex dev`
+
+## Advanced Patterns
+
+For function handles (callbacks), deriving validators from schema, globals tables, and class-based client wrappers, see `references/components-advanced.md`.
+
+## Checklist
+
+- [ ] Confirmed a component is the right abstraction
+- [ ] Planned tables, public API, boundaries, and app wrappers
+- [ ] Component lives under `convex/components/<name>/`
+- [ ] Component imports from its own `./_generated/server`
+- [ ] Auth, env access, and HTTP routes stay in the app
+- [ ] Parent app IDs cross the boundary as `v.string()`
+- [ ] Public functions have `args` and `returns` validators
+- [ ] Ran `npx convex dev` and fixed codegen or type issues

package/src/orchestrator/plugins/convex/references/function-budget.md

@@ -0,0 +1,232 @@
+# Function Budget
+
+Use these rules when functions are hitting execution limits, transaction size errors, or returning excessively large payloads to the client.
+
+## Core Principle
+
+Convex functions run inside transactions with budgets for time, reads, and writes. Staying well within these limits is not just about avoiding errors, it reduces latency and contention.
+
+## Limits to Know
+
+These are the current values from the [Convex limits docs](https://docs.convex.dev/production/state/limits). Check that page for the latest numbers.
+
+| Resource | Limit |
+|---|---|
+| Query/mutation execution time | 1 second (user code only, excludes DB operations) |
+| Action execution time | 10 minutes |
+| Data read per transaction | 16 MiB |
+| Data written per transaction | 16 MiB |
+| Documents scanned per transaction | 32,000 (includes documents filtered out by `.filter`) |
+| Index ranges read per transaction | 4,096 (each `db.get` and `db.query` call) |
+| Documents written per transaction | 16,000 |
+| Individual document size | 1 MiB |
+| Function return value size | 16 MiB |
+
+## Symptoms
+
+- "Function execution took too long" errors
+- "Transaction too large" or read/write set size errors
+- Slow queries that read many documents
+- Client receiving large payloads that slow down page load
+- `npx convex insights --details` showing high bytes read
+
+## Common Causes
+
+### Unbounded collection
+
+A query that calls `.collect()` on a table without a reasonable limit. As the table grows, the query reads more and more documents.
+
+### Large document reads on hot paths
+
+Reading documents with large fields (rich text, embedded media references, long arrays) when only a small subset of the data is needed for the current view.
+
+### Mutation doing too much work
+
+A single mutation that updates hundreds of documents, backfills data, or rebuilds derived state in one transaction.
+
+### Returning too much data to the client
+
+A query returning full documents when the client only needs a few fields.
+
+## Fix Order
+
+### 1. Bound your reads
+
+Never `.collect()` without a limit on a table that can grow unbounded.
+
+```ts
+// Bad: unbounded read, breaks as the table grows
+const messages = await ctx.db.query("messages").collect();
+```
+
+```ts
+// Good: paginate or limit
+const messages = await ctx.db
+  .query("messages")
+  .withIndex("by_channel", (q) => q.eq("channelId", channelId))
+  .order("desc")
+  .take(50);
+```
+
+### 2. Read smaller shapes
+
+If the list page only needs title, author, and date, do not read full documents with rich content fields.
+
+Use digest or summary tables for hot list pages. See `hot-path-rules.md` for the digest table pattern.
+
+### 3. Break large mutations into batches
+
+If a mutation needs to update hundreds of documents, split it into a self-scheduling chain.
+
+```ts
+// Bad: one mutation updating every row
+export const backfillAll = internalMutation({
+  handler: async (ctx) => {
+    const docs = await ctx.db.query("items").collect();
+    for (const doc of docs) {
+      await ctx.db.patch(doc._id, { newField: computeValue(doc) });
+    }
+  },
+});
+```
+
+```ts
+// Good: cursor-based batch processing
+export const backfillBatch = internalMutation({
+  args: { cursor: v.optional(v.string()), batchSize: v.optional(v.number()) },
+  handler: async (ctx, args) => {
+    const batchSize = args.batchSize ?? 100;
+    const result = await ctx.db
+      .query("items")
+      .paginate({ cursor: args.cursor ?? null, numItems: batchSize });
+
+    for (const doc of result.page) {
+      if (doc.newField === undefined) {
+        await ctx.db.patch(doc._id, { newField: computeValue(doc) });
+      }
+    }
+
+    if (!result.isDone) {
+      await ctx.scheduler.runAfter(0, internal.items.backfillBatch, {
+        cursor: result.continueCursor,
+        batchSize,
+      });
+    }
+  },
+});
+```
+
+### 4. Move heavy work to actions
+
+Queries and mutations run inside Convex's transactional runtime with strict budgets. If you need to do CPU-intensive computation, call external APIs, or process large files, use an action instead.
+
+Actions run outside the transaction and can call mutations to write results back.
+
+```ts
+// Bad: heavy computation inside a mutation
+export const processUpload = mutation({
+  handler: async (ctx, args) => {
+    const result = expensiveComputation(args.data);
+    await ctx.db.insert("results", result);
+  },
+});
+```
+
+```ts
+// Good: action for heavy work, mutation for the write
+export const processUpload = action({
+  handler: async (ctx, args) => {
+    const result = expensiveComputation(args.data);
+    await ctx.runMutation(internal.results.store, { result });
+  },
+});
+```
+
+### 5. Trim return values
+
+Only return what the client needs. If a query fetches full documents but the component only renders a few fields, map the results before returning.
+
+```ts
+// Bad: returns full documents including large content fields
+export const list = query({
+  handler: async (ctx) => {
+    return await ctx.db.query("articles").take(20);
+  },
+});
+```
+
+```ts
+// Good: project to only the fields the client needs
+export const list = query({
+  handler: async (ctx) => {
+    const articles = await ctx.db.query("articles").take(20);
+    return articles.map((a) => ({
+      _id: a._id,
+      title: a.title,
+      author: a.author,
+      createdAt: a._creationTime,
+    }));
+  },
+});
+```
+
+### 6. Replace `ctx.runQuery` and `ctx.runMutation` with helper functions
+
+Inside queries and mutations, `ctx.runQuery` and `ctx.runMutation` have overhead compared to calling a plain TypeScript helper function. They run in the same transaction but pay extra per-call cost.
+
+```ts
+// Bad: unnecessary overhead from ctx.runQuery inside a mutation
+export const createProject = mutation({
+  handler: async (ctx, args) => {
+    const user = await ctx.runQuery(api.users.getCurrentUser);
+    await ctx.db.insert("projects", { ...args, ownerId: user._id });
+  },
+});
+```
+
+```ts
+// Good: plain helper function, no extra overhead
+export const createProject = mutation({
+  handler: async (ctx, args) => {
+    const user = await getCurrentUser(ctx);
+    await ctx.db.insert("projects", { ...args, ownerId: user._id });
+  },
+});
+```
+
+Exception: components require `ctx.runQuery`/`ctx.runMutation`. Use them there, but prefer helpers everywhere else.
+
+### 7. Avoid unnecessary `runAction` calls
+
+`runAction` from within an action creates a separate function invocation with its own memory and CPU budget. The parent action just sits idle waiting. Replace with a plain TypeScript function call unless you need a different runtime (e.g. calling Node.js code from the Convex runtime).
+
+```ts
+// Bad: runAction overhead for no reason
+export const processItems = action({
+  handler: async (ctx, args) => {
+    for (const item of args.items) {
+      await ctx.runAction(internal.items.processOne, { item });
+    }
+  },
+});
+```
+
+```ts
+// Good: plain function call
+export const processItems = action({
+  handler: async (ctx, args) => {
+    for (const item of args.items) {
+      await processOneItem(ctx, { item });
+    }
+  },
+});
+```
+
+## Verification
+
+1. No function execution or transaction size errors
+2. `npx convex insights --details` shows reduced bytes read
+3. Large mutations are batched and self-scheduling
+4. Client payloads are reasonably sized for the UI they serve
+5. `ctx.runQuery`/`ctx.runMutation` in queries and mutations replaced with helpers where possible
+6. Sibling functions with similar patterns were checked