create-handover 0.1.1

package/README.md

@@ -0,0 +1,61 @@
+# create-handover
+
+Scaffold a new [Handover](https://handover.carney.dev) client site — a white-label admin boilerplate that connects to the Handover CMS platform via API key.
+
+## Usage
+
+```bash
+pnpm create handoverhq@latest
+# or
+npx create-handover@latest
+# or with a target directory:
+npx create-handover@latest my-client-site
+```
+
+The CLI will prompt you for:
+- **Project directory name** — where to scaffold the project
+- **tRPC placeholder** — optional tRPC env stub (y/N)
+- **Theme mode** — light or dark default
+
+## What you get
+
+A production-ready Next.js admin template pre-wired to the Handover SDK:
+
+- `/admin` — password-protected content & media management dashboard
+- `/admin/login` — authentication gate
+- White-label branding surface via `lib/branding.ts` (name, logo, colors, copy)
+- Storage-aware image upload with progress feedback
+- Lock-state (`HANDOVER_LOCKED`) handling built in
+
+## Setup after scaffolding
+
+```bash
+cd my-client-site
+pnpm install
+cp .env.example .env.local
+# Fill in your API key and URL from the Handover dashboard
+pnpm dev
+```
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `NEXT_PUBLIC_HANDOVER_API_URL` | Your Handover platform URL |
+| `NEXT_PUBLIC_HANDOVER_API_KEY` | Project API key (`ho_live_*`) from the dashboard |
+| `NEXT_PUBLIC_SITE_NAME` | Display name for the admin UI (optional) |
+
+## Options
+
+```
+--template-dir <path>   Use a custom local template instead of the bundled one
+```
+
+```
+HANDOVER_TEMPLATE_DIR=/path/to/template   Env-based template override
+```
+
+## Links
+
+- [Handover Platform](https://handover.carney.dev)
+- [SDK on npm](https://www.npmjs.com/package/@handoverhq/sdk)

package/index.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+import readline from "node:readline/promises";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Template is bundled inside this package, relative to this file.
+// Override with --template-dir or HANDOVER_TEMPLATE_DIR env var.
+const defaultTemplateDir = path.join(__dirname, "template");
+
+const EXCLUDED_ENTRIES = new Set([
+  ".next",
+  "node_modules",
+  ".env.local",
+  "pnpm-lock.yaml",
+  "pnpm-workspace.yaml",
+  "tsconfig.tsbuildinfo",
+]);
+
+function printUsage() {
+  console.log("Usage: pnpm create handoverhq@latest [target-directory]");
+  console.log("       npx create-handover@latest [target-directory]");
+  console.log("");
+  console.log("Options:");
+  console.log("  --template-dir <path>   Use a custom template directory");
+  console.log("  -h, --help              Show this help message");
+  console.log("");
+  console.log("Env override: HANDOVER_TEMPLATE_DIR=/abs/path/to/template");
+}
+
+function resolveInputPath(rawPath) {
+  if (!rawPath) {
+    return "";
+  }
+
+  if (path.isAbsolute(rawPath)) {
+    return rawPath;
+  }
+
+  return path.resolve(process.cwd(), rawPath);
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let targetArg;
+  let templateDirArg;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === "--") {
+      continue;
+    }
+
+    if (arg === "-h" || arg === "--help") {
+      return { showHelp: true };
+    }
+
+    if (arg === "--template-dir") {
+      const value = args[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --template-dir");
+      }
+
+      templateDirArg = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    if (!targetArg) {
+      targetArg = arg;
+      continue;
+    }
+
+    throw new Error(`Unexpected extra argument: ${arg}`);
+  }
+
+  return {
+    showHelp: false,
+    targetArg,
+    templateDirArg,
+  };
+}
+
+function toPackageName(raw) {
+  const normalized = raw
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]/g, "-")
+    .replace(/--+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  return normalized || "handover-client-site";
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureEmptyDir(targetDir) {
+  if (!(await exists(targetDir))) {
+    await fs.mkdir(targetDir, { recursive: true });
+    return;
+  }
+
+  const contents = await fs.readdir(targetDir);
+  if (contents.length > 0) {
+    throw new Error(`Target directory is not empty: ${targetDir}`);
+  }
+}
+
+async function copyDirectory(srcDir, dstDir) {
+  await fs.mkdir(dstDir, { recursive: true });
+  const entries = await fs.readdir(srcDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (EXCLUDED_ENTRIES.has(entry.name)) {
+      continue;
+    }
+
+    const sourcePath = path.join(srcDir, entry.name);
+    const targetPath = path.join(dstDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDirectory(sourcePath, targetPath);
+      continue;
+    }
+
+    if (entry.isFile()) {
+      await fs.copyFile(sourcePath, targetPath);
+    }
+  }
+}
+
+async function updateScaffoldPackageJson(targetDir) {
+  const packageJsonPath = path.join(targetDir, "package.json");
+  const packageJsonRaw = await fs.readFile(packageJsonPath, "utf8");
+  const packageJson = JSON.parse(packageJsonRaw);
+
+  packageJson.name = toPackageName(path.basename(targetDir));
+  packageJson.private = true;
+
+  await fs.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`, "utf8");
+}
+
+async function run() {
+  const { showHelp, targetArg, templateDirArg } = parseArgs(process.argv);
+  const templateDirInput =
+    templateDirArg || (process.env.HANDOVER_TEMPLATE_DIR || "").trim() || defaultTemplateDir;
+  const templateDir = resolveInputPath(templateDirInput);
+
+  if (showHelp) {
+    printUsage();
+    process.exit(0);
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  const projectInput =
+    targetArg ||
+    (await rl.question("Project directory name (e.g. my-client-site): ")).trim() ||
+    "my-client-site";
+
+  const trpcInput = (
+    await rl.question("Include tRPC placeholder setup? (y/N): ")
+  )
+    .trim()
+    .toLowerCase();
+  const includeTrpc = trpcInput === "y" || trpcInput === "yes";
+
+  const modeInput = (
+    await rl.question("Default theme mode? (light/dark) [light]: ")
+  )
+    .trim()
+    .toLowerCase();
+  const themeMode = modeInput === "dark" ? "dark" : "light";
+
+  rl.close();
+
+  const targetDir = path.resolve(process.cwd(), projectInput);
+
+  if (!(await exists(templateDir))) {
+    throw new Error(`Template directory not found: ${templateDir}`);
+  }
+
+  await ensureEmptyDir(targetDir);
+  await copyDirectory(templateDir, targetDir);
+  await updateScaffoldPackageJson(targetDir);
+
+  const envExamplePath = path.join(targetDir, ".env.example");
+  const readmePath = path.join(targetDir, "README.md");
+  const globalsPath = path.join(targetDir, "app", "globals.css");
+
+  if (themeMode === "dark") {
+    const globalsCss = await fs.readFile(globalsPath, "utf8");
+    const darkCss = globalsCss
+      .replace("--background: var(--surface-100);", "--background: var(--bg-900);")
+      .replace("--foreground: var(--text-900);", "--foreground: #e2e8f0;")
+      .replace("--surface-card-bg: #ffffff;", "--surface-card-bg: #0f172a;");
+    await fs.writeFile(globalsPath, darkCss, "utf8");
+  }
+
+  if (includeTrpc) {
+    const envExample = await fs.readFile(envExamplePath, "utf8");
+    const withTrpcEnv = `${envExample}\n# Optional tRPC API endpoint placeholder\nNEXT_PUBLIC_TRPC_URL=https://api.example.com/trpc\n`;
+    await fs.writeFile(envExamplePath, withTrpcEnv, "utf8");
+
+    const readme = await fs.readFile(readmePath, "utf8");
+    const trpcNote = "\n## Optional tRPC placeholder\n\nYou enabled the tRPC placeholder flag.\nSet `NEXT_PUBLIC_TRPC_URL` if your project exposes a tRPC endpoint.\nThis template does not ship runtime tRPC coupling by default.\n";
+    await fs.writeFile(readmePath, `${readme}${trpcNote}`, "utf8");
+  }
+
+  const relativePath = path.relative(process.cwd(), targetDir) || ".";
+
+  console.log("\n✅ Scaffold created successfully.");
+  console.log(`📁 Location: ${relativePath}`);
+  console.log(`🎨 Theme mode: ${themeMode}`);
+  console.log(`🔌 tRPC placeholder: ${includeTrpc ? "enabled" : "disabled"}`);
+  console.log("\nNext steps:");
+  console.log(`  cd ${relativePath}`);
+  console.log("  pnpm install");
+  console.log("  cp .env.example .env.local");
+  console.log("  # Fill in your API key and URL from the Handover dashboard");
+  console.log("  pnpm dev");
+}
+
+run().catch((error) => {
+  console.error(`\ncreate-handover failed: ${error.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "create-handover",
+  "version": "0.1.1",
+  "description": "Scaffold a new Handover client site — the white-label admin boilerplate for the Handover CMS platform",
+  "type": "module",
+  "bin": {
+    "create-handover": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "template",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "handover",
+    "cms",
+    "scaffold",
+    "create",
+    "boilerplate",
+    "nextjs",
+    "white-label"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/olivercarney/handover-platform"
+  }
+}

package/template/README.md

@@ -0,0 +1,61 @@
+# Handover Boilerplate
+
+Client-facing template for websites connected to Handover via SDK/API only.
+
+## What this template includes
+
+- Public site shell (`/`)
+- Embedded client admin (`/admin/login`, `/admin`)
+- Text and image editing through Handover API endpoints
+- Lock-state handling (`HANDOVER_LOCKED`)
+
+## Publish-ready acceptance criteria
+
+- Client-facing landing page at `/` explains what the site is and links to `/admin/login`.
+- Admin area has clear empty/loading/error states for text and image workflows.
+- Branding surface is env-driven (`NEXT_PUBLIC_SITE_NAME`, `NEXT_PUBLIC_ADMIN_TITLE`, etc.).
+- Runtime integration stays SDK/API-only (no Convex/Clerk/Polar coupling).
+- Build and lint pass in scaffold output before client handoff.
+
+## Required environment variables
+
+Create `.env.local` (or copy from `.env.example`) with:
+
+```bash
+NEXT_PUBLIC_HANDOVER_API_URL=https://your-platform-domain
+NEXT_PUBLIC_HANDOVER_API_KEY=ho_live_xxxxxxxxxxxxxxxxxxxx
+```
+
+Optional branding variables:
+
+```bash
+NEXT_PUBLIC_SITE_NAME="Client Site"
+NEXT_PUBLIC_ADMIN_TITLE="Client Admin"
+NEXT_PUBLIC_BRAND_TAGLINE="Keep your website content fresh with a secure, lightweight admin experience."
+NEXT_PUBLIC_SUPPORT_EMAIL="support@example.com"
+```
+
+## Quick start
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Open:
+
+- `http://localhost:3000` for the public view
+- `http://localhost:3000/admin/login` for client editing access
+
+## Production handoff checklist
+
+1. Set `NEXT_PUBLIC_HANDOVER_API_URL` and `NEXT_PUBLIC_HANDOVER_API_KEY`.
+2. Confirm lock-state behavior by toggling lock in platform dashboard.
+3. Upload and delete at least one image in `/admin`.
+4. Update branding env vars to client-facing values.
+5. Deploy.
+
+## Boundary note
+
+This boilerplate intentionally has no direct Convex/Clerk/Polar runtime dependency.
+Integration boundary stays at Handover SDK/API.

package/template/app/admin/login/page.tsx

@@ -0,0 +1,261 @@
+"use client";
+
+import { useState, FormEvent } from "react";
+import { useRouter } from "next/navigation";
+import { useHandover } from "@/components/HandoverProvider";
+import { Lock, UserPlus } from "lucide-react";
+import { HandoverError } from "@/lib/handover";
+import { branding } from "@/lib/branding";
+
+export default function AdminLoginPage() {
+    const [username, setUsername] = useState("");
+    const [password, setPassword] = useState("");
+    const [clientPassword, setClientPassword] = useState("");
+    const [resetToken, setResetToken] = useState("");
+    const [resetPassword, setResetPassword] = useState("");
+    const [confirmResetPassword, setConfirmResetPassword] = useState("");
+    const [isResetMode, setIsResetMode] = useState(false);
+    const [needsBootstrap, setNeedsBootstrap] = useState(false);
+    const [error, setError] = useState("");
+    const [isLoading, setIsLoading] = useState(false);
+    const { handover } = useHandover();
+    const router = useRouter();
+
+    const persistSession = (token: string, user: { id: string; username: string; role: string; status: string }) => {
+        localStorage.setItem("handover_admin_session", token);
+        localStorage.setItem("handover_admin_user", JSON.stringify(user));
+    };
+
+    const handleSubmit = async (e: FormEvent) => {
+        e.preventDefault();
+        setIsLoading(true);
+        setError("");
+
+        try {
+            if (isResetMode) {
+                if (resetPassword !== confirmResetPassword) {
+                    setError("Reset passwords do not match.");
+                    return;
+                }
+                await handover.resetAdminPasswordWithToken(resetToken, resetPassword);
+                setError("Password reset successful. You can now sign in.");
+                setIsResetMode(false);
+                setResetToken("");
+                setResetPassword("");
+                setConfirmResetPassword("");
+                return;
+            }
+
+            if (needsBootstrap) {
+                const result = await handover.bootstrapAdmin(clientPassword, username, password);
+                persistSession(result.token, result.user);
+                router.push("/admin");
+                return;
+            }
+
+            const result = await handover.loginAdmin(username, password);
+            persistSession(result.token, result.user);
+            router.push("/admin");
+        } catch (err: unknown) {
+            if (err instanceof HandoverError && err.code === "AUTH_RATE_LIMITED") {
+                setError("Too many failed attempts. Please wait and try again.");
+            } else if (err instanceof HandoverError && err.code === "RESET_TOKEN_EXPIRED") {
+                setError("This reset token has expired. Request a new one from an admin.");
+            } else if (err instanceof HandoverError && err.code === "RESET_TOKEN_USED") {
+                setError("This reset token has already been used. Request a new one.");
+            } else if (err instanceof HandoverError && err.code === "INVALID_RESET_TOKEN") {
+                setError("Invalid reset token. Check the token and try again.");
+            } else if (err instanceof HandoverError && err.code === "ADMIN_NOT_BOOTSTRAPPED") {
+                setNeedsBootstrap(true);
+                setError("No admin users are set up yet. Create the owner account below.");
+            } else if (err instanceof HandoverError && err.code === "INVALID_CREDENTIALS") {
+                setError("Invalid username or password.");
+            } else if (err instanceof HandoverError && err.code === "ACCOUNT_DISABLED") {
+                setError("This account is disabled. Contact the project owner.");
+            } else if (err instanceof HandoverError && err.code === "INVALID_PASSWORD") {
+                setError("Invalid client password. Please try again.");
+            } else if (err instanceof HandoverError && err.code === "ADMIN_USERS_ALREADY_INITIALIZED") {
+                setNeedsBootstrap(false);
+                setError("Admin users are already initialized. Sign in with username and password.");
+            } else {
+                setError("Unable to sign in right now. Please try again in a moment.");
+            }
+        } finally {
+            setIsLoading(false);
+        }
+    };
+
+    return (
+        <div className="min-h-screen admin-shell flex items-center justify-center p-[var(--spacing-page-x)] sm:p-[var(--spacing-card)]">
+            <div className="surface-card max-w-md w-full p-[var(--spacing-card)] sm:p-[var(--spacing-section)]">
+                <div className="text-center mb-[var(--spacing-section)]">
+                    <div className="bg-teal-50 w-12 h-12 rounded-full flex items-center justify-center mx-auto mb-[var(--spacing-stack)]">
+                        {needsBootstrap ? <UserPlus className="w-6 h-6 text-teal-700" /> : <Lock className="w-6 h-6 text-teal-700" />}
+                    </div>
+                    <p className="section-label">{branding.adminTitle}</p>
+                    <h1 className="text-2xl font-bold text-slate-900 mt-[var(--spacing-inline)]">{isResetMode ? "Reset Admin Password" : needsBootstrap ? "Initialize Admin Access" : "Secure Admin Login"}</h1>
+                    <p className="text-slate-600 mt-[var(--spacing-inline)]">
+                        {isResetMode
+                            ? "Use your one-time reset token to set a new password."
+                            : needsBootstrap
+                            ? "Create the owner account for this /admin workspace."
+                            : "Sign in with your admin username and password."}
+                    </p>
+                </div>
+
+                <form onSubmit={handleSubmit} className="space-y-[var(--spacing-stack)]">
+                    {!isResetMode && (
+                        <div>
+                            <label htmlFor="admin-username" className="mb-[var(--spacing-1)] block text-xs font-semibold uppercase tracking-wider text-slate-500">Username</label>
+                            <input
+                                id="admin-username"
+                                type="text"
+                                value={username}
+                                onChange={(e) => setUsername(e.target.value)}
+                                placeholder="Username"
+                                className="w-full px-[var(--spacing-stack)] py-2.5 border border-slate-200 rounded-lg focus-ring focus:border-transparent transition-all"
+                                autoFocus
+                                autoComplete="username"
+                                required
+                            />
+                        </div>
+                    )}
+
+                    {!isResetMode && (
+                        <div>
+                            <label htmlFor="admin-password" className="mb-[var(--spacing-1)] block text-xs font-semibold uppercase tracking-wider text-slate-500">Password</label>
+                            <input
+                                id="admin-password"
+                                type="password"
+                                value={password}
+                                onChange={(e) => setPassword(e.target.value)}
+                                placeholder={needsBootstrap ? "Owner account password" : "Password"}
+                                className="w-full px-[var(--spacing-stack)] py-2.5 border border-slate-200 rounded-lg focus-ring focus:border-transparent transition-all"
+                                autoComplete="current-password"
+                                required
+                            />
+                        </div>
+                    )}
+
+                    {isResetMode && (
+                        <>
+                            <div>
+                                <label htmlFor="admin-reset-token" className="mb-[var(--spacing-1)] block text-xs font-semibold uppercase tracking-wider text-slate-500">Reset Token</label>
+                                <input
+                                    id="admin-reset-token"
+                                    type="text"
+                                    value={resetToken}
+                                    onChange={(e) => setResetToken(e.target.value)}
+                                    placeholder="One-time reset token"
+                                    className="w-full px-[var(--spacing-stack)] py-2.5 border border-slate-200 rounded-lg focus-ring focus:border-transparent transition-all"
+                                    autoFocus
+                                    required
+                                />
+                            </div>
+                            <div>
+                                <label htmlFor="admin-reset-password" className="mb-[var(--spacing-1)] block text-xs font-semibold uppercase tracking-wider text-slate-500">New Password</label>
+                                <input
+                                    id="admin-reset-password"
+                                    type="password"
+                                    value={resetPassword}
+                                    onChange={(e) => setResetPassword(e.target.value)}
+                                    placeholder="New password"
+                                    className="w-full px-[var(--spacing-stack)] py-2.5 border border-slate-200 rounded-lg focus-ring focus:border-transparent transition-all"
+                                    required
+                                />
+                            </div>
+                            <div>
+                                <label htmlFor="admin-reset-confirm" className="mb-[var(--spacing-1)] block text-xs font-semibold uppercase tracking-wider text-slate-500">Confirm New Password</label>
+                                <input
+                                    id="admin-reset-confirm"
+                                    type="password"
+                                    value={confirmResetPassword}
+                                    onChange={(e) => setConfirmResetPassword(e.target.value)}
+                                    placeholder="Confirm new password"
+                                    className="w-full px-[var(--spacing-stack)] py-2.5 border border-slate-200 rounded-lg focus-ring focus:border-transparent transition-all"
+                                    required
+                                />
+                            </div>
+                            <p className="mt-[var(--spacing-inline)] text-xs text-slate-500">
+                                Password must be 10-128 chars and include uppercase, lowercase, and a number.
+                            </p>
+                        </>
+                    )}
+
+                    {needsBootstrap && (
+                        <div>
+                            <label htmlFor="admin-client-password" className="mb-[var(--spacing-1)] block text-xs font-semibold uppercase tracking-wider text-slate-500">Current Client Password</label>
+                            <input
+                                id="admin-client-password"
+                                type="password"
+                                value={clientPassword}
+                                onChange={(e) => setClientPassword(e.target.value)}
+                                placeholder="Current client password"
+                                className="w-full px-[var(--spacing-stack)] py-2.5 border border-slate-200 rounded-lg focus-ring focus:border-transparent transition-all"
+                                autoComplete="off"
+                                required
+                            />
+                            <p className="mt-[var(--spacing-inline)] text-xs text-slate-500">
+                                Required once to authorize owner account setup.
+                            </p>
+                        </div>
+                    )}
+
+                    {error && (
+                        <div role="alert" aria-live="polite" className="error-banner text-sm text-center py-[var(--spacing-inline)] rounded-lg px-[var(--spacing-3)]">
+                            {error}
+                        </div>
+                    )}
+
+                    <button
+                        type="submit"
+                        disabled={isLoading}
+                        className="w-full bg-teal-700 text-white py-2.5 rounded-lg font-medium hover:bg-teal-800 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+                    >
+                        {isLoading ? "Verifying..." : isResetMode ? "Reset Password" : needsBootstrap ? "Create Owner Account" : "Login"}
+                    </button>
+                </form>
+
+                <div className="mt-[var(--spacing-stack)] grid gap-[var(--spacing-inline)]">
+                    {!needsBootstrap && !isResetMode && (
+                        <button
+                            type="button"
+                            onClick={() => {
+                                setNeedsBootstrap(true);
+                                setError("");
+                            }}
+                            className="w-full text-xs text-slate-500 hover:text-slate-700 transition-colors"
+                        >
+                            First-time setup? Initialize admin owner account
+                        </button>
+                    )}
+                    {!isResetMode && (
+                        <button
+                            type="button"
+                            onClick={() => {
+                                setIsResetMode(true);
+                                setNeedsBootstrap(false);
+                                setError("");
+                            }}
+                            className="w-full text-xs text-slate-500 hover:text-slate-700 transition-colors"
+                        >
+                            Have a reset token? Reset password
+                        </button>
+                    )}
+                    {isResetMode && (
+                        <button
+                            type="button"
+                            onClick={() => {
+                                setIsResetMode(false);
+                                setError("");
+                            }}
+                            className="w-full text-xs text-slate-500 hover:text-slate-700 transition-colors"
+                        >
+                            Back to login
+                        </button>
+                    )}
+                </div>
+            </div>
+        </div>
+    );
+}