clefbase 2.0.0 → 2.0.2

package/dist/cli-src/cli/commands/init.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runInit = runInit;
+exports.scaffoldFunctions = scaffoldFunctions;
 exports.scaffoldLib = scaffoldLib;
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
@@ -48,18 +49,10 @@ async function runInit(cwd = process.cwd()) {
             mask: "●",
             validate: (v) => v.trim().length > 0 || "Required",
         }]);
-    const { adminSecret } = await inquirer_1.default.prompt([{
-            type: "password",
-            name: "adminSecret",
-            message: "Admin Secret  (x-admin-secret, needed for hosting)",
-            mask: "●",
-            validate: (v) => v.trim().length > 0 || "Required",
-        }]);
     const cfg = {
         serverUrl: serverUrl.replace(/\/+$/, ""),
         projectId: projectId.trim(),
         apiKey: apiKey.trim(),
-        adminSecret: adminSecret.trim(),
         services: { database: false, auth: false, storage: false, hosting: false, functions: false },
     };
     // ── Step 2: Connection test ───────────────────────────────────────────────
@@ -96,11 +89,16 @@ async function runInit(cwd = process.cwd()) {
     if (cfg.services.hosting) {
         await setupHosting(cfg, cwd);
     }
-    // ── Step 5: Write root config files ──────────────────────────────────────
+    // ── Step 5: Functions setup ───────────────────────────────────────────────
+    let functionsRuntime;
+    if (cfg.services.functions) {
+        functionsRuntime = await setupFunctions(cfg, cwd);
+    }
+    // ── Step 6: Write root config files ──────────────────────────────────────
     const configPath = (0, config_1.saveConfig)(cfg, cwd);
     (0, config_1.ensureGitignore)(cwd);
     (0, config_1.writeEnvExample)(cfg, cwd);
-    // ── Step 6: Scaffold src/lib ──────────────────────────────────────────────
+    // ── Step 7: Scaffold src/lib ──────────────────────────────────────────────
     const libResult = scaffoldLib(cfg, cwd);
     // ── Done ──────────────────────────────────────────────────────────────────
     console.log();
@@ -113,9 +111,602 @@ async function runInit(cwd = process.cwd()) {
         console.log(chalk_1.default.dim(`  Lib config:    ${libResult.configCopy}`));
         console.log(chalk_1.default.dim(`  Lib entry:     ${libResult.libFile}`));
     }
+    if (cfg.services.functions) {
+        console.log(chalk_1.default.dim(`  Functions:     functions/  (${functionsRuntime ?? "node"})`));
+        console.log(chalk_1.default.dim(`                 run: node functions/deploy.mjs`));
+    }
     console.log();
     printUsageHint(cfg);
 }
+// ─── Functions scaffolding ────────────────────────────────────────────────────
+/**
+ * Interactively scaffold the `functions/` directory.
+ * Returns the chosen runtime(s) so the done-summary can print it.
+ */
+async function setupFunctions(cfg, cwd) {
+    console.log();
+    console.log(chalk_1.default.bold("  Functions"));
+    console.log();
+    const { runtime } = await inquirer_1.default.prompt([{
+            type: "list",
+            name: "runtime",
+            message: "Default functions runtime",
+            choices: [
+                { name: "Node.js / TypeScript  (recommended)", value: "node" },
+                { name: "Python 3", value: "python" },
+                { name: "Both  (create examples for each)", value: "both" },
+            ],
+            default: "node",
+        }]);
+    const scaffoldResult = scaffoldFunctions(cfg, cwd, runtime);
+    const sp = (0, ora_1.default)("Creating functions/ folder…").start();
+    sp.succeed(chalk_1.default.green(`functions/ created  (${scaffoldResult.files.length} file${scaffoldResult.files.length !== 1 ? "s" : ""})`));
+    return runtime;
+}
+/**
+ * Write the full `functions/` directory scaffold.
+ * Safe to call multiple times — existing files are NOT overwritten.
+ */
+function scaffoldFunctions(cfg, cwd = process.cwd(), runtime = "node") {
+    const dir = path_1.default.join(cwd, "functions");
+    const files = [];
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    const write = (rel, content) => {
+        const abs = path_1.default.join(dir, rel);
+        fs_1.default.mkdirSync(path_1.default.dirname(abs), { recursive: true });
+        if (!fs_1.default.existsSync(abs)) {
+            fs_1.default.writeFileSync(abs, content);
+            files.push(path_1.default.join("functions", rel));
+        }
+    };
+    const wantNode = runtime === "node" || runtime === "both";
+    const wantPython = runtime === "python" || runtime === "both";
+    // ── README ────────────────────────────────────────────────────────────────
+    write("README.md", buildFunctionsReadme(cfg, runtime));
+    // ── .env ──────────────────────────────────────────────────────────────────
+    write(".env", buildFunctionsEnv(cfg));
+    write(".env.example", buildFunctionsEnvExample(cfg));
+    // ── .gitignore ────────────────────────────────────────────────────────────
+    write(".gitignore", FUNCTIONS_GITIGNORE);
+    // ── Node / TypeScript ─────────────────────────────────────────────────────
+    if (wantNode) {
+        write("src/hello.ts", NODE_HELLO_TS);
+        write("src/onUserCreate.ts", NODE_ON_USER_CREATE_TS);
+        write("src/scheduled.ts", NODE_SCHEDULED_TS);
+        write("tsconfig.json", FUNCTIONS_TSCONFIG);
+    }
+    // ── Python ────────────────────────────────────────────────────────────────
+    if (wantPython) {
+        write("python/hello.py", PYTHON_HELLO_PY);
+        write("python/on_user_create.py", PYTHON_ON_USER_CREATE_PY);
+        write("python/scheduled.py", PYTHON_SCHEDULED_PY);
+        write("python/requirements.txt", PYTHON_REQUIREMENTS_TXT);
+    }
+    // ── package.json (npm run deploy, npm run deploy:all) ───────────────────────
+    write("package.json", buildFunctionsPackageJson(cfg, runtime));
+    // ── deploy script (cross-platform Node) ──────────────────────────────────
+    write("deploy.mjs", buildDeployMjs(cfg, runtime));
+    return { dir, files };
+}
+// ─── File templates ───────────────────────────────────────────────────────────
+function buildFunctionsReadme(cfg, runtime) {
+    const wantNode = runtime === "node" || runtime === "both";
+    const wantPython = runtime === "python" || runtime === "both";
+    const baseUrl = cfg.serverUrl.replace(/\/+$/, "");
+    return `# Clefbase Functions
+
+Serverless functions for project \`${cfg.projectId}\`.
+
+Functions run on the Clefbase server and are triggered by HTTP calls,
+database events, auth events, storage events, or a cron schedule.
+No infrastructure to manage — just write code and deploy.
+
+---
+
+## Quick start
+${wantNode ? `
+### Node.js / TypeScript
+
+\`\`\`bash
+# 1. Install the Clefbase CLI (if not already)
+npm install -g clefbase
+
+# 2. Deploy a function
+clefbase functions:deploy -f src/hello.ts --name hello --trigger http
+
+# 3. Call it
+clefbase functions:call hello -d '{"name":"World"}'
+# or via HTTP
+curl -X POST ${baseUrl}/functions/call/hello \\
+  -H "x-cfx-key: <YOUR_API_KEY>" \\
+  -H "Content-Type: application/json" \\
+  -d '{"data":{"name":"World"}}'
+\`\`\`
+` : ""}${wantPython ? `
+### Python 3
+
+\`\`\`bash
+# Deploy a Python function
+clefbase functions:deploy -f python/hello.py --name hello-py --runtime python --trigger http
+
+# Call it
+clefbase functions:call hello-py -d '{"name":"World"}'
+\`\`\`
+` : ""}
+---
+
+## Writing functions
+
+Every function must export a single async **\`handler\`** (or the name you
+pass as \`--entry\`).  It receives one argument — a **\`FunctionContext\`** — and
+can return any JSON-serialisable value.
+
+### FunctionContext shape
+
+\`\`\`ts
+interface FunctionContext {
+  /** Payload supplied by the caller (HTTP) or the event (triggers). */
+  data: unknown;
+
+  /** Populated when the caller includes a valid auth token. */
+  auth?: {
+    uid:      string;
+    email?:   string;
+    metadata: Record<string, unknown>;
+  };
+
+  /** Describes what fired the function. */
+  trigger: {
+    type:      string;        // "http" | "schedule" | "onDocumentCreate" | …
+    timestamp: string;        // ISO 8601
+    document?: unknown;       // populated for document triggers
+    before?:   unknown;       // populated for onDocumentUpdate / onDocumentWrite
+    after?:    unknown;       // populated for onDocumentUpdate / onDocumentWrite
+    user?:     unknown;       // populated for onUserCreate / onUserDelete
+    file?:     unknown;       // populated for onFileUpload / onFileDelete
+  };
+
+  /** Key-value env vars you passed at deploy time. */
+  env: Record<string, string>;
+}
+\`\`\`
+
+### Trigger types
+
+| Type | When it fires |
+|------|---------------|
+| \`http\` | \`POST /functions/call/:name\` |
+| \`schedule\` | Cron timer (e.g. \`0 * * * *\` = every hour) |
+| \`onDocumentCreate\` | A document is created in the watched collection |
+| \`onDocumentUpdate\` | A document is updated |
+| \`onDocumentDelete\` | A document is deleted |
+| \`onDocumentWrite\` | Any of create / update / delete |
+| \`onUserCreate\` | A new user account is created |
+| \`onUserDelete\` | A user account is deleted |
+| \`onFileUpload\` | A file is uploaded to Storage |
+| \`onFileDelete\` | A file is deleted from Storage |
+
+---
+
+## Deployment examples
+
+\`\`\`bash
+# HTTP function
+clefbase functions:deploy -f src/hello.ts --trigger http
+
+# Scheduled (every day at midnight UTC)
+clefbase functions:deploy -f src/scheduled.ts --trigger schedule --cron "0 0 * * *"
+
+# Document trigger (fires on every new "orders" document)
+clefbase functions:deploy -f src/onOrder.ts --trigger onDocumentCreate --collection orders
+
+# With env vars and a custom timeout
+clefbase functions:deploy -f src/sendEmail.ts \\
+  --trigger http \\
+  --env SENDGRID_KEY=SG.xxx \\
+  --timeout 15000
+
+# Use the deploy script in this folder (deploys everything at once)
+node deploy.mjs
+\`\`\`
+
+---
+
+## Calling HTTP functions
+
+### From the Clefbase SDK
+
+\`\`\`ts
+import { getFunctions, httpsCallable } from "clefbase";
+// or: import { fns } from "@lib/clefBase";
+
+const greet = httpsCallable<{ name: string }, { message: string }>(fns, "hello");
+const { data, durationMs } = await greet({ name: "Alice" });
+console.log(data.message);   // "Hello, Alice!"
+console.log(durationMs);     // e.g. 42
+\`\`\`
+
+### Auth-aware calls
+
+\`\`\`ts
+import { getAuth, setAuthToken } from "clefbase";
+
+const { token } = await getAuth(app).signIn("alice@example.com", "password");
+setAuthToken(app, token);
+
+// ctx.auth.uid and ctx.auth.email are now available inside the function
+const { data } = await callFunction(fns, "getProfile");
+\`\`\`
+
+### Raw HTTP (no SDK)
+
+\`\`\`bash
+curl -X POST ${baseUrl}/functions/call/<functionName> \\
+  -H "x-cfx-key: <YOUR_API_KEY>" \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer <USER_JWT>"   # optional auth
+  -d '{"data": { "key": "value" }}'
+\`\`\`
+
+---
+
+## Viewing logs
+
+\`\`\`bash
+# Last 20 executions
+clefbase functions:logs hello
+
+# Last 50
+clefbase functions:logs hello -l 50
+
+# All functions
+clefbase functions:list
+\`\`\`
+
+---
+
+## Managing functions
+
+\`\`\`bash
+clefbase functions:list                  # see all deployed functions
+clefbase functions:delete oldFunction    # delete (prompts for confirmation)
+clefbase functions:delete oldFunction -y # delete without confirmation
+\`\`\`
+
+---
+
+## Environment variables
+
+Secrets and config for your functions live in \`functions/.env\`.
+They are **never** committed to git (already in \`.gitignore\`).
+
+Pass them at deploy time with \`--env KEY=VALUE\` or edit \`deploy.sh\`
+to read them automatically from \`.env\`.
+
+---
+
+## Project info
+
+| Key | Value |
+|-----|-------|
+| Project ID | \`${cfg.projectId}\` |
+| Server | \`${baseUrl}\` |
+| Functions base URL | \`${baseUrl}/functions\` |
+`;
+}
+function buildFunctionsEnv(cfg) {
+    return `# Clefbase Functions — secrets for this project
+# This file is git-ignored. Do NOT commit it.
+# Copy values from your Clefbase dashboard.
+
+CLEFBASE_SERVER_URL=${cfg.serverUrl}
+CLEFBASE_PROJECT_ID=${cfg.projectId}
+CLEFBASE_API_KEY=${cfg.apiKey}
+
+# Add your own secrets below:
+# SENDGRID_API_KEY=
+# STRIPE_SECRET_KEY=
+# DATABASE_URL=
+`;
+}
+function buildFunctionsEnvExample(cfg) {
+    return `# Clefbase Functions — environment variable template
+# Copy this to .env and fill in your values.
+
+CLEFBASE_SERVER_URL=${cfg.serverUrl}
+CLEFBASE_PROJECT_ID=${cfg.projectId}
+CLEFBASE_API_KEY=your_api_key_here
+
+# Add your own secrets below:
+# SENDGRID_API_KEY=
+# STRIPE_SECRET_KEY=
+# DATABASE_URL=
+`;
+}
+const FUNCTIONS_GITIGNORE = `# Dependencies
+node_modules/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+
+# Secrets — never commit these
+.env
+
+# Build artefacts
+dist/
+*.js.map
+`;
+const FUNCTIONS_TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+`;
+// ─── Node / TypeScript examples ───────────────────────────────────────────────
+const NODE_HELLO_TS = `/**
+ * hello.ts — HTTP-triggered "hello world" function.
+ *
+ * Deploy:
+ *   clefbase functions:deploy -f src/hello.ts --name hello --trigger http
+ *
+ * Call:
+ *   clefbase functions:call hello -d '{"name":"World"}'
+ */
+
+import type { FunctionContext } from "clefbase";
+
+interface Input  { name?: string }
+interface Output { message: string; timestamp: string }
+
+export async function handler(ctx: FunctionContext): Promise<Output> {
+  const { name = "World" } = (ctx.data ?? {}) as Input;
+
+  return {
+    message:   \`Hello, \${name}!\`,
+    timestamp: ctx.trigger.timestamp,
+  };
+}
+`;
+const NODE_ON_USER_CREATE_TS = `/**
+ * onUserCreate.ts — fires whenever a new user signs up.
+ *
+ * Deploy:
+ *   clefbase functions:deploy -f src/onUserCreate.ts \\
+ *     --name onUserCreate --trigger onUserCreate
+ *
+ * ctx.trigger.user contains the new user's profile.
+ */
+
+import type { FunctionContext } from "clefbase";
+
+export async function handler(ctx: FunctionContext): Promise<void> {
+  const user = ctx.trigger.user as {
+    uid:      string;
+    email?:   string;
+    metadata: Record<string, unknown>;
+  } | undefined;
+
+  if (!user) return;
+
+  console.log(\`New user: \${user.uid}  email: \${user.email ?? "—"}\`);
+
+  // Example: send a welcome email, add to a mailing list, seed default data…
+  // const emailKey = ctx.env["SENDGRID_API_KEY"];
+}
+`;
+const NODE_SCHEDULED_TS = `/**
+ * scheduled.ts — runs on a cron schedule.
+ *
+ * Deploy (every day at midnight UTC):
+ *   clefbase functions:deploy -f src/scheduled.ts \\
+ *     --name dailyCleanup --trigger schedule --cron "0 0 * * *"
+ *
+ * Common cron expressions:
+ *   "* * * * *"    every minute
+ *   "0 * * * *"    every hour
+ *   "0 9 * * 1"    every Monday at 09:00 UTC
+ */
+
+import type { FunctionContext } from "clefbase";
+
+export async function handler(ctx: FunctionContext): Promise<{ cleaned: number }> {
+  console.log("Running scheduled cleanup at", ctx.trigger.timestamp);
+
+  // TODO: your scheduled work here
+  const cleaned = 0;
+
+  return { cleaned };
+}
+`;
+// ─── Python examples ──────────────────────────────────────────────────────────
+const PYTHON_HELLO_PY = `"""
+hello.py — HTTP-triggered "hello world" function.
+
+Deploy:
+    clefbase functions:deploy -f python/hello.py \\
+        --name hello-py --runtime python --trigger http
+
+Call:
+    clefbase functions:call hello-py -d '{"name":"World"}'
+"""
+
+
+async def handler(ctx):
+    """
+    ctx.data       — payload from the caller
+    ctx.auth       — populated when a valid auth token is included
+    ctx.trigger    — describes what fired this function
+    ctx.env        — env vars you passed at deploy time
+    """
+    data = ctx.get("data") or {}
+    name = data.get("name", "World")
+
+    return {
+        "message":   f"Hello, {name}!",
+        "timestamp": ctx["trigger"]["timestamp"],
+    }
+`;
+const PYTHON_ON_USER_CREATE_PY = `"""
+on_user_create.py — fires whenever a new user signs up.
+
+Deploy:
+    clefbase functions:deploy -f python/on_user_create.py \\
+        --name onUserCreate-py --runtime python --trigger onUserCreate
+"""
+
+
+async def handler(ctx):
+    user = (ctx.get("trigger") or {}).get("user") or {}
+
+    uid   = user.get("uid", "unknown")
+    email = user.get("email", "—")
+
+    print(f"New user: {uid}  email: {email}")
+
+    # Example: send a welcome email, seed default data, etc.
+    # sendgrid_key = ctx["env"].get("SENDGRID_API_KEY")
+`;
+const PYTHON_SCHEDULED_PY = `"""
+scheduled.py — runs on a cron schedule.
+
+Deploy (every day at midnight UTC):
+    clefbase functions:deploy -f python/scheduled.py \\
+        --name dailyCleanup-py --runtime python \\
+        --trigger schedule --cron "0 0 * * *"
+"""
+
+
+async def handler(ctx):
+    print("Running scheduled cleanup at", ctx["trigger"]["timestamp"])
+
+    # TODO: your scheduled work here
+    cleaned = 0
+
+    return {"cleaned": cleaned}
+`;
+const PYTHON_REQUIREMENTS_TXT = `# Add your Python dependencies here.
+# They are NOT automatically installed on the server — include only stdlib
+# and packages already available in the Clefbase Python runtime.
+#
+# For heavier workloads, consider the Node.js runtime and npm packages.
+#
+# httpx>=0.27
+# pydantic>=2.0
+`;
+// ─── deploy.mjs (cross-platform — runs anywhere Node.js is installed) ────────
+function buildDeployMjs(cfg, runtime) {
+    const wantNode = runtime === "node" || runtime === "both";
+    const wantPython = runtime === "python" || runtime === "both";
+    const fns = [];
+    if (wantNode) {
+        fns.push({ name: "hello", file: "src/hello.ts", runtime: "node", trigger: "http" }, { name: "onUserCreate", file: "src/onUserCreate.ts", runtime: "node", trigger: "onUserCreate" }, { name: "dailyCleanup", file: "src/scheduled.ts", runtime: "node", trigger: "schedule", cron: "0 0 * * *" });
+    }
+    if (wantPython) {
+        fns.push({ name: "hello-py", file: "python/hello.py", runtime: "python", trigger: "http" }, { name: "onUserCreate-py", file: "python/on_user_create.py", runtime: "python", trigger: "onUserCreate" }, { name: "dailyCleanup-py", file: "python/scheduled.py", runtime: "python", trigger: "schedule", cron: "0 0 * * *" });
+    }
+    const fnJson = JSON.stringify(fns, null, 2);
+    return `#!/usr/bin/env node
+// deploy.mjs — deploy all functions in this folder to Clefbase
+// Generated by \`clefbase init\`  •  project: ${cfg.projectId}
+//
+// Usage (any OS):  node deploy.mjs
+//
+// Node.js 18+ required (uses built-in fetch + fs).
+// No extra dependencies — just the Clefbase CLI on your PATH.
+
+import { execSync }  from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join }  from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ── Load .env ─────────────────────────────────────────────────────────────────
+
+const envPath = join(__dirname, ".env");
+if (existsSync(envPath)) {
+  for (const line of readFileSync(envPath, "utf8").split("\\n")) {
+    const match = line.match(/^\\s*([^#][^=]*)=(.*)$/);
+    if (match) process.env[match[1].trim()] = match[2].trim();
+  }
+}
+
+// ── Functions to deploy ───────────────────────────────────────────────────────
+
+const functions = ${fnJson};
+
+// ── Deploy ────────────────────────────────────────────────────────────────────
+
+let passed = 0;
+let failed = 0;
+
+for (const fn of functions) {
+  const args = [
+    \`--name     \${fn.name}\`,
+    \`--file     \${fn.file}\`,
+    \`--runtime  \${fn.runtime}\`,
+    \`--trigger  \${fn.trigger}\`,
+    fn.cron       ? \`--cron       "\${fn.cron}"\`       : "",
+    fn.collection ? \`--collection "\${fn.collection}"\` : "",
+  ].filter(Boolean).join(" ");
+
+  console.log(\`\\n→ Deploying "\${fn.name}"…\`);
+  try {
+    execSync(\`clefbase functions:deploy \${args}\`, { stdio: "inherit", cwd: __dirname });
+    passed++;
+  } catch {
+    console.error(\`  ✗ "\${fn.name}" failed\`);
+    failed++;
+  }
+}
+
+// ── Summary ───────────────────────────────────────────────────────────────────
+
+console.log(\`\\n\${passed} deployed, \${failed} failed — project: ${cfg.projectId}\\n\`);
+if (failed > 0) process.exit(1);
+`;
+}
+// ─── functions/package.json ───────────────────────────────────────────────────
+function buildFunctionsPackageJson(cfg, runtime) {
+    const wantNode = runtime === "node" || runtime === "both";
+    const scripts = {
+        "deploy:all": "node deploy.mjs",
+    };
+    // Individual per-function shortcuts — only Node ones get their own script
+    // because Python files are plain paths with no compile step either way.
+    if (wantNode) {
+        scripts["deploy:hello"] = "clefbase functions:deploy -f src/hello.ts        --name hello        --runtime node   --trigger http";
+        scripts["deploy:onUserCreate"] = "clefbase functions:deploy -f src/onUserCreate.ts --name onUserCreate --runtime node   --trigger onUserCreate";
+        scripts["deploy:scheduled"] = "clefbase functions:deploy -f src/scheduled.ts    --name dailyCleanup --runtime node   --trigger schedule --cron \"0 0 * * *\"";
+    }
+    if (runtime === "python" || runtime === "both") {
+        scripts["deploy:hello-py"] = "clefbase functions:deploy -f python/hello.py           --name hello-py        --runtime python --trigger http";
+        scripts["deploy:onUserCreate-py"] = "clefbase functions:deploy -f python/on_user_create.py  --name onUserCreate-py --runtime python --trigger onUserCreate";
+        scripts["deploy:scheduled-py"] = "clefbase functions:deploy -f python/scheduled.py        --name dailyCleanup-py --runtime python --trigger schedule --cron \"0 0 * * *\"";
+    }
+    const pkg = {
+        name: `${cfg.projectId}-functions`,
+        version: "1.0.0",
+        description: `Clefbase Functions for project ${cfg.projectId}`,
+        private: true,
+        type: "module",
+        scripts,
+    };
+    return JSON.stringify(pkg, null, 2) + "\n";
+}
 /**
  * Writes two files into `<cwd>/src/lib/`:
  *   • clefbase.json  — a copy of the project config (adminSecret stripped)
@@ -173,7 +764,18 @@ function buildLibTs(cfg) {
         ` *`,
         ` * Usage:`,
         ...(database ? [` *   import { db } from "@lib/clefBase";`] : []),
-        ...(auth ? [` *   import { auth } from "@lib/clefBase";`] : []),
+        ...(auth ? [
+            ` *   import { auth } from "@lib/clefBase";`,
+            ` *`,
+            ` *   // Email / password`,
+            ` *   const { user } = await auth.signIn("alice@example.com", "pass");`,
+            ` *`,
+            ` *   // Google sign-in — add this to your root component / entry point:`,
+            ` *   await auth.handleGatewayCallback(); // handles ?cfx_token= on return`,
+            ` *`,
+            ` *   // On sign-in button click:`,
+            ` *   await auth.signInWithGateway("google");`,
+        ] : []),
         ...(storage ? [` *   import { storage } from "@lib/clefBase";`] : []),
         ...(fns ? [
             ` *   import { fns, httpsCallable } from "@lib/clefBase";`,
@@ -192,10 +794,9 @@ function buildLibTs(cfg) {
         `// ─── App ─────────────────────────────────────────────────────────────────────`,
         ``,
         `const app = initClefbase({`,
-        `  serverUrl:   config.serverUrl,`,
-        `  projectId:   config.projectId,`,
-        `  apiKey:      config.apiKey,`,
-        `  adminSecret: "",`,
+        `  serverUrl: config.serverUrl,`,
+        `  projectId: config.projectId,`,
+        `  apiKey:    config.apiKey,`,
         `});`,
         ``,
     ];
@@ -214,6 +815,20 @@ function buildLibTs(cfg) {
         lines.push(`/** Clefbase Auth — sign up, sign in, manage sessions. */`);
         lines.push(`export const auth: Auth = getAuth(app);`);
         lines.push("");
+        lines.push(`/**`);
+        lines.push(` * Call this once on every page load (before rendering your UI).`);
+        lines.push(` * Detects the ?cfx_token= param the gateway appends after OAuth,`);
+        lines.push(` * saves the session, and cleans the URL.`);
+        lines.push(` *`);
+        lines.push(` * @example`);
+        lines.push(` * // React / Next.js — in your root layout or _app.tsx:`);
+        lines.push(` * useEffect(() => { auth.handleGatewayCallback(); }, []);`);
+        lines.push(` *`);
+        lines.push(` * // Vanilla JS — at the top of your entry point:`);
+        lines.push(` * await auth.handleGatewayCallback();`);
+        lines.push(` */`);
+        lines.push(`export { auth };`);
+        lines.push("");
     }
     if (storage) {
         lines.push(`/** Clefbase Storage — upload and manage files. */`);
@@ -257,6 +872,7 @@ async function setupHosting(cfg, cwd) {
     }
     let siteId = "";
     let siteName = "";
+    let previewUrl = "";
     if (existing.length > 0) {
         const choices = [
             ...existing.map(s => ({ name: `${s.name}  ${chalk_1.default.dim(s.id)}`, value: s.id })),
@@ -269,8 +885,10 @@ async function setupHosting(cfg, cwd) {
                 choices,
             }]);
         if (chosen !== "__new__") {
+            const found = existing.find(s => s.id === chosen);
             siteId = chosen;
-            siteName = existing.find(s => s.id === chosen)?.name ?? chosen;
+            siteName = found?.name ?? chosen;
+            previewUrl = found?.previewUrl ?? "";
         }
     }
     if (!siteId) {
@@ -285,6 +903,7 @@ async function setupHosting(cfg, cwd) {
             const site = await (0, api_1.createSite)(cfg, newName.trim());
             siteId = site.id;
             siteName = site.name;
+            previewUrl = site.previewUrl ?? "";
             s.succeed(chalk_1.default.green(`Created "${siteName}"  ${chalk_1.default.dim(siteId)}`));
         }
         catch (err) {
@@ -309,6 +928,7 @@ async function setupHosting(cfg, cwd) {
     cfg.hosting = {
         siteId,
         siteName,
+        previewUrl,
         distDir: distDir.trim(),
         entrypoint: entrypoint.trim(),
     };
@@ -346,6 +966,8 @@ function printUsageHint(cfg) {
     if (cfg.services.auth) {
         console.log();
         console.log(chalk_1.default.cyan(`  const { user } = await auth.signIn("email", "pass");`));
+        console.log(chalk_1.default.cyan(`  await auth.signInWithGateway("google"); // redirects to auth.cleforyx.com`));
+        console.log(chalk_1.default.cyan(`  await auth.handleGatewayCallback();     // call on every page load`));
     }
     if (cfg.services.storage) {
         console.log();
@@ -354,12 +976,15 @@ function printUsageHint(cfg) {
     if (cfg.services.functions) {
         console.log();
         console.log(chalk_1.default.bold("  Functions:"));
-        console.log(chalk_1.default.cyan(`  // Deploy from a file`));
-        console.log(chalk_1.default.cyan(`  $ clefbase functions:deploy -f ./src/functions/hello.ts`));
+        console.log(chalk_1.default.cyan(`  # Edit your functions in functions/src/`));
+        console.log(chalk_1.default.cyan(`  $ clefbase functions:deploy -f functions/src/hello.ts`));
         console.log();
-        console.log(chalk_1.default.cyan(`  // Call from your app`));
+        console.log(chalk_1.default.cyan(`  # Call from your app`));
         console.log(chalk_1.default.cyan(`  const greet = httpsCallable(fns, "greetUser");`));
         console.log(chalk_1.default.cyan(`  const { data } = await greet({ name: "Alice" });`));
+        console.log();
+        console.log(chalk_1.default.dim(`  Full guide: functions/README.md`));
+        console.log(chalk_1.default.dim(`  Deploy all: node functions/deploy.mjs`));
     }
     if (cfg.services.hosting && cfg.hosting) {
         console.log();