create-ab-app 0.1.1

package/README.md

@@ -0,0 +1,60 @@
+# create-ab-app
+
+Scaffold a React + Vite app with authentication and billing already wired up via
+[`ab-ecosystem-sso`](https://www.npmjs.com/package/ab-ecosystem-sso).
+
+```bash
+npm create ab-app@latest my-app
+```
+
+```
+◇  Where should the project be created?  my-app
+◇  App display name                      My App
+◇  Auth project id                       459412-review-ai.abprojects.com
+◇  Auth API base URL                     https://partner-api.example.com
+◇  Your own API base URL                 (optional)
+◇  Start with the in-app documentation?  Yes
+◇  Package manager                       npm
+◇  Install dependencies now?             Yes
+◇  Initialise a git repository?          Yes
+```
+
+You get React 19, TypeScript, Tailwind v4, shadcn/ui with the `sidebar-07` shell,
+login / signup / 2FA / magic links / password reset / email verification, plans,
+wallets, credits, route guards, entitlement gating, toasts and a theme toggle.
+
+## Options
+
+Every prompt has a flag, so CI can scaffold non-interactively:
+
+```bash
+npx create-ab-app my-app \
+  --project-id=459412-review-ai.abprojects.com \
+  --auth-url=https://partner-api.example.com \
+  --app-name="Review AI" \
+  --minimal --no-install --no-git -y
+```
+
+| Flag | Effect |
+| --- | --- |
+| `--project-id=<id>` | `VITE_AUTH_PROJECT_ID` (required) |
+| `--auth-url=<url>` | `VITE_AUTH_API_BASE_URL` |
+| `--api-url=<url>` | `VITE_API_BASE_URL` — your own backend |
+| `--app-name=<name>` | Sidebar and browser-tab name |
+| `--minimal` | Skip the in-app documentation pages |
+| `--pm=<npm\|pnpm\|yarn\|bun>` | Package manager |
+| `--no-install` / `--no-git` | Skip those steps |
+| `-y`, `--yes` | Accept defaults for everything optional |
+
+## After scaffolding
+
+```bash
+cd my-app
+npm run dev
+```
+
+Sign in and the sidebar carries the documentation: project structure, auth,
+billing, routing, theming, and calling your own API. The one rule it opens with:
+**import from `@/lib/sso`, never from `ab-ecosystem-sso` directly.**
+
+Requires Node 20+.

package/index.js

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+/**
+ * create-ab-app — scaffolds the React + Vite template with auth and billing.
+ *
+ * Asks for the handful of things the template cannot guess (project id, API
+ * origin, app name), writes .env.local, then optionally installs and inits git.
+ */
+import { spawn } from "node:child_process"
+import { access, cp, readdir, readFile, rename, rm, writeFile } from "node:fs/promises"
+import path from "node:path"
+import process from "node:process"
+import { fileURLToPath } from "node:url"
+
+import {
+  cancel,
+  confirm,
+  intro,
+  isCancel,
+  log,
+  note,
+  outro,
+  select,
+  spinner,
+  text,
+} from "@clack/prompts"
+import pc from "picocolors"
+
+const cliDir = path.dirname(fileURLToPath(import.meta.url))
+const templateDir = path.join(cliDir, "template")
+const variantsDir = path.join(cliDir, "variants")
+
+// ─── args ────────────────────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2)
+const flags = new Map()
+const positionals = []
+
+for (const arg of argv) {
+  if (arg.startsWith("--")) {
+    const [key, value] = arg.slice(2).split("=")
+    flags.set(key, value ?? true)
+  } else if (arg.startsWith("-") && arg !== "-") {
+    flags.set(arg.slice(1), true)
+  } else {
+    positionals.push(arg)
+  }
+}
+
+if (flags.has("help") || flags.has("h")) {
+  console.log(`
+${pc.bold("create-ab-app")} — React + Vite starter with auth and billing
+
+  ${pc.dim("npm create ab-app@latest my-app")}
+
+Options
+  --project-id=<id>     VITE_AUTH_PROJECT_ID
+  --auth-url=<url>      VITE_AUTH_API_BASE_URL
+  --api-url=<url>       VITE_API_BASE_URL (your own backend)
+  --app-name=<name>     Display name in the sidebar
+  --minimal             Skip the in-app documentation pages
+  --pm=<npm|pnpm|yarn|bun>
+  --no-install          Do not install dependencies
+  --no-git              Do not initialise a git repository
+  -y, --yes             Accept defaults for everything optional
+`)
+  process.exit(0)
+}
+
+const assumeYes = flags.has("yes") || flags.has("y")
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+/** Every prompt goes through here so Ctrl+C exits cleanly everywhere. */
+async function ask(promptPromise) {
+  const value = await promptPromise
+  if (isCancel(value)) {
+    cancel("Cancelled. Nothing was written.")
+    process.exit(0)
+  }
+  return value
+}
+
+async function exists(target) {
+  try {
+    await access(target)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function toPackageName(input) {
+  return (
+    input
+      .trim()
+      .toLowerCase()
+      .replace(/^[._]+/, "")
+      .replace(/[^a-z0-9-~._]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "app"
+  )
+}
+
+function toTitle(input) {
+  return input
+    .replace(/[-_]+/g, " ")
+    .trim()
+    .replace(/\b\w/g, (character) => character.toUpperCase())
+}
+
+function detectPackageManager() {
+  const agent = process.env.npm_config_user_agent ?? ""
+  if (agent.startsWith("pnpm")) return "pnpm"
+  if (agent.startsWith("yarn")) return "yarn"
+  if (agent.startsWith("bun")) return "bun"
+  return "npm"
+}
+
+function run(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: "pipe",
+      shell: process.platform === "win32",
+    })
+    let stderr = ""
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk
+    })
+    child.on("error", reject)
+    child.on("close", (code) =>
+      code === 0 ? resolve() : reject(new Error(stderr.trim() || `exit ${code}`)),
+    )
+  })
+}
+
+// ─── prompts ─────────────────────────────────────────────────────────────────
+
+intro(pc.bgCyan(pc.black(" create-ab-app ")))
+
+const targetInput =
+  positionals[0] ??
+  (await ask(
+    text({
+      message: "Where should the project be created?",
+      placeholder: "my-app",
+      defaultValue: "my-app",
+      validate: (value) =>
+        value && value.trim().startsWith("-")
+          ? "Directory name cannot start with a dash"
+          : undefined,
+    }),
+  ))
+
+const targetDir = path.resolve(process.cwd(), targetInput || "my-app")
+const projectName = toPackageName(path.basename(targetDir))
+
+if (await exists(targetDir)) {
+  const entries = await readdir(targetDir)
+  if (entries.length > 0) {
+    const overwrite = await ask(
+      confirm({
+        message: `${pc.yellow(path.basename(targetDir))} is not empty. Delete its contents and continue?`,
+        initialValue: false,
+      }),
+    )
+    if (!overwrite) {
+      cancel("Cancelled. Nothing was written.")
+      process.exit(0)
+    }
+    await rm(targetDir, { recursive: true, force: true })
+  }
+}
+
+const appName =
+  flags.get("app-name") ??
+  (assumeYes
+    ? toTitle(projectName)
+    : await ask(
+        text({
+          message: "App display name",
+          placeholder: toTitle(projectName),
+          defaultValue: toTitle(projectName),
+        }),
+      ))
+
+const authProjectId =
+  flags.get("project-id") ??
+  (await ask(
+    text({
+      message: "Auth project id",
+      placeholder: "459412-review-ai.abprojects.com",
+      validate: (value) =>
+        value && value.trim() ? undefined : "Required — the SDK cannot resolve a project without it",
+    }),
+  ))
+
+const authApiBaseUrl =
+  flags.get("auth-url") ??
+  (assumeYes
+    ? ""
+    : await ask(
+        text({
+          message: "Auth API base URL",
+          placeholder: "https://partner-api.example.com",
+          defaultValue: "",
+          validate: (value) =>
+            !value || /^https?:\/\//.test(value.trim())
+              ? undefined
+              : "Must start with http:// or https://",
+        }),
+      ))
+
+const apiBaseUrl =
+  flags.get("api-url") ??
+  (assumeYes
+    ? ""
+    : await ask(
+        text({
+          message: `Your own API base URL ${pc.dim("(optional, press enter to skip)")}`,
+          placeholder: "https://api.example.com",
+          defaultValue: "",
+        }),
+      ))
+
+const includeDocs = flags.has("minimal")
+  ? false
+  : assumeYes
+    ? true
+    : await ask(
+        select({
+          message: "Start with the in-app documentation?",
+          initialValue: true,
+          options: [
+            {
+              value: true,
+              label: "Yes — keep the guides and the live example",
+              hint: "recommended for a first project",
+            },
+            {
+              value: false,
+              label: "No — minimal starter",
+              hint: "one page, empty nav",
+            },
+          ],
+        }),
+      )
+
+const packageManager =
+  flags.get("pm") ??
+  (assumeYes
+    ? detectPackageManager()
+    : await ask(
+        select({
+          message: "Package manager",
+          initialValue: detectPackageManager(),
+          options: [
+            { value: "npm", label: "npm" },
+            { value: "pnpm", label: "pnpm" },
+            { value: "yarn", label: "yarn" },
+            { value: "bun", label: "bun" },
+          ],
+        }),
+      ))
+
+const shouldInstall = flags.has("no-install")
+  ? false
+  : assumeYes
+    ? true
+    : await ask(confirm({ message: "Install dependencies now?", initialValue: true }))
+
+const shouldGit = flags.has("no-git")
+  ? false
+  : assumeYes
+    ? true
+    : await ask(confirm({ message: "Initialise a git repository?", initialValue: true }))
+
+// ─── scaffold ────────────────────────────────────────────────────────────────
+
+const progress = spinner()
+progress.start("Creating project")
+
+await cp(templateDir, targetDir, { recursive: true })
+
+// npm strips .gitignore from tarballs, so the staged copy ships it renamed.
+const stagedGitignore = path.join(targetDir, "_gitignore")
+if (await exists(stagedGitignore)) {
+  await rename(stagedGitignore, path.join(targetDir, ".gitignore"))
+}
+
+const pkgPath = path.join(targetDir, "package.json")
+const pkg = JSON.parse(await readFile(pkgPath, "utf8"))
+pkg.name = projectName
+pkg.version = "0.1.0"
+pkg.private = true
+await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
+
+// The lockfile carries the old project name in its root entry.
+const lockPath = path.join(targetDir, "package-lock.json")
+if (await exists(lockPath)) {
+  const lock = JSON.parse(await readFile(lockPath, "utf8"))
+  lock.name = projectName
+  if (lock.packages?.[""]) lock.packages[""].name = projectName
+  await writeFile(lockPath, `${JSON.stringify(lock, null, 2)}
+`)
+}
+
+const envLines = [
+  "# Required — the SDK cannot resolve a project without it.",
+  `VITE_AUTH_PROJECT_ID=${authProjectId.trim()}`,
+  "",
+  "# Auth-as-a-Service origin.",
+  `VITE_AUTH_API_BASE_URL=${(authApiBaseUrl || "").trim()}`,
+  "",
+  "# Your own product API (src/lib/http.ts). Unrelated to auth.",
+  `VITE_API_BASE_URL=${(apiBaseUrl || "").trim()}`,
+  "",
+  "# Shown in the sidebar header and breadcrumb.",
+  `VITE_APP_NAME=${appName}`,
+  "",
+]
+await writeFile(path.join(targetDir, ".env.local"), envLines.join("\n"))
+
+if (!includeDocs) {
+  await rm(path.join(targetDir, "src/routes/docs"), { recursive: true, force: true })
+  await rm(path.join(targetDir, "src/components/docs"), { recursive: true, force: true })
+  await rm(path.join(targetDir, "src/routes/app/example.tsx"), { force: true })
+  await cp(path.join(variantsDir, "minimal"), targetDir, { recursive: true })
+}
+
+// index.html carries the tab title.
+const htmlPath = path.join(targetDir, "index.html")
+const html = await readFile(htmlPath, "utf8")
+await writeFile(htmlPath, html.replace(/<title>.*?<\/title>/, `<title>${appName}</title>`))
+
+progress.stop("Project created")
+
+if (shouldInstall) {
+  progress.start(`Installing dependencies with ${packageManager}`)
+  try {
+    await run(packageManager, ["install"], targetDir)
+    progress.stop("Dependencies installed")
+  } catch (error) {
+    progress.stop("Dependency install failed")
+    log.warn(`${error.message}\nRun ${pc.cyan(`${packageManager} install`)} yourself.`)
+  }
+}
+
+if (shouldGit) {
+  try {
+    await run("git", ["init"], targetDir)
+    await run("git", ["add", "-A"], targetDir)
+    await run("git", ["commit", "-m", "Initial commit from create-ab-app"], targetDir)
+    log.success("Git repository initialised")
+  } catch {
+    // Usually an unconfigured user.email — the repo still exists.
+    log.warn("Git repository created, but the initial commit failed.")
+  }
+}
+
+// ─── done ────────────────────────────────────────────────────────────────────
+
+const relative = path.relative(process.cwd(), targetDir) || "."
+const runCmd = packageManager === "npm" ? "npm run dev" : `${packageManager} dev`
+
+note(
+  [
+    `cd ${relative}`,
+    shouldInstall ? null : `${packageManager} install`,
+    runCmd,
+  ]
+    .filter(Boolean)
+    .join("\n"),
+  "Next steps",
+)
+
+log.info(
+  `${pc.dim("Auth and billing live in")} src/lib/sso ${pc.dim("— import from")} @/lib/sso${pc.dim(", never from the SDK directly.")}`,
+)
+
+outro(pc.green("Done."))

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "create-ab-app",
+  "version": "0.1.1",
+  "description": "Scaffold a React + Vite app with ab-ecosystem-sso auth and billing already wired up.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "private": false,
+  "bin": {
+    "create-ab-app": "index.js"
+  },
+  "files": [
+    "index.js",
+    "template",
+    "variants",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "stage": "node scripts/prepare-template.js",
+    "prepack": "node scripts/prepare-template.js",
+    "check": "node scripts/prepare-template.js && npm pack --dry-run"
+  },
+  "keywords": [
+    "react",
+    "vite",
+    "template",
+    "auth",
+    "billing"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "picocolors": "^1.1.1"
+  }
+}

package/template/.env.example

@@ -0,0 +1,8 @@
+# Required — your project id in the partner ecosystem.
+VITE_AUTH_PROJECT_ID=436582-forms.abprojects.com
+
+# Auth-as-a-Service origin. The SDK also reads this var directly.
+VITE_AUTH_API_BASE_URL=https://sso.1automations.com
+
+# Your own product API (used by src/lib/http.ts, unrelated to auth).
+VITE_API_BASE_URL=

package/template/.oxlintrc.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["react", "typescript", "oxc"],
+  "rules": {
+    "react/rules-of-hooks": "error",
+    "react/only-export-components": ["warn", { "allowConstantExport": true }]
+  }
+}

package/template/README.md

@@ -0,0 +1,196 @@
+# React + Vite starter — auth & billing included
+
+A team template: React 19, Vite, TypeScript, Tailwind v4, shadcn/ui, and
+[`ab-ecosystem-sso`](https://www.npmjs.com/package/ab-ecosystem-sso) wired up for
+authentication **and** billing.
+
+## Use it
+
+```bash
+npm create ab-app@latest my-app
+```
+
+The CLI (`cli/`) asks for the project id, API origins and app name, writes
+`.env.local`, and optionally installs and inits git. See [PUBLISHING.md](PUBLISHING.md)
+to publish it.
+
+## Or run this repo directly
+
+```bash
+cp .env.example .env.local   # set VITE_AUTH_PROJECT_ID
+npm install
+npm run dev
+```
+
+**The running app is the documentation.** Sign in and the sidebar has Overview,
+Project structure, Configuration, and guides for Auth, Billing, Routing, Theming
+and calling your own API — plus a Live example page showing the hooks against
+real data. Source: `src/routes/docs/`.
+
+When you start building your product, delete `src/routes/docs/` and
+`src/routes/app/example.tsx`, and replace the groups in `src/config/navigation.ts`.
+This README stays as the offline copy.
+
+Missing config fails loudly: without `VITE_AUTH_PROJECT_ID` the app renders a
+setup screen instead of an opaque network error.
+
+## The one rule
+
+**Product code imports from `@/lib/sso`, never from `ab-ecosystem-sso`.**
+
+Every SDK call takes `(projectId, token, apiBaseUrl)`. Those are bound once in
+`src/lib/sso/config.ts`, so nothing downstream repeats them — and an SDK upgrade
+is a change to one folder.
+
+## What's in `src/lib/sso`
+
+| File | Responsibility |
+| --- | --- |
+| `config.ts` | The three SDK inputs, bound once. Spread `ssoProps` into any SDK component. |
+| `token-store.ts` | The **only** place that touches token storage. Cross-tab aware; falls back to memory when storage is blocked. |
+| `auth-provider.tsx` / `auth-context.ts` | Owns the token app-wide. `useAuth() → { token, isAuthenticated, signIn, signOut }`. |
+| `auth-screens.tsx` | The SDK's `Login` / `Signup` / `ForgotPassword` / `VerifyEmail`, bound to config, token store and router. |
+| `protected-route.tsx` | `<ProtectedRoute>` (guard + `SessionProvider`) and `<PublicOnlyRoute>`. |
+| `queries.ts` | Cached, pre-bound `useProfile` / `useWallet` / `useCreditWallets` / `useRawSubscription`. |
+| `entitlements.ts` | Normalises the **raw** `/subscription` payload into `useEntitlements() → { isActive, has(id), countOf(id) }`. |
+| `require-plan.tsx` | `<RequirePlan>` — per-feature gating. |
+| `account-settings.tsx` | `useAccountSettings().open(section)` — the billing surface. |
+
+### Auth screens are central
+
+The SDK exposes no `loginApi` / `signupApi` — sign-in and sign-up are reachable
+*only* through its components, which is also what gives you the project's
+captcha config, the 2FA OTP step and magic-link sign-in for free.
+
+**The auth pages have no layout of their own.** Each SDK screen already renders a
+full-page centered root (`flex min-h-screen items-center justify-center p-4`)
+plus its own card, branding and legal links, driven by the project's
+`auth-config` — so any wrapper would just double-wrap it. Route files are one
+line each:
+
+```tsx
+export default function LoginPage() {
+  return <SsoLogin />
+}
+```
+
+Routes exist because the emailed links need them:
+
+| Route | Screen |
+| --- | --- |
+| `/login` | `Login` — also consumes a `#<access_token>` magic-link hash |
+| `/signup` | `Signup` |
+| `/forgot-password` | `ForgotPassword` — request a reset link |
+| `/reset-password/:token` | `ForgotPassword` — set a new password |
+| `/verify/:token` | `VerifyEmail` |
+
+`/reset-password?token=` and `/verify-email?token=` are kept as aliases in case a
+link carries the token as a query string.
+
+The two token routes sit **outside** `<PublicOnlyRoute>`: a user who just signed
+up is already signed in, and must still be able to verify or reset.
+
+To restyle these screens, pass `classNames` (`root`, `card`, `button`, `input`, …)
+from `auth-screens.tsx`, or retheme via the `--aas-*` bridge below — not by
+wrapping them in app markup.
+
+### The login response shape
+
+`onSuccess` receives the **raw API envelope**, not the `{ token, user }` that the
+SDK's `AuthResponse` type declares:
+
+```json
+{ "success": true, "message": "Login successful",
+  "data": { "accessToken": "eyJhbGciOi…" } }
+```
+
+`extractToken()` in `auth-screens.tsx` reads `data.accessToken` first and falls
+back through the other spellings, so a change on either side cannot silently
+break sign-in — and a response with no token now raises an error toast instead
+of doing nothing. Because `onSuccess` is typed `(data: any)`, TypeScript will not
+catch this for you.
+
+The token then goes to `tokenStore` (localStorage), which is what `useAuth()`,
+the SDK getters in `queries.ts`, and the `Authorization: Bearer` header in
+`src/lib/http.ts` all read from.
+
+### Notifications
+
+Each completed auth call raises one sonner toast from `auth-screens.tsx`, all
+sharing a single toast id so a retry replaces the previous one rather than
+stacking. Errors are echoed the same way, alongside the screens' own inline
+error state.
+
+| Flow | Callback | Toast |
+| --- | --- | --- |
+| Login | `onSuccess` | Signed in. |
+| Signup (session returned) | `onSuccess` | Account created. |
+| Signup (verification required) | `onSuccess`, no token | Account created. Check your email to verify it. |
+| Reset password | `onResetSuccess` | Password updated. |
+| Verify email | `onVerified` | Email verified. |
+| Any failure | `onError` | The error message. |
+
+**Two gaps, both in the SDK rather than here:**
+
+- *Forgot password (request a link)* fires no success callback — `ForgotPassword`
+  accepts only `onError`, `onResetSuccess` and `onBackToLogin`, and there is no
+  exported `forgotPasswordApi` to call directly. The screen shows its own inline
+  confirmation; a toast would need the SDK to expose `onSuccess` on that step.
+- *Resend verification email* does not exist — no exported function, no endpoint,
+  no UI anywhere in the package.
+
+### Billing has no route — by design
+
+Plans, add-ons, wallet and credit wallets all live in the SDK's Account Settings
+modal. The sidebar user menu opens it on the right section:
+
+```tsx
+const { open } = useAccountSettings()
+open("plans")   // "general" | "account" | "wallet" | "plans" | "credits"
+```
+
+Gating comes in two strengths:
+
+```tsx
+// Hard paywall for the whole app shell — src/App.tsx
+<ProtectedRoute enforceActiveSubscription />
+
+// Per-feature
+<RequirePlan ids={["addon-exports"]} fallback={<Upgrade />}>…</RequirePlan>
+```
+
+> **Check this first when gates misbehave.** `getUserSubscription` returns the
+> API response unmapped, so `mapSubscription()` in `entitlements.ts` guesses at
+> field spellings. Log one real payload and correct the readers there — every
+> gate in the app follows from that one function.
+
+## Dashboard
+
+`sidebar-07`, rewired: nav comes from `src/config/navigation.ts` (with optional
+`requiresIds` for entitlement-gated items), links use the router instead of
+`<a href>`, the user card reads the live profile, and the footer shows the first
+credit-wallet balance. The block's `team-switcher` was dropped — add it back as a
+project switcher if one app ever serves multiple `projectId`s.
+
+## Theming
+
+`src/styles/aas-theme.css` maps the SDK's `--aas-*` variables onto the shadcn
+tokens, so the auth screens and the settings modal match the app in light and
+dark. The SDK's CSS is scoped and unlayered — it cannot leak into your app, and
+your preflight cannot override it — which is exactly why this bridge is needed.
+
+## Your own API
+
+`src/lib/http.ts` attaches the same bearer token and, on a 401, clears the token
+so the route guard bounces to `/login`. Set `VITE_API_BASE_URL`.
+
+## Notes
+
+- `ab-ecosystem-sso` is **pinned exactly**. It is pre-1.0; upgrade deliberately.
+- Tokens live in `localStorage` (the SDK exposes no refresh flow), so an XSS bug
+  exposes them. Swapping strategy is a one-file change in `token-store.ts`.
+- Deep links need an SPA fallback — `public/_redirects` and `vercel.json` are included.
+
+## Scripts
+
+`npm run dev` · `npm run build` · `npm run typecheck` · `npm run lint` · `npm run preview`