@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/configure-storage/SKILL.md

@@ -0,0 +1,273 @@
+# Skill: Configure File Storage
+
+Set up file uploads and storage in a MARS application using Vercel Blob, S3, or local storage.
+
+## When to Use
+
+Use this skill when the user asks to add file uploads, image uploads, document storage, or configure a storage provider.
+
+## Prerequisites
+
+- `appConfig.features.fileUpload` set to `true`
+- `appConfig.services.storage.provider` set to `'vercel'`, `'s3'`, or `'local'`
+
+## Step 1: Install SDK
+
+**Vercel Blob:**
+```bash
+yarn add @vercel/blob
+```
+
+**AWS S3:**
+```bash
+yarn add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
+```
+
+## Step 2: Environment Variables
+
+**Vercel Blob:**
+```bash
+BLOB_READ_WRITE_TOKEN="vercel_blob_..."
+```
+
+**AWS S3:**
+```bash
+AWS_ACCESS_KEY_ID="..."
+AWS_SECRET_ACCESS_KEY="..."
+AWS_REGION="eu-west-2"
+S3_BUCKET_NAME="my-app-uploads"
+```
+
+## Step 3: Create the Storage Service
+
+```typescript
+// src/core/storage/index.ts
+import 'server-only';
+
+import { appConfig } from '@/config/app.config';
+
+export interface UploadResult {
+  url: string;
+  pathname: string;
+  size: number;
+}
+
+export interface StorageService {
+  upload(file: File, path: string): Promise<UploadResult>;
+  delete(url: string): Promise<void>;
+  getSignedUrl(url: string): Promise<string>;
+}
+
+async function createVercelBlobStorage(): Promise<StorageService> {
+  const { put, del } = await import('@vercel/blob');
+
+  return {
+    async upload(file: File, path: string): Promise<UploadResult> {
+      const blob = await put(path, file, {
+        access: 'public',
+        token: process.env.BLOB_READ_WRITE_TOKEN,
+      });
+      return { url: blob.url, pathname: blob.pathname, size: file.size };
+    },
+    async delete(url: string): Promise<void> {
+      await del(url, { token: process.env.BLOB_READ_WRITE_TOKEN });
+    },
+    async getSignedUrl(url: string): Promise<string> {
+      return url; // Vercel Blob public URLs don't need signing
+    },
+  };
+}
+
+async function createS3Storage(): Promise<StorageService> {
+  const { S3Client, PutObjectCommand, DeleteObjectCommand, GetObjectCommand } =
+    await import('@aws-sdk/client-s3');
+  const { getSignedUrl } = await import('@aws-sdk/s3-request-presigner');
+
+  const client = new S3Client({ region: process.env.AWS_REGION });
+  const bucket = process.env.S3_BUCKET_NAME!;
+
+  return {
+    async upload(file: File, path: string): Promise<UploadResult> {
+      const buffer = Buffer.from(await file.arrayBuffer());
+      await client.send(
+        new PutObjectCommand({
+          Bucket: bucket,
+          Key: path,
+          Body: buffer,
+          ContentType: file.type,
+        }),
+      );
+      const url = `https://${bucket}.s3.${process.env.AWS_REGION}.amazonaws.com/${path}`;
+      return { url, pathname: path, size: file.size };
+    },
+    async delete(url: string): Promise<void> {
+      const key = new URL(url).pathname.slice(1);
+      await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+    },
+    async getSignedUrl(url: string): Promise<string> {
+      const key = new URL(url).pathname.slice(1);
+      return getSignedUrl(client, new GetObjectCommand({ Bucket: bucket, Key: key }), {
+        expiresIn: 3600,
+      });
+    },
+  };
+}
+
+let _storage: StorageService | null = null;
+
+export async function getStorage(): Promise<StorageService> {
+  if (_storage) return _storage;
+
+  const provider = appConfig.services.storage.provider;
+  switch (provider) {
+    case 'vercel':
+      _storage = await createVercelBlobStorage();
+      break;
+    case 's3':
+      _storage = await createS3Storage();
+      break;
+    default:
+      throw new Error(`Storage provider "${provider}" is not configured. Set appConfig.services.storage.provider.`);
+  }
+
+  return _storage;
+}
+```
+
+## Step 4: Upload API Route
+
+```typescript
+// src/app/api/protected/upload/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { getStorage } from '@/core/storage';
+import { NextResponse } from 'next/server';
+
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
+const ALLOWED_TYPES = ['image/jpeg', 'image/png', 'image/webp', 'application/pdf'];
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const formData = await request.formData();
+    const file = formData.get('file') as File | null;
+
+    if (!file) {
+      return NextResponse.json({ error: 'No file provided' }, { status: 400 });
+    }
+
+    if (file.size > MAX_FILE_SIZE) {
+      return NextResponse.json({ error: 'File too large (max 10MB)' }, { status: 400 });
+    }
+
+    if (!ALLOWED_TYPES.includes(file.type)) {
+      return NextResponse.json({ error: 'File type not allowed' }, { status: 400 });
+    }
+
+    const userId = request.session.userId;
+    const ext = file.name.split('.').pop() || 'bin';
+    const path = `uploads/${userId}/${Date.now()}.${ext}`;
+
+    const storage = await getStorage();
+    const result = await storage.upload(file, path);
+
+    return NextResponse.json(result, { status: 201 });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/upload' });
+  }
+});
+```
+
+## Step 5: Client Upload Component
+
+```tsx
+'use client';
+
+import { Button, Spinner } from '@mars-stack/ui';
+import { useState, useRef } from 'react';
+
+interface FileUploadProps {
+  onUpload: (result: { url: string; pathname: string }) => void;
+  accept?: string;
+  maxSize?: number;
+}
+
+export function FileUpload({ onUpload, accept = 'image/*', maxSize = 10 }: FileUploadProps) {
+  const [uploading, setUploading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  async function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0];
+    if (!file) return;
+
+    if (file.size > maxSize * 1024 * 1024) {
+      setError(`File too large (max ${maxSize}MB)`);
+      return;
+    }
+
+    setError(null);
+    setUploading(true);
+
+    try {
+      const formData = new FormData();
+      formData.append('file', file);
+
+      const res = await fetch('/api/protected/upload', {
+        method: 'POST',
+        body: formData,
+      });
+
+      if (!res.ok) {
+        const data = await res.json();
+        throw new Error(data.error || 'Upload failed');
+      }
+
+      const result = await res.json();
+      onUpload(result);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Upload failed');
+    } finally {
+      setUploading(false);
+    }
+  }
+
+  return (
+    <div>
+      <input
+        ref={inputRef}
+        type="file"
+        accept={accept}
+        onChange={handleChange}
+        className="hidden"
+      />
+      <Button
+        type="button"
+        variant="secondary"
+        onClick={() => inputRef.current?.click()}
+        disabled={uploading}
+      >
+        {uploading ? <Spinner size="sm" /> : 'Upload File'}
+      </Button>
+      {error && <p className="mt-1 text-sm text-text-error">{error}</p>}
+    </div>
+  );
+}
+```
+
+## Security Rules
+
+- **Always validate file size and type** on the server, even if checked on the client.
+- **Scope upload paths by userId** to prevent users from overwriting each other's files.
+- **Sanitize filenames** -- never use the original filename in the storage path.
+- **Stream responses** when proxying file downloads (see `data-access` rule).
+- **Set appropriate `Content-Disposition` headers** when serving files for download.
+
+## Checklist
+
+- [ ] Storage SDK installed
+- [ ] Environment variables set
+- [ ] Storage service created (`src/core/storage/index.ts`)
+- [ ] Upload API route with size and type validation
+- [ ] Upload paths scoped by userId
+- [ ] Client upload component
+- [ ] Feature flag checked (`appConfig.features.fileUpload`)
+- [ ] File metadata stored in database (optional but recommended)