@betterstart/cli 0.1.37 → 0.1.39

package/README.md

@@ -1,48 +1,61 @@
 # @betterstart/cli
 
-Scaffold a full-featured, code-generated CMS into any Next.js 16 application. The CMS lives in a self-contained `cms/` directory — you own the code, eject anytime.
+> **Warning:** This project is a work in progress. Expect bugs, breaking changes, and incomplete features.
 
-## Quick Start
+Drop a production-ready CMS into any Next.js 16 app with one command. You get a full admin panel — auth, CRUD, rich text editing, file uploads, forms — living in a self-contained `cms/` directory. You own the code. No vendor lock-in.
 
 ```bash
-npx @betterstart/cli init my-app --preset blog
+npx @betterstart/cli init
 ```
 
-This will:
+## What you get
 
-1. Create a new Next.js app (or detect your existing project)
-2. Scaffold the CMS into `cms/` with auth, database, admin UI, and API routes
-3. Install all dependencies
-4. Generate blog schemas (posts + categories) with full CRUD
+- **Admin panel** with sidebar navigation, search, filters, bulk actions, and CSV export
+- **Authentication** via Better Auth (email/password, role-based: admin, editor, member)
+- **22 field types** including rich text (TipTap), markdown (CodeMirror + Shiki), image/video uploads, relationships, tabs, groups, lists, and curriculum builder
+- **Public forms** with multi-step support, email notifications, Mailchimp integration, and a submissions admin
+- **Three schema types** — entities (full CRUD), singles (settings pages), and forms (public-facing with submission tracking)
+- **Caching** with Next.js 16 `'use cache'` directive, `cacheLife`, `cacheTag`, and `updateTag`
 
 ## Commands
 
 ### `betterstart init [name]`
 
-Scaffold CMS into a new or existing Next.js project.
+Scaffold the CMS into a new or existing Next.js project.
 
 ```bash
-betterstart init                    # Existing project
-betterstart init my-app             # Fresh project
-betterstart init --preset blank     # No starter content
-betterstart init --preset blog      # Blog (default)
-betterstart init --preset full      # Blog + navigation + contact form
+betterstart init                       # Interactive setup in current project
+betterstart init my-app                # Create new Next.js app + CMS
+betterstart init --preset blog -y      # Non-interactive with blog preset
 ```
 
+**Presets:**
+
+| Preset | What it includes |
+|--------|-----------------|
+| `blank` | Settings singleton only |
+| `blog` | Settings + Categories + Posts (with many-to-many) |
+| `full` | Blog + Navigation + Contact form |
+
+Init runs 12 scaffolders in sequence: base directories, tsconfig aliases, Tailwind tokens, env vars, database, auth, UI components (206 files), layouts, API routes, linter config, dependency installation (~130 packages), and preset generation.
+
 ### `betterstart generate <schema>`
 
-Generate entity or form CRUD from a JSON schema in `cms/schemas/`.
+Generate everything from a JSON schema file in `cms/schemas/`.
 
 ```bash
-betterstart generate posts          # Entity CRUD
-betterstart generate contact        # Form (auto-detected)
-betterstart generate posts --force  # Overwrite existing files
-betterstart generate posts --skip-migration  # Skip db:push
+betterstart generate posts                # Entity CRUD (12 files)
+betterstart generate settings             # Single-type page (7 files)
+betterstart generate contact              # Form + admin (14 files)
+betterstart generate posts --force        # Overwrite existing files
+betterstart generate posts --skip-migration  # Skip drizzle-kit push
 ```
 
+Schema type is auto-detected: files in `schemas/forms/` or with `submitButtonText`/`steps` are forms, `type: "single"` is a single, everything else is an entity.
+
 ### `betterstart remove <schema>`
 
-Remove all generated files for an entity or form.
+Remove all generated files for a schema and clean up `schema.ts` + `navigation.ts`.
 
 ```bash
 betterstart remove posts
@@ -50,83 +63,197 @@ betterstart remove posts
 
 ### `betterstart seed`
 
-Create an initial admin user.
+Create an initial admin user interactively.
 
 ```bash
 betterstart seed
 ```
 
-## What Gets Generated
+### `betterstart setup-r2`
+
+Configure Cloudflare R2 for file uploads.
+
+### `betterstart update-deps`
 
-For each entity schema, the CLI generates 12 files:
+Install or update all CMS dependencies to their latest versions.
 
-| # | File | Description |
-|---|------|-------------|
-| 1 | `cms/db/schema.ts` | Drizzle table definition (appended) |
-| 2 | `cms/lib/actions/<name>.ts` | Server actions (CRUD) |
-| 3 | `cms/hooks/use-<name>.ts` | React Query hook |
-| 4 | `cms/lib/cache/<name>.ts` | Cache tags + queries |
-| 5 | `app/(cms)/cms/(authenticated)/<name>/columns.tsx` | Table column definitions |
-| 6 | `app/(cms)/cms/(authenticated)/<name>/<name>-table.tsx` | Data table component |
-| 7 | `app/(cms)/cms/(authenticated)/<name>/<name>-page-content.tsx` | Page content (client) |
-| 8 | `app/(cms)/cms/(authenticated)/<name>/page.tsx` | Page (server) |
-| 9 | `app/(cms)/cms/(authenticated)/<name>/<name>-form.tsx` | Create/edit form |
-| 10 | `app/(cms)/cms/(authenticated)/<name>/new/page.tsx` | Create page |
-| 11 | `app/(cms)/cms/(authenticated)/<name>/[id]/edit/page.tsx` | Edit page |
-| 12 | `cms/data/navigation.ts` | Sidebar nav (appended) |
+### `betterstart update-styles`
 
-## Schema Format
+Replace `cms-globals.css` with the latest version from the CLI templates.
 
-### Entity Schema
+## Generated file structure
+
+```
+cms/
+  db/schema.ts                 # Drizzle table definitions
+  lib/actions/<name>.ts        # Server actions (CRUD, search, filter, export)
+  lib/cache/                   # Cache tags, cached queries, revalidation
+  hooks/use-<name>.ts          # React Query hooks
+  components/forms/            # Public form components
+  lib/emails/                  # React Email notification templates
+  data/navigation.ts           # Sidebar navigation config
+
+app/(cms)/cms/(authenticated)/
+  <entity>/
+    page.tsx                   # Server page with Suspense
+    columns.tsx                # TanStack Table column definitions
+    <name>-table.tsx           # Data table with pagination + sorting
+    page-content.tsx           # Client component (search, filters, bulk actions)
+    <name>-form.tsx            # Create/edit form with Zod validation
+    new/page.tsx               # Create page
+    [id]/edit/page.tsx         # Edit page
+  forms/<form>/
+    page.tsx                   # Submissions list
+    [id]/page.tsx              # View submission
+    settings/page.tsx          # Notification + export settings
+```
+
+## Schema examples
+
+### Entity
 
 ```json
 {
   "name": "posts",
-  "label": "Posts",
+  "label": "Blog Posts",
   "icon": "FileText",
+  "navGroup": { "label": "Blog", "icon": "BookOpen" },
   "fields": [
     { "name": "title", "type": "string", "label": "Title", "required": true },
-    { "name": "slug", "type": "string", "label": "Slug", "required": true },
-    { "name": "content", "type": "richtext", "label": "Content" },
+    { "name": "slug", "type": "string", "label": "Slug", "hidden": true },
+    { "name": "content", "type": "richtext", "label": "Content", "output": "html" },
+    { "name": "image", "type": "image", "label": "Featured Image" },
     { "name": "published", "type": "boolean", "label": "Published" },
-    { "name": "publishedAt", "type": "date", "label": "Publish Date" },
-    { "name": "image", "type": "image", "label": "Featured Image" }
-  ]
+    {
+      "name": "categories",
+      "type": "relationship",
+      "relationship": "categories",
+      "label": "Categories",
+      "multiple": true
+    }
+  ],
+  "columns": [
+    { "accessorKey": "title", "header": "Title", "type": "text", "sortable": true },
+    { "accessorKey": "published", "header": "Status", "type": "badge" }
+  ],
+  "actions": { "create": true, "edit": true, "delete": true, "draft": true },
+  "search": { "fields": ["title"] },
+  "autoSlugify": { "enabled": true, "sourceField": "title", "targetField": "slug" }
 }
 ```
 
-Field types: `string`, `text`, `richtext`, `number`, `boolean`, `date`, `image`, `select`, `relationship`.
-
-### Form Schema
+### Single
 
 ```json
 {
-  "name": "contact",
-  "label": "Contact Form",
-  "type": "form",
-  "submitButtonText": "Send Message",
+  "name": "settings",
+  "type": "single",
+  "label": "Settings",
+  "icon": "Settings",
   "fields": [
-    { "name": "name", "type": "text", "label": "Name", "required": true },
-    { "name": "email", "type": "email", "label": "Email", "required": true },
-    { "name": "message", "type": "textarea", "label": "Message", "required": true }
+    { "name": "siteName", "type": "string", "label": "Site Name" },
+    { "name": "description", "type": "text", "label": "Description" }
   ]
 }
 ```
 
-## Tech Stack
+### Form (multi-step)
 
-- **Framework:** Next.js 16 (App Router)
-- **Database:** Drizzle ORM + Neon PostgreSQL
-- **Auth:** Better Auth (email/password, roles)
-- **UI:** Radix UI + Tailwind CSS v4
-- **Rich Text:** TipTap
-- **Storage:** Cloudflare R2
-- **Email:** Resend + React Email (opt-in)
+```json
+{
+  "name": "candidateApplication",
+  "label": "Candidate Applications",
+  "icon": "UserPlus",
+  "submitButtonText": "Submit Application",
+  "successMessage": "Thanks for applying!",
+  "notificationEmail": "hr@example.com",
+  "steps": [
+    {
+      "name": "basicInfo",
+      "label": "Basic Information",
+      "fields": [
+        { "name": "name", "type": "text", "label": "Full Name", "required": true },
+        { "name": "email", "type": "email", "label": "Email", "required": true }
+      ]
+    },
+    {
+      "name": "experience",
+      "label": "Experience",
+      "fields": [
+        { "name": "resume", "type": "upload", "label": "Resume" }
+      ]
+    }
+  ]
+}
+```
+
+## Field types
+
+### Entity/Single (22 types)
+
+| Category | Types |
+|----------|-------|
+| Text | `string`, `text`, `varchar` |
+| Rich content | `richtext`, `markdown` |
+| Numbers | `number`, `decimal`, `serial` |
+| Date/time | `date`, `timestamp`, `time` |
+| Boolean | `boolean` |
+| Media | `image`, `video`, `media`, `icon` |
+| Selection | `select`, `relationship` |
+| Layout | `group`, `tabs`, `separator` |
+| Complex | `list`, `curriculum` |
+
+### Form (17 types)
+
+`text`, `textarea`, `email`, `phone`, `number`, `url`, `date`, `select`, `radio`, `checkbox`, `multiselect`, `file`, `upload`, `group`, `list`, `timezone`, `dynamicFields`
+
+## Tech stack
+
+| Concern | Technology |
+|---------|-----------|
+| Framework | Next.js 16 (App Router) |
+| Database | Drizzle ORM + Neon PostgreSQL |
+| Auth | Better Auth |
+| UI | Radix primitives + Tailwind CSS v4 |
+| Rich text | TipTap |
+| Markdown | CodeMirror + Shiki + KaTeX |
+| Tables | TanStack React Table |
+| Data fetching | TanStack React Query |
+| Forms | React Hook Form + Zod |
+| URL state | nuqs |
+| Storage | Cloudflare R2 |
+| Email | Resend + React Email (opt-in) |
+| Icons | Lucide React |
+
+## Configuration
+
+Create `cms.config.ts` in your project root (generated by `init`):
+
+```typescript
+import { defineConfig } from '@betterstart/cli'
+
+export default defineConfig({
+  database: {
+    provider: 'neon',
+  },
+  features: {
+    email: true,
+  },
+})
+```
+
+All generated code uses `@cms/*` path aliases:
+
+```typescript
+import { db } from '@cms/db'
+import { posts } from '@cms/db/schema'
+import { getPosts } from '@cms/actions/posts'
+```
 
 ## Requirements
 
 - Node.js >= 22
-- Next.js 16 with TypeScript and Tailwind CSS
+- Next.js 16 with TypeScript and Tailwind CSS v4
 
 ## License
 

package/dist/cli.js

@@ -2359,6 +2359,8 @@ function generateFieldJSX(field) {
   const hint = field.hint || "";
   const hintJSX = hint ? `
                   <FormDescription>${escapeJsx(hint)}</FormDescription>` : "";
+  const hintPlainJSX = hint ? `
+          <p className="text-sm text-muted-foreground">${escapeJsx(hint)}</p>` : "";
   const requiredStar = field.required ? ' <span className="text-destructive">*</span>' : "";
   switch (field.type) {
     case "textarea":
@@ -2459,7 +2461,7 @@ ${optionItems}
     case "upload":
       return generateTextFieldJSX(name, label, placeholder, hintJSX, requiredStar, "file");
     case "list":
-      return generateListFieldJSX(field, name, label, hintJSX, requiredStar);
+      return generateListFieldJSX(field, name, label, hintPlainJSX, requiredStar);
     default:
       return generateTextFieldJSX(name, label, placeholder, hintJSX, requiredStar, "text");
   }
@@ -2533,7 +2535,7 @@ ${selectItems}
     return `${nf.name}: ''`;
   }).join(", ");
   return `        <div className="space-y-4">
-          <FormLabel>${label}${requiredStar}</FormLabel>${hintJSX}
+          <label className="text-sm font-medium leading-none">${label}${requiredStar}</label>${hintJSX}
           {${name}FieldArray.fields.map((item, index) => (
             <div key={item.id} className="flex items-end gap-2 rounded-lg border p-4">
               <div className="flex-1 space-y-4">
@@ -2558,6 +2560,38 @@ ${nestedFieldsJSX}
 // src/generators/form-pipeline/form-database.ts
 import fs8 from "fs";
 import path8 from "path";
+function findTableEnd(content, startIndex) {
+  let depth = 0;
+  let inString = false;
+  let stringChar = "";
+  for (let i = startIndex; i < content.length; i++) {
+    const char = content[i];
+    const prev = i > 0 ? content[i - 1] : "";
+    if ((char === '"' || char === "'" || char === "`") && prev !== "\\") {
+      if (!inString) {
+        inString = true;
+        stringChar = char;
+      } else if (char === stringChar) {
+        inString = false;
+      }
+      continue;
+    }
+    if (inString) continue;
+    if (char === "(" || char === "{" || char === "[") depth++;
+    if (char === ")" || char === "}" || char === "]") depth--;
+    if (depth === 0 && char === ")") {
+      let end = i + 1;
+      while (end < content.length && (content[end] === ";" || content[end] === " " || content[end] === "	")) {
+        end++;
+      }
+      if (end < content.length && content[end] === "\n") {
+        end++;
+      }
+      return end;
+    }
+  }
+  return content.length;
+}
 function generateFormDatabase(schema, cwd, dbSchemaPath, options) {
   const tableName = `${toCamelCase(schema.name)}Submissions`;
   const fields = getAllFormSchemaFields(schema);
@@ -2606,8 +2640,13 @@ ${match}`
     if (!options.force) {
       return { files: [dbSchemaPath] };
     }
-    const regex = new RegExp(`\\nexport const ${tableName} = pgTable\\([\\s\\S]*?\\n\\}\\)\\n`, "g");
-    content = content.replace(regex, "");
+    const marker = `export const ${tableName} =`;
+    const start = content.indexOf(marker);
+    if (start !== -1) {
+      const end = findTableEnd(content, start);
+      const actualStart = start > 0 && content[start - 1] === "\n" ? start - 1 : start;
+      content = content.slice(0, actualStart) + content.slice(end);
+    }
   }
   content += `
 ${tableSchema}`;
@@ -4811,7 +4850,7 @@ ${updated}`;
   }
   return updated;
 }
-function findTableEnd(content, startIndex) {
+function findTableEnd2(content, startIndex) {
   let depth = 0;
   let inString = false;
   let stringChar = "";
@@ -4863,7 +4902,7 @@ function generateDatabase(schema, cwd, schemaDir, options = {}) {
   let updated = content;
   if (options.force && content.includes(`export const ${variableName} =`)) {
     const start = content.indexOf(`export const ${variableName} =`);
-    const end = findTableEnd(content, start);
+    const end = findTableEnd2(content, start);
     updated = content.slice(0, start) + tableDef.trim() + content.slice(end);
   } else {
     updated = `${updated.trimEnd()}
@@ -4873,7 +4912,7 @@ ${tableDef}`;
     const jName = junctionNames[i];
     if (options.force && updated.includes(`export const ${jName} =`)) {
       const start = updated.indexOf(`export const ${jName} =`);
-      const end = findTableEnd(updated, start);
+      const end = findTableEnd2(updated, start);
       updated = updated.slice(0, start) + junctionDefs[i].trim() + updated.slice(end);
     } else if (!updated.includes(`export const ${jName} =`)) {
       updated = `${updated.trimEnd()}
@@ -14247,7 +14286,7 @@ import fs39 from "fs";
 import path44 from "path";
 import readline from "readline";
 import { Command as Command4 } from "commander";
-function findTableEnd2(content, startIndex) {
+function findTableEnd3(content, startIndex) {
   let depth = 0;
   let inString = false;
   let stringChar = "";
@@ -14281,7 +14320,7 @@ function removeTableFromSchema(schemaFilePath, name) {
   let changed = false;
   if (content.includes(`export const ${variableName} =`)) {
     const start = content.indexOf(`export const ${variableName} =`);
-    const end = findTableEnd2(content, start);
+    const end = findTableEnd3(content, start);
     content = content.slice(0, start) + content.slice(end);
     changed = true;
   }
@@ -14293,7 +14332,7 @@ function removeTableFromSchema(schemaFilePath, name) {
     const jVarName = jMatch[1];
     const jStart = content.indexOf(`export const ${jVarName} =`);
     if (jStart !== -1) {
-      const jEnd = findTableEnd2(content, jStart);
+      const jEnd = findTableEnd3(content, jStart);
       content = content.slice(0, jStart) + content.slice(jEnd);
       changed = true;
       regex.lastIndex = 0;