vibesuite 1.3.2 → 2.0.1

package/assets/.agent/skills/convex-file-storage/SKILL.md

@@ -0,0 +1,467 @@
+---
+name: convex-file-storage
+displayName: Convex File Storage
+description: Complete file handling including upload flows, serving files via URL, storing generated files from actions, deletion, and accessing file metadata from system tables
+version: 1.0.0
+author: Convex
+tags: [convex, file-storage, uploads, images, files]
+---
+
+# Convex File Storage
+
+Handle file uploads, storage, serving, and management in Convex applications with proper patterns for images, documents, and generated files.
+
+## Documentation Sources
+
+Before implementing, do not assume; fetch the latest documentation:
+
+- Primary: https://docs.convex.dev/file-storage
+- Upload Files: https://docs.convex.dev/file-storage/upload-files
+- Serve Files: https://docs.convex.dev/file-storage/serve-files
+- For broader context: https://docs.convex.dev/llms.txt
+
+## Instructions
+
+### File Storage Overview
+
+Convex provides built-in file storage with:
+- Automatic URL generation for serving files
+- Support for any file type (images, PDFs, videos, etc.)
+- File metadata via the `_storage` system table
+- Integration with mutations and actions
+
+### Generating Upload URLs
+
+```typescript
+// convex/files.ts
+import { mutation } from "./_generated/server";
+import { v } from "convex/values";
+
+export const generateUploadUrl = mutation({
+  args: {},
+  returns: v.string(),
+  handler: async (ctx) => {
+    return await ctx.storage.generateUploadUrl();
+  },
+});
+```
+
+### Client-Side Upload
+
+```typescript
+// React component
+import { useMutation } from "convex/react";
+import { api } from "../convex/_generated/api";
+import { useState } from "react";
+
+function FileUploader() {
+  const generateUploadUrl = useMutation(api.files.generateUploadUrl);
+  const saveFile = useMutation(api.files.saveFile);
+  const [uploading, setUploading] = useState(false);
+
+  const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+
+    setUploading(true);
+    try {
+      // Step 1: Get upload URL
+      const uploadUrl = await generateUploadUrl();
+
+      // Step 2: Upload file to storage
+      const result = await fetch(uploadUrl, {
+        method: "POST",
+        headers: { "Content-Type": file.type },
+        body: file,
+      });
+
+      const { storageId } = await result.json();
+
+      // Step 3: Save file reference to database
+      await saveFile({
+        storageId,
+        fileName: file.name,
+        fileType: file.type,
+        fileSize: file.size,
+      });
+    } finally {
+      setUploading(false);
+    }
+  };
+
+  return (
+    <div>
+      <input
+        type="file"
+        onChange={handleUpload}
+        disabled={uploading}
+      />
+      {uploading && <p>Uploading...</p>}
+    </div>
+  );
+}
+```
+
+### Saving File References
+
+```typescript
+// convex/files.ts
+import { mutation, query } from "./_generated/server";
+import { v } from "convex/values";
+
+export const saveFile = mutation({
+  args: {
+    storageId: v.id("_storage"),
+    fileName: v.string(),
+    fileType: v.string(),
+    fileSize: v.number(),
+  },
+  returns: v.id("files"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("files", {
+      storageId: args.storageId,
+      fileName: args.fileName,
+      fileType: args.fileType,
+      fileSize: args.fileSize,
+      uploadedAt: Date.now(),
+    });
+  },
+});
+```
+
+### Serving Files via URL
+
+```typescript
+// convex/files.ts
+export const getFileUrl = query({
+  args: { storageId: v.id("_storage") },
+  returns: v.union(v.string(), v.null()),
+  handler: async (ctx, args) => {
+    return await ctx.storage.getUrl(args.storageId);
+  },
+});
+
+// Get file with URL
+export const getFile = query({
+  args: { fileId: v.id("files") },
+  returns: v.union(
+    v.object({
+      _id: v.id("files"),
+      fileName: v.string(),
+      fileType: v.string(),
+      fileSize: v.number(),
+      url: v.union(v.string(), v.null()),
+    }),
+    v.null()
+  ),
+  handler: async (ctx, args) => {
+    const file = await ctx.db.get(args.fileId);
+    if (!file) return null;
+
+    const url = await ctx.storage.getUrl(file.storageId);
+    
+    return {
+      _id: file._id,
+      fileName: file.fileName,
+      fileType: file.fileType,
+      fileSize: file.fileSize,
+      url,
+    };
+  },
+});
+```
+
+### Displaying Files in React
+
+```typescript
+import { useQuery } from "convex/react";
+import { api } from "../convex/_generated/api";
+
+function FileDisplay({ fileId }: { fileId: Id<"files"> }) {
+  const file = useQuery(api.files.getFile, { fileId });
+
+  if (!file) return <div>Loading...</div>;
+  if (!file.url) return <div>File not found</div>;
+
+  // Handle different file types
+  if (file.fileType.startsWith("image/")) {
+    return <img src={file.url} alt={file.fileName} />;
+  }
+
+  if (file.fileType === "application/pdf") {
+    return (
+      <iframe
+        src={file.url}
+        title={file.fileName}
+        width="100%"
+        height="600px"
+      />
+    );
+  }
+
+  return (
+    <a href={file.url} download={file.fileName}>
+      Download {file.fileName}
+    </a>
+  );
+}
+```
+
+### Storing Generated Files from Actions
+
+```typescript
+// convex/generate.ts
+"use node";
+
+import { action } from "./_generated/server";
+import { v } from "convex/values";
+import { api } from "./_generated/api";
+
+export const generatePDF = action({
+  args: { content: v.string() },
+  returns: v.id("_storage"),
+  handler: async (ctx, args) => {
+    // Generate PDF (example using a library)
+    const pdfBuffer = await generatePDFFromContent(args.content);
+
+    // Convert to Blob
+    const blob = new Blob([pdfBuffer], { type: "application/pdf" });
+
+    // Store in Convex
+    const storageId = await ctx.storage.store(blob);
+
+    return storageId;
+  },
+});
+
+// Generate and save image
+export const generateImage = action({
+  args: { prompt: v.string() },
+  returns: v.id("_storage"),
+  handler: async (ctx, args) => {
+    // Call external API to generate image
+    const response = await fetch("https://api.example.com/generate", {
+      method: "POST",
+      body: JSON.stringify({ prompt: args.prompt }),
+    });
+
+    const imageBuffer = await response.arrayBuffer();
+    const blob = new Blob([imageBuffer], { type: "image/png" });
+
+    return await ctx.storage.store(blob);
+  },
+});
+```
+
+### Accessing File Metadata
+
+```typescript
+// convex/files.ts
+import { query } from "./_generated/server";
+import { v } from "convex/values";
+import { Id } from "./_generated/dataModel";
+
+type FileMetadata = {
+  _id: Id<"_storage">;
+  _creationTime: number;
+  contentType?: string;
+  sha256: string;
+  size: number;
+};
+
+export const getFileMetadata = query({
+  args: { storageId: v.id("_storage") },
+  returns: v.union(
+    v.object({
+      _id: v.id("_storage"),
+      _creationTime: v.number(),
+      contentType: v.optional(v.string()),
+      sha256: v.string(),
+      size: v.number(),
+    }),
+    v.null()
+  ),
+  handler: async (ctx, args) => {
+    const metadata = await ctx.db.system.get(args.storageId);
+    return metadata as FileMetadata | null;
+  },
+});
+```
+
+### Deleting Files
+
+```typescript
+// convex/files.ts
+import { mutation } from "./_generated/server";
+import { v } from "convex/values";
+
+export const deleteFile = mutation({
+  args: { fileId: v.id("files") },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const file = await ctx.db.get(args.fileId);
+    if (!file) return null;
+
+    // Delete from storage
+    await ctx.storage.delete(file.storageId);
+
+    // Delete database record
+    await ctx.db.delete(args.fileId);
+
+    return null;
+  },
+});
+```
+
+### Image Upload with Preview
+
+```typescript
+import { useMutation } from "convex/react";
+import { api } from "../convex/_generated/api";
+import { useState, useRef } from "react";
+
+function ImageUploader({ onUpload }: { onUpload: (id: Id<"files">) => void }) {
+  const generateUploadUrl = useMutation(api.files.generateUploadUrl);
+  const saveFile = useMutation(api.files.saveFile);
+  const [preview, setPreview] = useState<string | null>(null);
+  const [uploading, setUploading] = useState(false);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const handleFileSelect = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+
+    // Validate file type
+    if (!file.type.startsWith("image/")) {
+      alert("Please select an image file");
+      return;
+    }
+
+    // Validate file size (max 10MB)
+    if (file.size > 10 * 1024 * 1024) {
+      alert("File size must be less than 10MB");
+      return;
+    }
+
+    // Show preview
+    const reader = new FileReader();
+    reader.onload = (e) => setPreview(e.target?.result as string);
+    reader.readAsDataURL(file);
+
+    // Upload
+    setUploading(true);
+    try {
+      const uploadUrl = await generateUploadUrl();
+      const result = await fetch(uploadUrl, {
+        method: "POST",
+        headers: { "Content-Type": file.type },
+        body: file,
+      });
+
+      const { storageId } = await result.json();
+      const fileId = await saveFile({
+        storageId,
+        fileName: file.name,
+        fileType: file.type,
+        fileSize: file.size,
+      });
+
+      onUpload(fileId);
+    } finally {
+      setUploading(false);
+    }
+  };
+
+  return (
+    <div>
+      <input
+        ref={inputRef}
+        type="file"
+        accept="image/*"
+        onChange={handleFileSelect}
+        style={{ display: "none" }}
+      />
+      
+      <button
+        onClick={() => inputRef.current?.click()}
+        disabled={uploading}
+      >
+        {uploading ? "Uploading..." : "Select Image"}
+      </button>
+
+      {preview && (
+        <img
+          src={preview}
+          alt="Preview"
+          style={{ maxWidth: 200, marginTop: 10 }}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+## Examples
+
+### Schema for File Storage
+
+```typescript
+// convex/schema.ts
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  files: defineTable({
+    storageId: v.id("_storage"),
+    fileName: v.string(),
+    fileType: v.string(),
+    fileSize: v.number(),
+    uploadedBy: v.id("users"),
+    uploadedAt: v.number(),
+  })
+    .index("by_user", ["uploadedBy"])
+    .index("by_type", ["fileType"]),
+
+  // User avatars
+  users: defineTable({
+    name: v.string(),
+    email: v.string(),
+    avatarStorageId: v.optional(v.id("_storage")),
+  }),
+
+  // Posts with images
+  posts: defineTable({
+    authorId: v.id("users"),
+    content: v.string(),
+    imageStorageIds: v.array(v.id("_storage")),
+    createdAt: v.number(),
+  }).index("by_author", ["authorId"]),
+});
+```
+
+## Best Practices
+
+- Never run `npx convex deploy` unless explicitly instructed
+- Never run any git commands unless explicitly instructed
+- Validate file types and sizes on the client before uploading
+- Store file metadata (name, type, size) in your own table
+- Use the `_storage` system table only for Convex metadata
+- Delete storage files when deleting database references
+- Use appropriate Content-Type headers when uploading
+- Consider image optimization for large images
+
+## Common Pitfalls
+
+1. **Not setting Content-Type header** - Files may not serve correctly
+2. **Forgetting to delete storage** - Orphaned files waste storage
+3. **Not validating file types** - Security risk for malicious uploads
+4. **Large file uploads without progress** - Poor UX for users
+5. **Using deprecated getMetadata** - Use ctx.db.system.get instead
+
+## References
+
+- Convex Documentation: https://docs.convex.dev/
+- Convex LLMs.txt: https://docs.convex.dev/llms.txt
+- File Storage: https://docs.convex.dev/file-storage
+- Upload Files: https://docs.convex.dev/file-storage/upload-files
+- Serve Files: https://docs.convex.dev/file-storage/serve-files

package/assets/.agent/skills/convex-file-storage/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-file-storage/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>