@codaijs/keel 0.1.0

package/sails/_template/install.ts

@@ -0,0 +1,402 @@
+/**
+ * Template Sail Installer
+ *
+ * This file serves as a reference implementation for creating sail installers.
+ * Each sail should have its own install.ts that follows this wizard pattern.
+ *
+ * The installer is executed by the CLI tool or can be run standalone:
+ *   npx tsx sails/<sail-name>/install.ts
+ *
+ * ============================================================================
+ * WIZARD PATTERN
+ * ============================================================================
+ *
+ * Every sail installer should follow this 8-step wizard flow:
+ *
+ *   Step 1: Welcome          - Explain what the sail does
+ *   Step 2: Prerequisites    - Check if the user has required accounts/setup
+ *                              If not, provide step-by-step guidance and wait
+ *   Step 3: Credentials      - Collect required API keys and secrets
+ *                              Validate format where possible (prefixes, etc.)
+ *   Step 4: Summary          - Show all files that will be created/modified
+ *                              Show collected env vars (masked)
+ *   Step 5: Confirm          - Ask user to confirm before making changes
+ *   Step 6: Execute          - Copy files, modify markers, update env
+ *   Step 7: Dependencies     - Install npm packages, run migrations
+ *   Step 8: Next steps       - Print what to do next and how to test
+ *
+ * Use @inquirer/prompts for all interactive prompts:
+ *   - input()    for text/credential entry with validation
+ *   - confirm()  for yes/no decisions
+ *   - select()   for choosing one option from a list
+ *   - checkbox() for selecting multiple options
+ *
+ * ============================================================================
+ */
+
+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";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface EnvVar {
+  key: string;
+  description: string;
+}
+
+interface SailManifest {
+  name: string;
+  displayName: string;
+  description: string;
+  version: string;
+  compatibility: string;
+  requiredEnvVars: EnvVar[];
+  dependencies: {
+    backend: Record<string, string>;
+    frontend: Record<string, string>;
+  };
+  modifies: {
+    backend: string[];
+    frontend: string[];
+  };
+  adds: {
+    backend: string[];
+    frontend: string[];
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const SAIL_DIR = dirname(new URL(import.meta.url).pathname);
+const PROJECT_ROOT = resolve(SAIL_DIR, "../..");
+
+function loadManifest(): SailManifest {
+  const raw = readFileSync(join(SAIL_DIR, "addon.json"), "utf-8");
+  return JSON.parse(raw) as SailManifest;
+}
+
+// ---------------------------------------------------------------------------
+// Step 1 -- Welcome message
+// ---------------------------------------------------------------------------
+
+function printWelcome(manifest: SailManifest): void {
+  console.log("\n------------------------------------------------------------");
+  console.log(`  ${manifest.displayName} Installer (v${manifest.version})`);
+  console.log("------------------------------------------------------------");
+  console.log();
+  console.log(`  ${manifest.description}`);
+  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(`  Required compatibility: ${manifest.compatibility}`);
+    console.log();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Step 2 -- Prerequisites check
+// ---------------------------------------------------------------------------
+
+async function checkPrerequisites(): Promise<void> {
+  const hasPrereqs = await confirm({
+    message: "Do you have the required external service account set up?",
+    default: false,
+  });
+
+  if (!hasPrereqs) {
+    console.log();
+    console.log("  Follow these steps to set up the required service:");
+    console.log();
+    console.log("  1. Go to <service dashboard URL>");
+    console.log("  2. Create an account or sign in");
+    console.log("  3. Create the required resources (API keys, projects, etc.)");
+    console.log("  4. Note down the credentials you will need");
+    console.log();
+
+    await confirm({
+      message: "I have completed the setup and have my credentials ready",
+      default: false,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Step 3 -- Collect credentials
+// ---------------------------------------------------------------------------
+
+async function collectCredentials(
+  envVars: EnvVar[]
+): Promise<Record<string, string>> {
+  const values: Record<string, string> = {};
+
+  console.log();
+  for (const v of envVars) {
+    const value = await input({
+      message: `${v.description}:`,
+      validate: (val) => {
+        if (!val || val.trim().length === 0) {
+          return `${v.key} is required.`;
+        }
+        return true;
+      },
+    });
+    values[v.key] = value.trim();
+  }
+
+  return values;
+}
+
+// ---------------------------------------------------------------------------
+// Step 4 -- Show summary
+// ---------------------------------------------------------------------------
+
+function showSummary(
+  manifest: SailManifest,
+  envValues: Record<string, string>
+): void {
+  console.log();
+  console.log("  Summary of changes:");
+  console.log("  -------------------");
+
+  if (manifest.adds.backend.length > 0 || manifest.adds.frontend.length > 0) {
+    console.log("  Files to create:");
+    for (const f of manifest.adds.backend) {
+      console.log(`    + packages/backend/${f}`);
+    }
+    for (const f of manifest.adds.frontend) {
+      console.log(`    + packages/frontend/${f}`);
+    }
+    console.log();
+  }
+
+  if (manifest.modifies.backend.length > 0 || manifest.modifies.frontend.length > 0) {
+    console.log("  Files to modify:");
+    for (const f of manifest.modifies.backend) {
+      console.log(`    ~ packages/backend/${f}`);
+    }
+    for (const f of manifest.modifies.frontend) {
+      console.log(`    ~ packages/frontend/${f}`);
+    }
+    console.log();
+  }
+
+  console.log("  Environment variables:");
+  for (const [key, val] of Object.entries(envValues)) {
+    const masked = val.length > 8 ? val.slice(0, 8) + "..." : val;
+    console.log(`    ${key}=${masked}`);
+  }
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// Step 5 -- Confirm
+// ---------------------------------------------------------------------------
+
+async function confirmInstallation(): Promise<void> {
+  const proceed = await confirm({
+    message: "Proceed with installation?",
+    default: true,
+  });
+
+  if (!proceed) {
+    console.log("\n  Installation cancelled.\n");
+    process.exit(0);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Step 6 -- Execute
+// ---------------------------------------------------------------------------
+
+function copySailFiles(manifest: SailManifest): void {
+  const filesDir = join(SAIL_DIR, "files");
+  if (!existsSync(filesDir)) {
+    console.log("  No files/ directory -- skipping file copy.");
+    return;
+  }
+
+  console.log("  Copying files...");
+
+  for (const file of manifest.adds.backend) {
+    const src = join(filesDir, "backend", file.replace(/^src\//, ""));
+    const dest = join(PROJECT_ROOT, "packages/backend", file);
+    if (existsSync(src)) {
+      mkdirSync(dirname(dest), { recursive: true });
+      copyFileSync(src, dest);
+      console.log(`    Copied -> ${file}`);
+    }
+  }
+
+  for (const file of manifest.adds.frontend) {
+    const src = join(filesDir, "frontend", file.replace(/^src\//, ""));
+    const dest = join(PROJECT_ROOT, "packages/frontend", file);
+    if (existsSync(src)) {
+      mkdirSync(dirname(dest), { recursive: true });
+      copyFileSync(src, dest);
+      console.log(`    Copied -> ${file}`);
+    }
+  }
+}
+
+function insertAtMarker(
+  filePath: string,
+  marker: string,
+  insertion: string
+): void {
+  if (!existsSync(filePath)) {
+    console.warn(`  Warning: File not found: ${filePath} -- skipping.`);
+    return;
+  }
+
+  const content = readFileSync(filePath, "utf-8");
+
+  if (!content.includes(marker)) {
+    console.warn(`  Warning: Marker "${marker}" not found in ${filePath}.`);
+    return;
+  }
+
+  if (content.includes(insertion.trim())) {
+    console.log(`    Skipped (already present) -> ${filePath}`);
+    return;
+  }
+
+  const updated = content.replace(marker, `${marker}\n${insertion}`);
+  writeFileSync(filePath, updated, "utf-8");
+  console.log(`    Inserted at ${marker} -> ${filePath}`);
+}
+
+function updateEnvFiles(
+  sectionName: string,
+  envVars: Record<string, string>
+): void {
+  console.log("  Updating environment files...");
+
+  for (const envFile of [".env.example", ".env"]) {
+    const envPath = join(PROJECT_ROOT, envFile);
+    if (!existsSync(envPath)) continue;
+
+    let content = readFileSync(envPath, "utf-8");
+    const additions: string[] = [];
+    for (const [key, value] of Object.entries(envVars)) {
+      if (!content.includes(key)) {
+        additions.push(`${key}=${value}`);
+      }
+    }
+
+    if (additions.length > 0) {
+      content += `\n# ${sectionName}\n${additions.join("\n")}\n`;
+      writeFileSync(envPath, content, "utf-8");
+      console.log(`    Updated ${envFile}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Step 7 -- Install dependencies and run migrations
+// ---------------------------------------------------------------------------
+
+function installDependencies(
+  deps: Record<string, string>,
+  workspace: string
+): void {
+  const entries = Object.entries(deps);
+  if (entries.length === 0) return;
+
+  const packages = entries.map(([name, version]) => `${name}@${version}`).join(" ");
+  const cmd = `npm install ${packages} --workspace=${workspace}`;
+  console.log(`    Running: ${cmd}`);
+  execSync(cmd, { cwd: PROJECT_ROOT, stdio: "inherit" });
+}
+
+function generateMigrations(): void {
+  console.log("    Running: npx drizzle-kit generate");
+  try {
+    execSync("npx drizzle-kit generate", {
+      cwd: join(PROJECT_ROOT, "packages/backend"),
+      stdio: "inherit",
+    });
+  } catch {
+    console.warn("    Warning: Could not generate migrations. Run manually:");
+    console.warn("      cd packages/backend && npx drizzle-kit generate");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Step 8 -- Print next steps
+// ---------------------------------------------------------------------------
+
+function printNextSteps(manifest: SailManifest): void {
+  console.log();
+  console.log("------------------------------------------------------------");
+  console.log(`  ${manifest.displayName} installed successfully!`);
+  console.log("------------------------------------------------------------");
+  console.log();
+  console.log("  Next steps:");
+  console.log("  1. Fill in any placeholder env vars in .env");
+  console.log("  2. Run database migrations: npm run db:migrate");
+  console.log("  3. Review the modified files listed in addon.json");
+  console.log("  4. Read the sail README for provider-specific setup");
+  console.log();
+  console.log("  Testing:");
+  console.log("  1. Start your dev server: npm run dev");
+  console.log("  2. Test the new functionality in the browser");
+  console.log("  3. Check server logs for any configuration errors");
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const manifest = loadManifest();
+
+  printWelcome(manifest);
+  await checkPrerequisites();
+  const envValues = await collectCredentials(manifest.requiredEnvVars);
+  showSummary(manifest, envValues);
+  await confirmInstallation();
+
+  console.log();
+  console.log("  Installing...");
+  console.log();
+  copySailFiles(manifest);
+
+  console.log();
+  console.log("  Modifying existing files...");
+  // Sail specific marker insertions go here. Example:
+  //   insertAtMarker(
+  //     join(PROJECT_ROOT, "packages/backend/src/index.ts"),
+  //     "// [SAIL_IMPORTS]",
+  //     'import { myRouter } from "./routes/my-route";'
+  //   );
+
+  updateEnvFiles(manifest.displayName, envValues);
+
+  console.log();
+  console.log("  Installing dependencies...");
+  installDependencies(manifest.dependencies.backend, "packages/backend");
+  installDependencies(manifest.dependencies.frontend, "packages/frontend");
+
+  if (manifest.adds.backend.some((f) => f.includes("schema"))) {
+    console.log();
+    console.log("  Generating database migrations...");
+    generateMigrations();
+  }
+
+  printNextSteps(manifest);
+}
+
+main().catch((err) => {
+  console.error("Installation failed:", err);
+  process.exit(1);
+});

package/sails/admin-dashboard/README.md

@@ -0,0 +1,117 @@
+# Admin Dashboard Sail
+
+Adds a user management and metrics dashboard to your keel application. Access is restricted to email addresses listed in the `ADMIN_EMAILS` environment variable.
+
+## Features
+
+- Dashboard with stats cards (total users, new this week/month, active sessions)
+- User signup chart (last 30 days) powered by recharts
+- Users table with search, sorting, and pagination
+- User detail view with admin actions
+- Admin actions: verify email, delete user
+- Access controlled via `ADMIN_EMAILS` environment variable
+- Admin middleware for backend route protection
+
+## Prerequisites
+
+- A working keel project with BetterAuth authentication
+- At least one user account with an email you want to use as admin
+
+## Installation
+
+```bash
+npx tsx sails/admin-dashboard/install.ts
+```
+
+The installer will prompt for admin email addresses and configure everything automatically.
+
+## Manual Setup
+
+### 1. Environment Variables
+
+Add the following to your `.env`:
+
+```env
+ADMIN_EMAILS=admin@example.com,another-admin@example.com
+```
+
+Multiple emails are separated by commas.
+
+### 2. Access the Dashboard
+
+1. Start your dev server: `npm run dev`
+2. Log in with an admin email address
+3. Navigate to `/admin`
+
+## Architecture
+
+### Backend
+
+**Admin Middleware** (`src/middleware/admin.ts`)
+
+Checks if the authenticated user's email is in the `ADMIN_EMAILS` list. Returns 403 if not. Must be used after `requireAuth`.
+
+**Admin Routes** (`src/routes/admin.ts`)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | /api/admin/users | List users (paginated, searchable) |
+| GET | /api/admin/users/:id | Get user details |
+| PATCH | /api/admin/users/:id | Update user (name, emailVerified) |
+| DELETE | /api/admin/users/:id | Delete a user |
+| GET | /api/admin/stats | Dashboard statistics |
+
+All routes require authentication + admin privileges.
+
+### Frontend
+
+**Dashboard** (`/admin`)
+
+The main admin page showing:
+- Stats cards with key metrics
+- Line chart of user signups over the last 30 days
+- Searchable, sortable users table
+
+**User Detail** (`/admin/users/:id`)
+
+Detailed view of a single user with:
+- User profile information
+- Active session count
+- Admin actions (verify email, delete user)
+
+### Components
+
+- `StatsCard` - Reusable card for displaying a metric with optional trend
+- `UsersTable` - Table with search, sort, and pagination
+
+### Hooks
+
+- `useAdminStats()` - Fetch dashboard statistics
+- `useAdminUsers(page, search)` - Fetch paginated user list
+- `fetchUser(id)` - Get single user details
+- `updateUser(id, data)` - Update user fields
+- `deleteUser(id)` - Delete a user
+
+## Customization
+
+### Adding Admin Link to Header
+
+Add a link to the admin dashboard in your Header component for admin users:
+
+```tsx
+{isAuthenticated && isAdmin && (
+  <Link to="/admin" className="text-sm font-medium text-keel-gray-400 hover:text-white">
+    Admin
+  </Link>
+)}
+```
+
+You can check admin status by comparing the user's email against a list fetched from the backend, or by adding an admin check API endpoint.
+
+### Extending the Dashboard
+
+Add new stats cards by modifying `Dashboard.tsx` and adding corresponding backend queries in `routes/admin.ts`.
+
+### Adding More Admin Actions
+
+Extend the `PATCH /api/admin/users/:id` endpoint to support additional fields, or add new endpoints for other admin operations (e.g., ban user, reset password, impersonate).

package/sails/admin-dashboard/addon.json

@@ -0,0 +1,28 @@
+{
+  "name": "admin-dashboard",
+  "displayName": "Admin Dashboard",
+  "description": "Admin dashboard for user management, metrics, and basic analytics",
+  "version": "1.0.0",
+  "compatibility": ">=1.0.0",
+  "requiredEnvVars": [
+    { "key": "ADMIN_EMAILS", "description": "Comma-separated list of admin email addresses" }
+  ],
+  "dependencies": {
+    "backend": {},
+    "frontend": { "recharts": "^2.15.0" }
+  },
+  "modifies": {
+    "backend": ["src/index.ts", "src/env.ts"],
+    "frontend": ["src/router.tsx"]
+  },
+  "adds": {
+    "backend": ["src/middleware/admin.ts", "src/routes/admin.ts"],
+    "frontend": [
+      "src/pages/admin/Dashboard.tsx",
+      "src/pages/admin/UserDetail.tsx",
+      "src/components/admin/StatsCard.tsx",
+      "src/components/admin/UsersTable.tsx",
+      "src/hooks/useAdmin.ts"
+    ]
+  }
+}

package/sails/admin-dashboard/files/backend/middleware/admin.ts

@@ -0,0 +1,34 @@
+import type { Request, Response, NextFunction } from "express";
+import { env } from "../env.js";
+
+/**
+ * Middleware that checks whether the authenticated user is an admin.
+ * Admin status is determined by the ADMIN_EMAILS environment variable
+ * which contains a comma-separated list of admin email addresses.
+ *
+ * Must be used AFTER requireAuth so that req.user is populated.
+ */
+export function requireAdmin(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): void {
+  const user = req.user;
+
+  if (!user) {
+    res.status(401).json({ error: "Unauthorized" });
+    return;
+  }
+
+  const adminEmails = (env.ADMIN_EMAILS ?? "")
+    .split(",")
+    .map((e) => e.trim().toLowerCase())
+    .filter(Boolean);
+
+  if (!adminEmails.includes(user.email.toLowerCase())) {
+    res.status(403).json({ error: "Forbidden: admin access required" });
+    return;
+  }
+
+  next();
+}