@codaijs/keel 0.1.0

package/sails/analytics/install.ts

@@ -0,0 +1,297 @@
+/**
+ * PostHog Analytics Sail Installer
+ *
+ * Adds privacy-friendly analytics with PostHog — automatic page views,
+ * user identification, and custom event tracking.
+ *
+ * PostHog can be used as a cloud service or self-hosted.
+ *
+ * Usage:
+ *   npx tsx sails/analytics/install.ts
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+} from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { execSync } from "node:child_process";
+import { input, confirm, select } from "@inquirer/prompts";
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const SAIL_DIR = dirname(new URL(import.meta.url).pathname);
+const PROJECT_ROOT = resolve(SAIL_DIR, "../..");
+const FRONTEND_ROOT = join(PROJECT_ROOT, "packages/frontend");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface SailManifest {
+  name: string;
+  displayName: string;
+  version: string;
+  requiredEnvVars: { key: string; description: string }[];
+  dependencies: { backend: Record<string, string>; frontend: Record<string, string> };
+}
+
+function loadManifest(): SailManifest {
+  return JSON.parse(readFileSync(join(SAIL_DIR, "addon.json"), "utf-8"));
+}
+
+function copyFile(src: string, dest: string, label: string): void {
+  mkdirSync(dirname(dest), { recursive: true });
+  copyFileSync(src, dest);
+  console.log(`  Copied -> ${label}`);
+}
+
+function appendToEnvFiles(section: string, entries: Record<string, string>): void {
+  for (const envFile of [".env.example", ".env"]) {
+    const envPath = join(PROJECT_ROOT, envFile);
+    if (!existsSync(envPath)) continue;
+    let content = readFileSync(envPath, "utf-8");
+    const lines: string[] = [];
+    for (const [key, val] of Object.entries(entries)) {
+      if (!content.includes(key)) lines.push(`${key}=${val}`);
+    }
+    if (lines.length > 0) {
+      content += `\n# ${section}\n${lines.join("\n")}\n`;
+      writeFileSync(envPath, content, "utf-8");
+      console.log(`  Updated ${envFile}`);
+    }
+  }
+}
+
+function installDeps(deps: Record<string, string>, workspace: string): void {
+  const entries = Object.entries(deps);
+  if (entries.length === 0) return;
+  const packages = entries.map(([n, v]) => `${n}@${v}`).join(" ");
+  const cmd = `npm install ${packages} --workspace=${workspace}`;
+  console.log(`  Running: ${cmd}`);
+  execSync(cmd, { cwd: PROJECT_ROOT, stdio: "inherit" });
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const manifest = loadManifest();
+
+  // -- Step 1: Welcome --------------------------------------------------------
+  console.log("\n------------------------------------------------------------");
+  console.log(`  PostHog Analytics Sail Installer (v${manifest.version})`);
+  console.log("------------------------------------------------------------");
+  console.log();
+  console.log("  This sail adds PostHog analytics to your app:");
+  console.log("    - Automatic page view tracking on SPA route changes");
+  console.log("    - User identification tied to your auth system");
+  console.log("    - Custom event tracking for feature usage");
+  console.log("    - Session recording and heatmaps (configurable in PostHog)");
+  console.log();
+  console.log("  PostHog is privacy-friendly, open-source, and GDPR-compatible.");
+  console.log("  You can use PostHog Cloud or self-host it.");
+  console.log();
+
+  const pkgPath = join(PROJECT_ROOT, "package.json");
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    console.log(`  Template version: ${pkg.version ?? "unknown"}`);
+    console.log();
+  }
+
+  // -- Step 2: Hosting choice -------------------------------------------------
+  const hostingChoice = await select({
+    message: "How will you use PostHog?",
+    choices: [
+      {
+        name: "PostHog Cloud (US)",
+        value: "cloud-us",
+        description: "Hosted by PostHog at us.i.posthog.com — easiest setup",
+      },
+      {
+        name: "PostHog Cloud (EU)",
+        value: "cloud-eu",
+        description: "Hosted by PostHog at eu.i.posthog.com — EU data residency",
+      },
+      {
+        name: "Self-hosted",
+        value: "self-hosted",
+        description: "Your own PostHog instance — full data control",
+      },
+    ],
+  });
+
+  let posthogHost: string;
+
+  if (hostingChoice === "cloud-us") {
+    posthogHost = "https://us.i.posthog.com";
+    console.log();
+    console.log("  To get your API key:");
+    console.log("  1. Sign up or log in at https://app.posthog.com");
+    console.log("  2. Create a project (or select existing)");
+    console.log("  3. Go to Project Settings");
+    console.log("  4. Copy the Project API Key");
+    console.log();
+  } else if (hostingChoice === "cloud-eu") {
+    posthogHost = "https://eu.i.posthog.com";
+    console.log();
+    console.log("  To get your API key:");
+    console.log("  1. Sign up or log in at https://eu.posthog.com");
+    console.log("  2. Create a project (or select existing)");
+    console.log("  3. Go to Project Settings");
+    console.log("  4. Copy the Project API Key");
+    console.log();
+  } else {
+    console.log();
+    posthogHost = await input({
+      message: "PostHog instance URL (e.g., https://posthog.yourdomain.com):",
+      validate: (value) => {
+        if (!value || value.trim().length === 0) return "Host URL is required.";
+        if (!value.startsWith("http")) return "Should start with http:// or https://";
+        return true;
+      },
+    });
+    posthogHost = posthogHost.replace(/\/+$/, ""); // Remove trailing slashes
+    console.log();
+  }
+
+  // -- Step 3: Collect API key ------------------------------------------------
+  const posthogKey = await input({
+    message: "PostHog Project API Key:",
+    validate: (value) => {
+      if (!value || value.trim().length === 0) return "API key is required.";
+      if (value.startsWith("phx_")) return "This looks like a personal API key. Use the Project API key (starts with 'phc_').";
+      return true;
+    },
+  });
+
+  // -- Step 4: Summary --------------------------------------------------------
+  console.log();
+  console.log("  Summary of changes:");
+  console.log("  -------------------");
+  console.log("  Files to create (frontend):");
+  console.log("    + packages/frontend/src/lib/analytics.ts");
+  console.log("    + packages/frontend/src/hooks/useAnalytics.ts");
+  console.log("    + packages/frontend/src/components/AnalyticsProvider.tsx");
+  console.log();
+  console.log("  Files to modify:");
+  console.log("    ~ packages/frontend/src/App.tsx");
+  console.log("    ~ .env.example / .env");
+  console.log();
+  console.log("  Environment variables:");
+  console.log(`    VITE_POSTHOG_KEY=${posthogKey.slice(0, 12)}...`);
+  console.log(`    VITE_POSTHOG_HOST=${posthogHost}`);
+  console.log();
+
+  // -- Step 5: Confirm --------------------------------------------------------
+  const proceed = await confirm({ message: "Proceed with installation?", default: true });
+  if (!proceed) { console.log("\n  Installation cancelled.\n"); process.exit(0); }
+
+  console.log();
+  console.log("  Installing...");
+  console.log();
+
+  // -- Step 6: Copy files and modify App.tsx ----------------------------------
+  console.log("  Copying frontend files...");
+  const frontendFiles = [
+    { src: "frontend/lib/analytics.ts", dest: "src/lib/analytics.ts" },
+    { src: "frontend/hooks/useAnalytics.ts", dest: "src/hooks/useAnalytics.ts" },
+    { src: "frontend/components/AnalyticsProvider.tsx", dest: "src/components/AnalyticsProvider.tsx" },
+  ];
+  for (const f of frontendFiles) {
+    copyFile(join(SAIL_DIR, "files", f.src), join(FRONTEND_ROOT, f.dest), f.dest);
+  }
+
+  console.log();
+  console.log("  Modifying App.tsx...");
+
+  const appPath = join(FRONTEND_ROOT, "src/App.tsx");
+  if (existsSync(appPath)) {
+    let appContent = readFileSync(appPath, "utf-8");
+
+    if (!appContent.includes("AnalyticsProvider")) {
+      // Add import
+      const importLine = 'import { AnalyticsProvider } from "./components/AnalyticsProvider.js";';
+      // Find the last import line and add after it
+      const lastImport = appContent.lastIndexOf("import ");
+      const importLineEnd = appContent.indexOf("\n", lastImport);
+      appContent =
+        appContent.slice(0, importLineEnd + 1) +
+        importLine + "\n" +
+        appContent.slice(importLineEnd + 1);
+
+      // Wrap <AppRouter /> with <AnalyticsProvider>
+      appContent = appContent.replace(
+        "<AppRouter />",
+        "<AnalyticsProvider>\n      <AppRouter />\n    </AnalyticsProvider>",
+      );
+
+      writeFileSync(appPath, appContent, "utf-8");
+      console.log("  Modified -> App.tsx");
+    } else {
+      console.log("  Skipped (already present) -> App.tsx");
+    }
+  } else {
+    console.warn("  Warning: App.tsx not found. Wrap your app with <AnalyticsProvider> manually.");
+  }
+
+  console.log();
+  console.log("  Installing dependencies...");
+  installDeps(manifest.dependencies.frontend, "packages/frontend");
+
+  console.log();
+  console.log("  Updating environment files...");
+  appendToEnvFiles("PostHog Analytics", {
+    VITE_POSTHOG_KEY: posthogKey.trim(),
+    VITE_POSTHOG_HOST: posthogHost,
+  });
+
+  // -- Step 7: Next steps ------------------------------------------------------
+  console.log();
+  console.log("------------------------------------------------------------");
+  console.log("  PostHog Analytics installed successfully!");
+  console.log("------------------------------------------------------------");
+  console.log();
+  console.log("  Next steps:");
+  console.log();
+  console.log("  1. Start your dev server:");
+  console.log("       npm run dev");
+  console.log();
+  console.log("  2. Verify analytics is working:");
+  console.log("     - Open your app in the browser");
+  console.log("     - Log in and navigate between pages");
+  console.log("     - Check PostHog dashboard for events");
+  console.log();
+  console.log("  3. Configure PostHog features (optional):");
+  console.log("     - Session Recording: enable in PostHog project settings");
+  console.log("     - Feature Flags: use posthog.isFeatureEnabled('flag-name')");
+  console.log("     - Surveys: create in-app surveys from the PostHog dashboard");
+  console.log();
+  console.log("  4. Track custom events in your components:");
+  console.log();
+  console.log("     import { useAnalytics } from '@/hooks/useAnalytics';");
+  console.log();
+  console.log("     function MyComponent() {");
+  console.log("       const { trackEvent } = useAnalytics();");
+  console.log("       return (");
+  console.log("         <button onClick={() => trackEvent('button_clicked', { label: 'cta' })}>");
+  console.log("           Click me");
+  console.log("         </button>");
+  console.log("       );");
+  console.log("     }");
+  console.log();
+  console.log("  GDPR note:");
+  console.log("    PostHog supports cookie-less tracking and consent management.");
+  console.log("    If you have the GDPR sail installed, consider integrating");
+  console.log("    analytics consent with your consent tracking system.");
+  console.log();
+}
+
+main().catch((err) => { console.error("Installation failed:", err); process.exit(1); });

package/sails/file-uploads/README.md

@@ -0,0 +1,191 @@
+# File Uploads Sail
+
+Generic file upload system with S3-compatible storage. Works with Cloudflare R2, AWS S3, MinIO, and any other S3-compatible provider.
+
+## What this sail adds
+
+### Backend
+- **`src/services/file-storage.ts`** -- S3 client with helpers for presigned URLs, deletion, and listing
+- **`src/routes/files.ts`** -- File management API (all auth-protected):
+  - `POST /api/files/upload-url` -- generate a presigned upload URL
+  - `GET /api/files` -- list the current user's files
+  - `GET /api/files/:fileId` -- get file metadata and download URL
+  - `DELETE /api/files/:fileId` -- delete a file
+- **`src/db/schema/files.ts`** -- Drizzle schema for the `files` table
+
+### Frontend
+- **`src/hooks/useFileUpload.ts`** -- React hook for uploading files with progress tracking
+- **`src/hooks/useFiles.ts`** -- React hook for listing, downloading, and deleting files
+- **`src/components/files/FileUploadButton.tsx`** -- Upload button with drag-and-drop support
+- **`src/components/files/FileList.tsx`** -- File browser with download and delete actions
+- **`src/pages/Files.tsx`** -- Full files page combining upload and browser
+
+### Environment variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `S3_ENDPOINT` | S3-compatible endpoint URL | (required) |
+| `S3_ACCESS_KEY_ID` | S3 access key ID | (required) |
+| `S3_SECRET_ACCESS_KEY` | S3 secret access key | (required) |
+| `S3_BUCKET_NAME` | Bucket name | (required) |
+| `S3_PUBLIC_URL` | Public URL for serving files | `""` |
+| `S3_REGION` | S3 region | `auto` |
+
+## Prerequisites
+
+1. An S3-compatible storage account (Cloudflare R2, AWS S3, MinIO, etc.)
+2. A bucket created in your storage provider
+3. API credentials with read/write permissions
+
+## Setup
+
+### Run the installer
+
+```bash
+npx tsx cli/sails/file-uploads/install.ts
+```
+
+Or use the CLI:
+
+```bash
+npx @codaijs/keel sail add file-uploads
+```
+
+The installer will guide you through:
+1. Choosing your storage provider
+2. Entering credentials
+3. Configuring max file size
+4. Copying files and modifying markers
+5. Installing dependencies and generating migrations
+
+### After installation
+
+1. Run database migrations:
+   ```bash
+   npm run db:migrate
+   ```
+
+2. Configure CORS on your storage bucket (see below)
+
+3. Start the dev server:
+   ```bash
+   npm run dev
+   ```
+
+4. Navigate to `/files` to test
+
+## Upload flow
+
+1. The frontend calls `POST /api/files/upload-url` with the file name and content type
+2. The backend generates a presigned PUT URL and creates a file record in the database
+3. The frontend uploads the file directly to storage using the presigned URL
+4. The file is now tracked in the database and available for listing, downloading, and deletion
+
+Files never pass through your server -- they go directly from the browser to storage.
+
+## CORS configuration
+
+Your storage bucket must allow PUT and GET requests from your frontend origin.
+
+### Cloudflare R2
+
+In your bucket settings, add a CORS policy:
+
+```json
+[
+  {
+    "AllowedOrigins": ["http://localhost:5173", "https://yourdomain.com"],
+    "AllowedMethods": ["GET", "PUT"],
+    "AllowedHeaders": ["Content-Type"],
+    "MaxAgeSeconds": 3600
+  }
+]
+```
+
+### AWS S3
+
+In bucket permissions, add a CORS configuration:
+
+```json
+[
+  {
+    "AllowedHeaders": ["Content-Type"],
+    "AllowedMethods": ["GET", "PUT"],
+    "AllowedOrigins": ["http://localhost:5173", "https://yourdomain.com"],
+    "MaxAgeSeconds": 3600
+  }
+]
+```
+
+### MinIO
+
+```bash
+mc admin config set local api cors_allow_origin=http://localhost:5173
+mc admin service restart local
+```
+
+## Usage in your own components
+
+### Upload a file
+
+```tsx
+import { useFileUpload } from "@/hooks/useFileUpload";
+
+function MyComponent() {
+  const { upload, isUploading, progress, error } = useFileUpload();
+
+  const handleUpload = async (file: File) => {
+    const result = await upload(file);
+    if (result) {
+      console.log("Uploaded:", result.id, result.fileName);
+    }
+  };
+}
+```
+
+### List and manage files
+
+```tsx
+import { useFiles } from "@/hooks/useFiles";
+
+function MyComponent() {
+  const { files, isLoading, deleteFile, getDownloadUrl, refresh } = useFiles();
+
+  const handleDownload = async (id: string) => {
+    const url = await getDownloadUrl(id);
+    if (url) window.open(url);
+  };
+}
+```
+
+### Custom upload button
+
+```tsx
+import { FileUploadButton } from "@/components/files/FileUploadButton";
+
+<FileUploadButton
+  accept="image/*,.pdf"
+  maxSize={10 * 1024 * 1024} // 10 MB
+  onUploadComplete={(file) => console.log("Uploaded:", file)}
+/>
+```
+
+## Difference from the r2-storage sail
+
+The **r2-storage** sail is focused specifically on Cloudflare R2 and profile picture uploads. This **file-uploads** sail is a more general-purpose system:
+
+- Works with any S3-compatible provider (R2, S3, MinIO)
+- Supports any file type, not just images
+- Tracks files in a database table
+- Includes a full file browser UI
+- Supports listing, downloading, and deleting files
+
+If you only need profile picture uploads with R2, use the r2-storage sail instead.
+
+## Troubleshooting
+
+- **CORS errors**: Make sure your bucket CORS policy includes your frontend origin and allows PUT/GET methods
+- **403 Forbidden**: Verify your API credentials have the correct permissions
+- **Upload succeeds but file not in list**: Check the server logs for database insert errors
+- **Presigned URL expired**: URLs expire after 10 minutes -- upload should happen immediately
+- **Large files timing out**: Increase the presigned URL expiry in `file-storage.ts` or your reverse proxy timeout

package/sails/file-uploads/addon.json

@@ -0,0 +1,30 @@
+{
+  "name": "file-uploads",
+  "displayName": "File Uploads",
+  "description": "Generic file upload system with S3-compatible storage (R2, S3, MinIO). Includes file management API, upload hooks, and a file browser component.",
+  "version": "1.0.0",
+  "compatibility": ">=1.0.0",
+  "requiredEnvVars": [
+    { "key": "S3_ENDPOINT", "description": "S3-compatible endpoint URL" },
+    { "key": "S3_ACCESS_KEY_ID", "description": "S3 access key ID" },
+    { "key": "S3_SECRET_ACCESS_KEY", "description": "S3 secret access key" },
+    { "key": "S3_BUCKET_NAME", "description": "S3 bucket name" },
+    { "key": "S3_PUBLIC_URL", "description": "Public URL for serving files" },
+    { "key": "S3_REGION", "description": "S3 region (defaults to auto)" }
+  ],
+  "dependencies": {
+    "backend": {
+      "@aws-sdk/client-s3": "^3.700.0",
+      "@aws-sdk/s3-request-presigner": "^3.700.0"
+    },
+    "frontend": {}
+  },
+  "modifies": {
+    "backend": ["src/index.ts", "src/db/schema/index.ts", "src/env.ts"],
+    "frontend": ["src/router.tsx"]
+  },
+  "adds": {
+    "backend": ["src/services/file-storage.ts", "src/routes/files.ts", "src/db/schema/files.ts"],
+    "frontend": ["src/hooks/useFileUpload.ts", "src/hooks/useFiles.ts", "src/components/files/FileUploadButton.tsx", "src/components/files/FileList.tsx", "src/pages/Files.tsx"]
+  }
+}