@codaijs/keel 0.1.0

package/sails/google-oauth/README.md

@@ -0,0 +1,121 @@
+# Google OAuth Sail
+
+Adds Google sign-in to your keel application using BetterAuth's social provider system.
+
+## Prerequisites
+
+- A Google Cloud project
+- OAuth 2.0 credentials (Client ID and Client Secret)
+
+## Installation
+
+```bash
+npx tsx sails/google-oauth/install.ts
+```
+
+The installer will prompt for your Google OAuth credentials and configure everything automatically.
+
+## Manual Setup: Google Cloud Console
+
+### 1. Create or Select a Project
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Click the project dropdown in the top bar
+3. Click **New Project** or select an existing one
+
+### 2. Enable the Google+ API (if not enabled)
+
+1. Go to **APIs & Services** > **Library**
+2. Search for "Google+ API" or "Google Identity"
+3. Click **Enable**
+
+### 3. Configure the OAuth Consent Screen
+
+1. Go to **APIs & Services** > **OAuth consent screen**
+2. Select **External** (or **Internal** for Google Workspace orgs)
+3. Fill in the required fields:
+   - **App name**: Your application name
+   - **User support email**: Your email
+   - **Developer contact information**: Your email
+4. Add scopes: `email`, `profile`, `openid`
+5. Add test users if in "Testing" mode
+
+### 4. Create OAuth 2.0 Credentials
+
+1. Go to **APIs & Services** > **Credentials**
+2. Click **Create Credentials** > **OAuth client ID**
+3. Select **Web application**
+4. Set the name (e.g., "My App - Web")
+5. Add **Authorized JavaScript origins**:
+   - `http://localhost:5173` (Vite dev server)
+   - `https://yourdomain.com` (production)
+6. Add **Authorized redirect URIs**:
+   - `http://localhost:3000/api/auth/callback/google` (development)
+   - `https://yourdomain.com/api/auth/callback/google` (production)
+7. Click **Create**
+8. Copy the **Client ID** and **Client Secret**
+
+### 5. Configure Environment Variables
+
+Add to your `.env` file:
+
+```env
+GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=your-client-secret
+```
+
+## How It Works
+
+### Authentication Flow
+
+1. User clicks "Continue with Google" button
+2. BetterAuth redirects to Google's OAuth consent screen
+3. User authorizes the application
+4. Google redirects back to `/api/auth/callback/google`
+5. BetterAuth creates or links the user account
+6. User is redirected to the dashboard
+
+### Files Modified
+
+**Backend:**
+- `src/auth/index.ts` -- Google added as a social provider in BetterAuth config
+- `src/env.ts` -- Environment variable validation for Google credentials
+
+**Frontend:**
+- `src/components/auth/LoginForm.tsx` -- Google sign-in button added
+- `src/components/auth/SignupForm.tsx` -- Google sign-in button added
+
+### Files Added
+
+**Frontend:**
+- `src/components/auth/GoogleButton.tsx` -- Styled Google sign-in button component
+
+## Capacitor / Native Apps
+
+For native mobile apps using Capacitor, Google OAuth works through the system browser (in-app browser tab). The redirect URI remains the same since the native app loads the web app in a WebView.
+
+If you need native Google Sign-In (using the Google SDK directly), you will need to:
+
+1. Create separate OAuth credentials for iOS and Android
+2. Use `@capacitor/google-auth` plugin
+3. Pass the token to BetterAuth for session creation
+
+## Troubleshooting
+
+### "redirect_uri_mismatch" Error
+
+Make sure your redirect URI in Google Cloud Console exactly matches:
+- Development: `http://localhost:3000/api/auth/callback/google`
+- Production: `https://yourdomain.com/api/auth/callback/google`
+
+The port must match your backend server port, and the path is determined by BetterAuth.
+
+### "Access blocked: app has not completed verification"
+
+Your OAuth consent screen is in "Testing" mode. Either:
+- Add test users in the consent screen settings, or
+- Submit your app for verification (required for production)
+
+### Users Not Being Linked
+
+If a user signs up with email/password and later tries Google OAuth with the same email, BetterAuth will attempt to link the accounts. Make sure `account linking` is enabled in your BetterAuth configuration.

package/sails/google-oauth/addon.json

@@ -0,0 +1,22 @@
+{
+  "name": "google-oauth",
+  "displayName": "Google OAuth",
+  "description": "Adds Google OAuth sign-in via BetterAuth social provider",
+  "version": "1.0.0",
+  "compatibility": ">=1.0.0",
+  "requiredEnvVars": [
+    { "key": "GOOGLE_CLIENT_ID", "description": "Google OAuth Client ID from Google Cloud Console" },
+    { "key": "GOOGLE_CLIENT_SECRET", "description": "Google OAuth Client Secret" }
+  ],
+  "dependencies": {
+    "backend": {},
+    "frontend": {}
+  },
+  "modifies": {
+    "backend": ["src/auth/index.ts", "src/env.ts"],
+    "frontend": ["src/components/auth/LoginForm.tsx", "src/components/auth/SignupForm.tsx"]
+  },
+  "adds": {
+    "frontend": ["src/components/auth/GoogleButton.tsx"]
+  }
+}

package/sails/google-oauth/files/GoogleButton.tsx

@@ -0,0 +1,50 @@
+import { authClient } from "@/lib/auth-client";
+
+/**
+ * Google sign-in button component.
+ *
+ * Uses BetterAuth's social sign-in to redirect the user to Google's OAuth
+ * consent screen. After authorization, Google redirects back to the app and
+ * BetterAuth completes the session creation automatically.
+ */
+export function GoogleButton() {
+  const handleGoogleSignIn = async () => {
+    await authClient.signIn.social({
+      provider: "google",
+      callbackURL: "/dashboard",
+    });
+  };
+
+  return (
+    <button
+      type="button"
+      onClick={handleGoogleSignIn}
+      className="flex w-full items-center justify-center gap-3 rounded-lg border border-gray-300 bg-white px-4 py-2.5 text-sm font-medium text-gray-700 shadow-sm transition-colors hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-200 dark:hover:bg-gray-700"
+    >
+      {/* Google "G" logo */}
+      <svg
+        className="h-5 w-5"
+        viewBox="0 0 24 24"
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <path
+          d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92a5.06 5.06 0 0 1-2.2 3.32v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.1z"
+          fill="#4285F4"
+        />
+        <path
+          d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"
+          fill="#34A853"
+        />
+        <path
+          d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"
+          fill="#FBBC05"
+        />
+        <path
+          d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"
+          fill="#EA4335"
+        />
+      </svg>
+      Continue with Google
+    </button>
+  );
+}

package/sails/google-oauth/install.ts

@@ -0,0 +1,252 @@
+/**
+ * Google OAuth Sail Installer
+ *
+ * Adds Google OAuth sign-in via BetterAuth social provider.
+ * Features a full interactive setup wizard that guides the user through
+ * Google Cloud project configuration, credential collection, and installation.
+ *
+ * Usage:
+ *   npx tsx sails/google-oauth/install.ts
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+} from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { input, confirm } from "@inquirer/prompts";
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const SAIL_DIR = dirname(new URL(import.meta.url).pathname);
+const PROJECT_ROOT = resolve(SAIL_DIR, "../..");
+const BACKEND_ROOT = join(PROJECT_ROOT, "packages/backend");
+const FRONTEND_ROOT = join(PROJECT_ROOT, "packages/frontend");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface SailManifest {
+  name: string;
+  displayName: string;
+  version: string;
+  requiredEnvVars: { key: string; description: string }[];
+}
+
+function loadManifest(): SailManifest {
+  return JSON.parse(readFileSync(join(SAIL_DIR, "addon.json"), "utf-8"));
+}
+
+function insertAtMarker(filePath: string, marker: string, code: string): void {
+  if (!existsSync(filePath)) {
+    console.warn(`  Warning: File not found: ${filePath}`);
+    return;
+  }
+  let content = readFileSync(filePath, "utf-8");
+  if (!content.includes(marker)) {
+    console.warn(`  Warning: Marker "${marker}" not found in ${filePath}`);
+    return;
+  }
+  if (content.includes(code.trim())) {
+    console.log(`  Skipped (already present) -> ${filePath}`);
+    return;
+  }
+  content = content.replace(marker, `${marker}\n${code}`);
+  writeFileSync(filePath, content, "utf-8");
+  console.log(`  Modified -> ${filePath}`);
+}
+
+function appendToEnvExample(entries: Record<string, string>): void {
+  const envPath = join(PROJECT_ROOT, ".env.example");
+  if (!existsSync(envPath)) {
+    console.warn("  Warning: .env.example not found");
+    return;
+  }
+  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# Google OAuth\n${lines.join("\n")}\n`;
+    writeFileSync(envPath, content, "utf-8");
+    console.log("  Updated .env.example");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const manifest = loadManifest();
+
+  // -- Step 1: Welcome message -------------------------------------------------
+  console.log("\n------------------------------------------------------------");
+  console.log(`  Google OAuth Sail Installer (v${manifest.version})`);
+  console.log("------------------------------------------------------------");
+  console.log();
+  console.log("  This sail integrates Google sign-in into your project");
+  console.log("  using BetterAuth's social provider system. After installation,");
+  console.log("  users will be able to sign in with their Google account via a");
+  console.log('  "Sign in with Google" button on your login and signup pages.');
+  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: Prerequisites check ---------------------------------------------
+  const hasProject = await confirm({
+    message: "Do you already have a Google Cloud project with OAuth configured?",
+    default: false,
+  });
+
+  if (!hasProject) {
+    console.log();
+    console.log("  Follow these steps to create a Google OAuth client:");
+    console.log();
+    console.log("  1. Go to https://console.cloud.google.com/");
+    console.log("  2. Create a new project (or select an existing one)");
+    console.log("  3. Go to APIs & Services > Credentials");
+    console.log('  4. Click "Create Credentials" > "OAuth client ID"');
+    console.log('  5. Set application type to "Web application"');
+    console.log("  6. Add authorized redirect URI:");
+    console.log("       {BACKEND_URL}/api/auth/callback/google");
+    console.log("     For local development, use:");
+    console.log("       http://localhost:3000/api/auth/callback/google");
+    console.log("  7. Copy the Client ID and Client Secret");
+    console.log();
+
+    await confirm({
+      message: "I have completed the steps above and have my credentials ready",
+      default: false,
+    });
+  }
+
+  const googleClientId = await input({
+    message: "Google OAuth Client ID:",
+    validate: (value) => {
+      if (!value || value.trim().length === 0) return "Client ID is required.";
+      return true;
+    },
+  });
+
+  const googleClientSecret = await input({
+    message: "Google OAuth Client Secret:",
+    validate: (value) => {
+      if (!value || value.trim().length === 0) return "Client Secret is required.";
+      return true;
+    },
+  });
+
+  // -- Step 5: Show summary ----------------------------------------------------
+  console.log();
+  console.log("  Summary of changes:");
+  console.log("  -------------------");
+  console.log("  Files to copy:");
+  console.log("    + packages/frontend/src/components/auth/GoogleButton.tsx");
+  console.log();
+  console.log("  Files to modify:");
+  console.log("    ~ packages/backend/src/auth/index.ts  (add Google provider)");
+  console.log("    ~ packages/backend/src/env.ts         (add env validation)");
+  console.log("    ~ packages/frontend/src/components/auth/LoginForm.tsx");
+  console.log("    ~ packages/frontend/src/components/auth/SignupForm.tsx");
+  console.log("    ~ .env.example");
+  console.log("    ~ .env (if exists)");
+  console.log();
+  console.log("  Environment variables:");
+  console.log(`    GOOGLE_CLIENT_ID=${googleClientId}`);
+  console.log(`    GOOGLE_CLIENT_SECRET=${googleClientSecret.slice(0, 8)}...`);
+  console.log();
+
+  const proceed = await confirm({ message: "Proceed with installation?", default: true });
+  if (!proceed) { console.log("\n  Installation cancelled.\n"); process.exit(0); }
+
+  // -- Step 7: Execute installation --------------------------------------------
+  console.log();
+  console.log("  Installing...");
+  console.log();
+
+  console.log("  Copying files...");
+  const srcFile = join(SAIL_DIR, "files/GoogleButton.tsx");
+  const destDir = join(FRONTEND_ROOT, "src/components/auth");
+  mkdirSync(destDir, { recursive: true });
+  copyFileSync(srcFile, join(destDir, "GoogleButton.tsx"));
+  console.log("  Copied -> src/components/auth/GoogleButton.tsx");
+
+  console.log();
+  console.log("  Modifying backend files...");
+
+  insertAtMarker(
+    join(BACKEND_ROOT, "src/auth/index.ts"),
+    "// [SAIL_SOCIAL_PROVIDERS]",
+    `    google: {\n      clientId: process.env.GOOGLE_CLIENT_ID!,\n      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,\n    },`
+  );
+
+  insertAtMarker(
+    join(BACKEND_ROOT, "src/env.ts"),
+    "// [SAIL_ENV_VARS]",
+    `  GOOGLE_CLIENT_ID: z.string().min(1, "GOOGLE_CLIENT_ID is required"),\n  GOOGLE_CLIENT_SECRET: z.string().min(1, "GOOGLE_CLIENT_SECRET is required"),`
+  );
+
+  console.log();
+  console.log("  Modifying frontend files...");
+
+  for (const form of ["LoginForm.tsx", "SignupForm.tsx"]) {
+    const formPath = join(FRONTEND_ROOT, "src/components/auth", form);
+    insertAtMarker(formPath, "// [SAIL_IMPORTS]", 'import { GoogleButton } from "./GoogleButton";');
+    insertAtMarker(formPath, "{/* [SAIL_SOCIAL_BUTTONS] */}", "            <GoogleButton />");
+  }
+
+  console.log();
+  console.log("  Updating environment files...");
+  appendToEnvExample({ GOOGLE_CLIENT_ID: googleClientId, GOOGLE_CLIENT_SECRET: googleClientSecret });
+
+  const dotEnvPath = join(PROJECT_ROOT, ".env");
+  if (existsSync(dotEnvPath)) {
+    let dotEnv = readFileSync(dotEnvPath, "utf-8");
+    if (!dotEnv.includes("GOOGLE_CLIENT_ID")) {
+      dotEnv += `\n# Google OAuth\nGOOGLE_CLIENT_ID=${googleClientId}\nGOOGLE_CLIENT_SECRET=${googleClientSecret}\n`;
+      writeFileSync(dotEnvPath, dotEnv, "utf-8");
+      console.log("  Updated .env");
+    }
+  }
+
+  console.log();
+  console.log("------------------------------------------------------------");
+  console.log("  Google OAuth installed successfully!");
+  console.log("------------------------------------------------------------");
+  console.log();
+  console.log("  Next steps:");
+  console.log();
+  console.log("  1. Verify your Google Cloud Console settings:");
+  console.log("     https://console.cloud.google.com/apis/credentials");
+  console.log();
+  console.log("  2. Ensure these redirect URIs are configured:");
+  console.log("     Development: http://localhost:3000/api/auth/callback/google");
+  console.log("     Production:  https://yourdomain.com/api/auth/callback/google");
+  console.log();
+  console.log("  3. Restart your dev server:");
+  console.log("     npm run dev");
+  console.log();
+  console.log("  Testing:");
+  console.log('  - Visit your login page and click "Sign in with Google"');
+  console.log("  - You should be redirected to Google's consent screen");
+  console.log("  - After authorizing, you should be redirected back and signed in");
+  console.log("  - Check the users table in your database for the new account");
+  console.log();
+}
+
+main().catch((err) => { console.error("Installation failed:", err); process.exit(1); });

package/sails/i18n/README.md

@@ -0,0 +1,193 @@
+# Internationalization (i18n) Sail
+
+Adds multi-language support to your keel application using i18next, react-i18next, and automatic browser language detection.
+
+## Features
+
+- i18next translation framework
+- react-i18next for seamless React integration
+- Automatic browser language detection (via `i18next-browser-languagedetector`)
+- Language switcher dropdown component (dark Keel theme)
+- Translation files for English, German, French, and Spanish
+- Language preference persisted in localStorage
+
+## Installation
+
+```bash
+npx tsx sails/i18n/install.ts
+```
+
+The installer will prompt you to select which languages to include and will configure everything automatically.
+
+## Usage
+
+### Using Translations in Components
+
+```tsx
+import { useTranslation } from "react-i18next";
+
+function MyComponent() {
+  const { t } = useTranslation();
+
+  return (
+    <div>
+      <h1>{t("nav.home")}</h1>
+      <p>{t("common.loading")}</p>
+      <button>{t("common.save")}</button>
+    </div>
+  );
+}
+```
+
+### Using the Language Hook
+
+```tsx
+import { useLanguage } from "@/hooks/useLanguage";
+
+function SettingsPage() {
+  const { currentLanguage, changeLanguage, availableLanguages } = useLanguage();
+
+  return (
+    <select
+      value={currentLanguage}
+      onChange={(e) => changeLanguage(e.target.value)}
+    >
+      {availableLanguages.map((lang) => (
+        <option key={lang.code} value={lang.code}>
+          {lang.label}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+### Translation Keys with Interpolation
+
+```json
+{
+  "greeting": "Hello, {{name}}!"
+}
+```
+
+```tsx
+t("greeting", { name: user.name })
+```
+
+### Pluralization
+
+```json
+{
+  "items_one": "{{count}} item",
+  "items_other": "{{count}} items"
+}
+```
+
+```tsx
+t("items", { count: 5 })  // "5 items"
+t("items", { count: 1 })  // "1 item"
+```
+
+## Adding a New Language
+
+1. Create the locale file:
+
+```bash
+mkdir -p packages/frontend/src/locales/ja
+```
+
+2. Create `packages/frontend/src/locales/ja/common.json` with all translation keys (copy from `en/common.json` as a template).
+
+3. Update `packages/frontend/src/lib/i18n.ts`:
+
+```ts
+import jaCommon from "@/locales/ja/common.json";
+
+const resources = {
+  en: { common: enCommon },
+  de: { common: deCommon },
+  ja: { common: jaCommon },  // Add this
+};
+```
+
+4. Update `packages/frontend/src/hooks/useLanguage.ts`:
+
+```ts
+const availableLanguages: Language[] = [
+  { code: "en", label: "English" },
+  { code: "de", label: "Deutsch" },
+  { code: "ja", label: "Japanese" },  // Add this
+];
+```
+
+## Adding New Translation Namespaces
+
+For larger applications, split translations into namespaces (e.g., per page):
+
+1. Create `packages/frontend/src/locales/en/dashboard.json`
+2. Import in `i18n.ts` and add to resources:
+
+```ts
+import enDashboard from "@/locales/en/dashboard.json";
+
+const resources = {
+  en: { common: enCommon, dashboard: enDashboard },
+  // ...
+};
+```
+
+3. Update the `ns` array in `i18n.init()`:
+
+```ts
+ns: ["common", "dashboard"],
+```
+
+4. Use in components:
+
+```tsx
+const { t } = useTranslation("dashboard");
+return <h1>{t("title")}</h1>;
+```
+
+## Language Detection
+
+The language detector checks in this order:
+
+1. `localStorage` key `i18nextLng`
+2. Browser navigator language
+3. HTML `lang` attribute
+
+The selected language is automatically persisted to `localStorage`.
+
+## Architecture
+
+| File | Purpose |
+|------|---------|
+| `src/lib/i18n.ts` | i18next initialization and configuration |
+| `src/locales/<lang>/common.json` | Translation strings per language |
+| `src/hooks/useLanguage.ts` | Hook for language switching |
+| `src/components/LanguageSwitcher.tsx` | Dropdown UI component |
+
+## Configuration
+
+### Changing the Default Language
+
+Edit `src/lib/i18n.ts`:
+
+```ts
+fallbackLng: "de",  // Change from "en" to desired default
+```
+
+### Disabling Language Detection
+
+Remove the `LanguageDetector` plugin from `i18n.ts`:
+
+```ts
+i18n
+  // .use(LanguageDetector)  // Remove this line
+  .use(initReactI18next)
+  .init({
+    lng: "en",  // Set a fixed language
+    // ...
+  });
+```

package/sails/i18n/addon.json

@@ -0,0 +1,30 @@
+{
+  "name": "i18n",
+  "displayName": "Internationalization (i18n)",
+  "description": "Multi-language support with i18next, react-i18next, and automatic language detection",
+  "version": "1.0.0",
+  "compatibility": ">=1.0.0",
+  "requiredEnvVars": [],
+  "dependencies": {
+    "backend": {},
+    "frontend": {
+      "i18next": "^24.0.0",
+      "react-i18next": "^15.0.0",
+      "i18next-browser-languagedetector": "^8.0.0"
+    }
+  },
+  "modifies": {
+    "backend": [],
+    "frontend": ["src/main.tsx", "src/components/layout/Header.tsx"]
+  },
+  "adds": {
+    "backend": [],
+    "frontend": [
+      "src/lib/i18n.ts",
+      "src/locales/en/common.json",
+      "src/locales/de/common.json",
+      "src/hooks/useLanguage.ts",
+      "src/components/LanguageSwitcher.tsx"
+    ]
+  }
+}