takomi 2.0.4

package/assets/.agent/skills/convex-component-authoring/SKILL.md

@@ -0,0 +1,457 @@
+---
+name: convex-component-authoring
+displayName: Convex Component Authoring
+description: How to create, structure, and publish self-contained Convex components with proper isolation, exports, and dependency management
+version: 1.0.0
+author: Convex
+tags: [convex, components, reusable, packages, npm]
+---
+
+# Convex Component Authoring
+
+Create self-contained, reusable Convex components with proper isolation, exports, and dependency management for sharing across projects.
+
+## Documentation Sources
+
+Before implementing, do not assume; fetch the latest documentation:
+
+- Primary: https://docs.convex.dev/components
+- Component Authoring: https://docs.convex.dev/components/authoring
+- For broader context: https://docs.convex.dev/llms.txt
+
+## Instructions
+
+### What Are Convex Components?
+
+Convex components are self-contained packages that include:
+- Database tables (isolated from the main app)
+- Functions (queries, mutations, actions)
+- TypeScript types and validators
+- Optional frontend hooks
+
+### Component Structure
+
+```
+my-convex-component/
+├── package.json
+├── tsconfig.json
+├── README.md
+├── src/
+│   ├── index.ts           # Main exports
+│   ├── component.ts       # Component definition
+│   ├── schema.ts          # Component schema
+│   └── functions/
+│       ├── queries.ts
+│       ├── mutations.ts
+│       └── actions.ts
+└── convex.config.ts       # Component configuration
+```
+
+### Creating a Component
+
+#### 1. Component Configuration
+
+```typescript
+// convex.config.ts
+import { defineComponent } from "convex/server";
+
+export default defineComponent("myComponent");
+```
+
+#### 2. Component Schema
+
+```typescript
+// src/schema.ts
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  // Tables are isolated to this component
+  items: defineTable({
+    name: v.string(),
+    data: v.any(),
+    createdAt: v.number(),
+  }).index("by_name", ["name"]),
+  
+  config: defineTable({
+    key: v.string(),
+    value: v.any(),
+  }).index("by_key", ["key"]),
+});
+```
+
+#### 3. Component Definition
+
+```typescript
+// src/component.ts
+import { defineComponent, ComponentDefinition } from "convex/server";
+import schema from "./schema";
+import * as queries from "./functions/queries";
+import * as mutations from "./functions/mutations";
+
+const component = defineComponent("myComponent", {
+  schema,
+  functions: {
+    ...queries,
+    ...mutations,
+  },
+});
+
+export default component;
+```
+
+#### 4. Component Functions
+
+```typescript
+// src/functions/queries.ts
+import { query } from "../_generated/server";
+import { v } from "convex/values";
+
+export const list = query({
+  args: {
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(v.object({
+    _id: v.id("items"),
+    name: v.string(),
+    data: v.any(),
+    createdAt: v.number(),
+  })),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("items")
+      .order("desc")
+      .take(args.limit ?? 10);
+  },
+});
+
+export const get = query({
+  args: { name: v.string() },
+  returns: v.union(v.object({
+    _id: v.id("items"),
+    name: v.string(),
+    data: v.any(),
+  }), v.null()),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("items")
+      .withIndex("by_name", (q) => q.eq("name", args.name))
+      .unique();
+  },
+});
+```
+
+```typescript
+// src/functions/mutations.ts
+import { mutation } from "../_generated/server";
+import { v } from "convex/values";
+
+export const create = mutation({
+  args: {
+    name: v.string(),
+    data: v.any(),
+  },
+  returns: v.id("items"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("items", {
+      name: args.name,
+      data: args.data,
+      createdAt: Date.now(),
+    });
+  },
+});
+
+export const update = mutation({
+  args: {
+    id: v.id("items"),
+    data: v.any(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.id, { data: args.data });
+    return null;
+  },
+});
+
+export const remove = mutation({
+  args: { id: v.id("items") },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.db.delete(args.id);
+    return null;
+  },
+});
+```
+
+#### 5. Main Exports
+
+```typescript
+// src/index.ts
+export { default as component } from "./component";
+export * from "./functions/queries";
+export * from "./functions/mutations";
+
+// Export types for consumers
+export type { Id } from "./_generated/dataModel";
+```
+
+### Using a Component
+
+```typescript
+// In the consuming app's convex/convex.config.ts
+import { defineApp } from "convex/server";
+import myComponent from "my-convex-component";
+
+const app = defineApp();
+
+app.use(myComponent, { name: "myComponent" });
+
+export default app;
+```
+
+```typescript
+// In the consuming app's code
+import { useQuery, useMutation } from "convex/react";
+import { api } from "../convex/_generated/api";
+
+function MyApp() {
+  // Access component functions through the app's API
+  const items = useQuery(api.myComponent.list, { limit: 10 });
+  const createItem = useMutation(api.myComponent.create);
+  
+  return (
+    <div>
+      {items?.map((item) => (
+        <div key={item._id}>{item.name}</div>
+      ))}
+      <button onClick={() => createItem({ name: "New", data: {} })}>
+        Add Item
+      </button>
+    </div>
+  );
+}
+```
+
+### Component Configuration Options
+
+```typescript
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import myComponent from "my-convex-component";
+
+const app = defineApp();
+
+// Basic usage
+app.use(myComponent);
+
+// With custom name
+app.use(myComponent, { name: "customName" });
+
+// Multiple instances
+app.use(myComponent, { name: "instance1" });
+app.use(myComponent, { name: "instance2" });
+
+export default app;
+```
+
+### Providing Component Hooks
+
+```typescript
+// src/hooks.ts
+import { useQuery, useMutation } from "convex/react";
+import { FunctionReference } from "convex/server";
+
+// Type-safe hooks for component consumers
+export function useMyComponent(api: {
+  list: FunctionReference<"query">;
+  create: FunctionReference<"mutation">;
+}) {
+  const items = useQuery(api.list, {});
+  const createItem = useMutation(api.create);
+  
+  return {
+    items,
+    createItem,
+    isLoading: items === undefined,
+  };
+}
+```
+
+### Publishing a Component
+
+#### package.json
+
+```json
+{
+  "name": "my-convex-component",
+  "version": "1.0.0",
+  "description": "A reusable Convex component",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "convex.config.ts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "convex": "^1.0.0"
+  },
+  "devDependencies": {
+    "convex": "^1.17.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "convex",
+    "component"
+  ]
+}
+```
+
+#### tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## Examples
+
+### Rate Limiter Component
+
+```typescript
+// rate-limiter/src/schema.ts
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  requests: defineTable({
+    key: v.string(),
+    timestamp: v.number(),
+  })
+    .index("by_key", ["key"])
+    .index("by_key_and_time", ["key", "timestamp"]),
+});
+```
+
+```typescript
+// rate-limiter/src/functions/mutations.ts
+import { mutation } from "../_generated/server";
+import { v } from "convex/values";
+
+export const checkLimit = mutation({
+  args: {
+    key: v.string(),
+    limit: v.number(),
+    windowMs: v.number(),
+  },
+  returns: v.object({
+    allowed: v.boolean(),
+    remaining: v.number(),
+    resetAt: v.number(),
+  }),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const windowStart = now - args.windowMs;
+    
+    // Clean old entries
+    const oldEntries = await ctx.db
+      .query("requests")
+      .withIndex("by_key_and_time", (q) => 
+        q.eq("key", args.key).lt("timestamp", windowStart)
+      )
+      .collect();
+    
+    for (const entry of oldEntries) {
+      await ctx.db.delete(entry._id);
+    }
+    
+    // Count current window
+    const currentRequests = await ctx.db
+      .query("requests")
+      .withIndex("by_key", (q) => q.eq("key", args.key))
+      .collect();
+    
+    const remaining = Math.max(0, args.limit - currentRequests.length);
+    const allowed = remaining > 0;
+    
+    if (allowed) {
+      await ctx.db.insert("requests", {
+        key: args.key,
+        timestamp: now,
+      });
+    }
+    
+    const oldestRequest = currentRequests[0];
+    const resetAt = oldestRequest 
+      ? oldestRequest.timestamp + args.windowMs 
+      : now + args.windowMs;
+    
+    return { allowed, remaining: remaining - (allowed ? 1 : 0), resetAt };
+  },
+});
+```
+
+```typescript
+// Usage in consuming app
+import { useMutation } from "convex/react";
+import { api } from "../convex/_generated/api";
+
+function useRateLimitedAction() {
+  const checkLimit = useMutation(api.rateLimiter.checkLimit);
+  
+  return async (action: () => Promise<void>) => {
+    const result = await checkLimit({
+      key: "user-action",
+      limit: 10,
+      windowMs: 60000,
+    });
+    
+    if (!result.allowed) {
+      throw new Error(`Rate limited. Try again at ${new Date(result.resetAt)}`);
+    }
+    
+    await action();
+  };
+}
+```
+
+## Best Practices
+
+- Never run `npx convex deploy` unless explicitly instructed
+- Never run any git commands unless explicitly instructed
+- Keep component tables isolated (don't reference main app tables)
+- Export clear TypeScript types for consumers
+- Document all public functions and their arguments
+- Use semantic versioning for component releases
+- Include comprehensive README with examples
+- Test components in isolation before publishing
+
+## Common Pitfalls
+
+1. **Cross-referencing tables** - Component tables should be self-contained
+2. **Missing type exports** - Export all necessary types
+3. **Hardcoded configuration** - Use component options for customization
+4. **No versioning** - Follow semantic versioning
+5. **Poor documentation** - Document all public APIs
+
+## References
+
+- Convex Documentation: https://docs.convex.dev/
+- Convex LLMs.txt: https://docs.convex.dev/llms.txt
+- Components: https://docs.convex.dev/components
+- Component Authoring: https://docs.convex.dev/components/authoring

package/assets/.agent/skills/convex-component-authoring/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  icon_small: "./assets/small-logo.svg"
+  icon_large: "./assets/large-logo.png"

package/assets/.agent/skills/convex-component-authoring/assets/small-logo.svg

@@ -0,0 +1,17 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_3_23)">
+<g clip-path="url(#clip1_3_23)">
+<path d="M10.0643 12.5735C12.3769 12.3166 14.5572 11.0843 15.7577 9.02756C15.1892 14.1148 9.62646 17.3302 5.08583 15.356C4.66743 15.1746 4.30728 14.8728 4.06013 14.4848C3.03973 12.8825 2.7043 10.8437 3.18626 8.99344C4.56327 11.37 7.3632 12.8267 10.0643 12.5735Z" fill="#F3B01C"/>
+<path d="M3.1018 7.50072C2.16436 9.66714 2.12376 12.2034 3.27303 14.2907C-0.771507 11.2479 -0.72737 4.7362 3.2236 1.72378C3.58904 1.44535 4.02333 1.2801 4.47881 1.25494C6.3519 1.15614 8.25501 1.88006 9.58963 3.22909C6.87799 3.25604 4.23695 4.99308 3.1018 7.50072Z" fill="#8D2676"/>
+<path d="M10.8974 3.89562C9.52924 1.98794 7.38779 0.68921 5.04156 0.649695C9.57686 -1.40888 15.1555 1.92867 15.7629 6.86314C15.8194 7.32119 15.7452 7.78824 15.5421 8.20138C14.6948 9.92223 13.1236 11.2569 11.2876 11.7508C12.6328 9.25579 12.4668 6.20748 10.8974 3.89562Z" fill="#EE342F"/>
+</g>
+</g>
+<defs>
+<clipPath id="clip0_3_23">
+<rect width="16" height="16" fill="white"/>
+</clipPath>
+<clipPath id="clip1_3_23">
+<rect width="16" height="16" fill="white"/>
+</clipPath>
+</defs>
+</svg>