create-better-system 1.0.0

package/README.md

@@ -0,0 +1,158 @@
+# create-better-system
+
+CLI to scaffold new projects from the [Better System](https://github.com/brunogilferro/better-system) template.
+
+## What it does
+
+1. Clones the Better System monorepo template
+2. Asks 5 questions about your project
+3. Fills in design tokens, fonts, and CSS variables automatically
+4. Leaves you with a ready-to-code project
+
+---
+
+## Usage
+
+```bash
+npx create-better-system
+```
+
+Or install globally:
+
+```bash
+npm install -g create-better-system
+create-better-system
+```
+
+---
+
+## Questions asked
+
+| Question | Default | Notes |
+|----------|---------|-------|
+| Project name | — | Used as folder name and package name |
+| Color theme | Dark only | Dark / Light / Both (with toggle) |
+| Heading font | Poppins | Any Google Font name |
+| Primary accent color | `#D4AF37` | Main brand color |
+| Secondary accent color | `#38bdf8` | Secondary highlights |
+
+---
+
+## After creation
+
+```bash
+# 1. Enter the project folder
+cd <project-name>
+
+# 2. Install dependencies
+pnpm install
+
+# 3. Set up backend environment
+cp apps/backend/.env.example apps/backend/.env
+# Edit apps/backend/.env and set APP_KEY and any other required values
+
+# 4. Run database migrations
+cd apps/backend
+node ace migration:run
+
+# 5. Start the project
+cd ../..
+pnpm dev
+```
+
+Frontend runs on `http://localhost:3000`
+Backend runs on `http://localhost:3333`
+
+---
+
+## What gets configured automatically
+
+- `docs/figma-design-rules.md` — filled with your design tokens
+- `apps/frontend/app/globals.css` — CSS variables set from your tokens
+- `apps/frontend/app/layout.tsx` — heading font imported from `next/font/google`
+- `package.json` — project name updated
+
+---
+
+## Using AI in your project
+
+Once the project is open in Cursor, the AI already knows your architecture, design tokens, and rules.
+
+### Create a complete feature (backend + frontend)
+
+```
+new-feature: courses with name, description and price
+```
+
+The AI will generate the migration, model, validator, service, controller, route, types, hook, and page automatically.
+
+---
+
+### Implement a screen from Figma
+
+```
+figma-to-next-screen: [paste Figma link here]
+```
+
+The AI reads the design, creates an architecture plan, implements with shadcn + your design tokens, and refines against the Figma screenshot.
+
+---
+
+### Generate only the backend for a resource (new table)
+
+```
+backend-from-schema: product with name (string), price (number), stock (integer)
+```
+
+Generates migration, model, validator, transformer, service, controller, and route.
+
+---
+
+### Generate backend from an existing database table
+
+```bash
+# First, pull the current schema from the database
+cd apps/backend && node ace db:pull
+```
+
+Then in Cursor:
+
+```
+database-to-feature: tabela products
+```
+
+Generates model (enhanced from db:pull), validator, transformer, service, controller, and route. **No migration created** — the table already exists.
+
+For tables that already exist, you can also use:
+
+```
+backend-from-schema: product [existing table] with name, price, stock
+```
+
+---
+
+### Write tests
+
+```
+write-tests: apps/backend/app/services/product_service.ts
+```
+
+Generates unit and integration tests following the project's conventions.
+
+---
+
+## Template includes
+
+- **Frontend**: Next.js 16, React 19, Tailwind v4, shadcn/ui (14 components), React Query
+- **Backend**: AdonisJS v7 with auth (signup, login, logout, profile)
+- **Type-safe API**: Tuyau client pre-configured in `lib/api.ts`
+- **Cursor AI skills**: `figma-to-next-screen`, `backend-from-schema`, `new-feature`, `write-tests`
+- **Cursor AI rules**: frontend, backend, accessibility, commits
+- **Docs**: design-system, components-registry, data-pattern, api-conventions, error-handling, state-management, figma-design-rules
+
+---
+
+## Requirements
+
+- Node.js 18+
+- pnpm

package/index.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+
+import inquirer from 'inquirer'
+import { execa } from 'execa'
+import fs from 'fs-extra'
+import path from 'path'
+
+const THEME_PRESETS = {
+  dark: {
+    bgPrimary: '#0a0e16',
+    bgSecondary: '#0e1117',
+    bgSurface: '#111827',
+    textPrimary: '#e0e0d0',
+    textSecondary: '#6a7282',
+    borderPrimary: '#1a2233',
+    borderSecondary: '#2a3545',
+  },
+  light: {
+    bgPrimary: '#ffffff',
+    bgSecondary: '#f9fafb',
+    bgSurface: '#f3f4f6',
+    textPrimary: '#111827',
+    textSecondary: '#6b7280',
+    borderPrimary: '#e5e7eb',
+    borderSecondary: '#d1d5db',
+  },
+}
+
+// Converts a font name like "Open Sans" to the Next.js import format "Open_Sans"
+function toNextFontName(fontName) {
+  return fontName.trim().replace(/\s+/g, '_')
+}
+
+// Converts a font name to a valid JS variable name: "Open Sans" → "openSans"
+function toVarName(fontName) {
+  const words = fontName.trim().split(/\s+/)
+  return words
+    .map((w, i) => (i === 0 ? w.toLowerCase() : w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()))
+    .join('')
+}
+
+function colorTable(colors) {
+  return [
+    '| Token                | Value                | Usage                |',
+    '|----------------------|----------------------|----------------------|',
+    `| \`--bg-primary\`       | ${colors.bgPrimary.padEnd(20)} | Main page background |`,
+    `| \`--bg-secondary\`     | ${colors.bgSecondary.padEnd(20)} | Secondary surfaces   |`,
+    `| \`--bg-surface\`       | ${colors.bgSurface.padEnd(20)} | Cards, panels        |`,
+    `| \`--text-primary\`     | ${colors.textPrimary.padEnd(20)} | Primary text         |`,
+    `| \`--text-secondary\`   | ${colors.textSecondary.padEnd(20)} | Muted text           |`,
+    `| \`--border-primary\`   | ${colors.borderPrimary.padEnd(20)} | Default borders      |`,
+    `| \`--border-secondary\` | ${colors.borderSecondary.padEnd(20)} | Subtle dividers      |`,
+  ].join('\n')
+}
+
+// ─── Prompts ──────────────────────────────────────────────────────────────────
+
+console.log('\n🚀 Better System — Create new project\n')
+
+const answers = await inquirer.prompt([
+  {
+    name: 'name',
+    message: 'Project name?',
+    validate: (v) => v.trim().length > 0 || 'Name is required',
+  },
+  {
+    name: 'theme',
+    type: 'list',
+    message: 'Color theme?',
+    choices: [
+      { name: 'Dark only', value: 'dark' },
+      { name: 'Light only', value: 'light' },
+      { name: 'Both (dark + light with toggle)', value: 'both' },
+    ],
+    default: 'dark',
+  },
+  {
+    name: 'headingFont',
+    message: 'Heading font (e.g. Poppins, Sora)?',
+    default: 'Poppins',
+  },
+  {
+    name: 'accentPrimary',
+    message: 'Primary accent color (hex)?',
+    default: '#D4AF37',
+  },
+  {
+    name: 'accentSecondary',
+    message: 'Secondary accent color (hex)?',
+    default: '#38bdf8',
+  },
+])
+
+// ─── Resolve values ───────────────────────────────────────────────────────────
+
+const projectName = answers.name.trim()
+const projectPath = path.resolve(process.cwd(), projectName)
+
+const isBoth = answers.theme === 'both'
+const isDark = answers.theme === 'dark'
+const rootColors = isBoth ? THEME_PRESETS.light : (isDark ? THEME_PRESETS.dark : THEME_PRESETS.light)
+const darkColors = THEME_PRESETS.dark
+
+// Font helpers
+const headingFontNextName = toNextFontName(answers.headingFont)
+const headingFontVarName = toVarName(answers.headingFont) + 'Font'
+
+// ─── Clone template ───────────────────────────────────────────────────────────
+
+console.log('\n📦 Cloning Better System template...')
+await execa('npx', ['degit', 'brunogilferro/better-system', projectName], {
+  stdio: 'inherit',
+})
+
+// ─── Update layout.tsx with heading font ─────────────────────────────────────
+
+console.log('🔤 Configuring fonts...')
+
+const layoutPath = path.join(projectPath, 'apps', 'frontend', 'app', 'layout.tsx')
+let layout = await fs.readFile(layoutPath, 'utf-8')
+
+layout = layout
+  .replace(
+    '// __HEADING_FONT_IMPORT__',
+    `import { ${headingFontNextName} } from "next/font/google"`
+  )
+  .replace(
+    '// __HEADING_FONT_DECLARATION__',
+    `const ${headingFontVarName} = ${headingFontNextName}({\n  variable: "--font-heading",\n  subsets: ["latin"],\n  weight: ["400", "500", "700"],\n})`
+  )
+  .replaceAll('__HEADING_FONT_CLASS__', `\${${headingFontVarName}.variable}`)
+  .replaceAll('__PROJECT_NAME__', projectName)
+
+await fs.writeFile(layoutPath, layout)
+
+// ─── Fill globals.css placeholders ───────────────────────────────────────────
+
+console.log('💅 Configuring CSS variables...')
+
+const cssPath = path.join(projectPath, 'apps', 'frontend', 'app', 'globals.css')
+let css = await fs.readFile(cssPath, 'utf-8')
+
+const cssReplacements = {
+  '__HEADING_FONT__': answers.headingFont,
+  '__BODY_FONT__': 'Inter',
+  '__ACCENT_PRIMARY__': answers.accentPrimary,
+  '__ACCENT_PRIMARY_HOVER__': answers.accentPrimary,
+  '__ACCENT_SECONDARY__': answers.accentSecondary,
+  '__BG_PRIMARY__': rootColors.bgPrimary,
+  '__BG_SECONDARY__': rootColors.bgSecondary,
+  '__BG_SURFACE__': rootColors.bgSurface,
+  '__TEXT_PRIMARY__': rootColors.textPrimary,
+  '__TEXT_SECONDARY__': rootColors.textSecondary,
+  '__BORDER_PRIMARY__': rootColors.borderPrimary,
+  '__BORDER_SECONDARY__': rootColors.borderSecondary,
+}
+
+for (const [placeholder, value] of Object.entries(cssReplacements)) {
+  css = css.replaceAll(placeholder, value)
+}
+
+if (isBoth) {
+  const darkReplacements = {
+    '__DARK_BG_PRIMARY__': darkColors.bgPrimary,
+    '__DARK_BG_SECONDARY__': darkColors.bgSecondary,
+    '__DARK_BG_SURFACE__': darkColors.bgSurface,
+    '__DARK_TEXT_PRIMARY__': darkColors.textPrimary,
+    '__DARK_TEXT_SECONDARY__': darkColors.textSecondary,
+    '__DARK_BORDER_PRIMARY__': darkColors.borderPrimary,
+    '__DARK_BORDER_SECONDARY__': darkColors.borderSecondary,
+  }
+  for (const [placeholder, value] of Object.entries(darkReplacements)) {
+    css = css.replaceAll(placeholder, value)
+  }
+  css = css.replace('/* DARK_THEME_BLOCK_START */', '').replace('/* DARK_THEME_BLOCK_END */', '')
+} else {
+  css = css.replace(
+    /\/\* DARK_THEME_BLOCK_START \*\/[\s\S]*?\/\* DARK_THEME_BLOCK_END \*\//,
+    ''
+  )
+}
+
+await fs.writeFile(cssPath, css)
+
+// ─── Fill figma-design-rules.md placeholders ─────────────────────────────────
+
+console.log('🎨 Configuring design tokens...')
+
+const figmaRulesPath = path.join(projectPath, 'docs', 'figma-design-rules.md')
+let figmaRules = await fs.readFile(figmaRulesPath, 'utf-8')
+
+let colorsSection
+if (isBoth) {
+  colorsSection = [
+    '## Colors — Light theme (default)',
+    '',
+    colorTable(THEME_PRESETS.light),
+    '',
+    '## Colors — Dark theme (`.dark` class on `<html>`)',
+    '',
+    colorTable(THEME_PRESETS.dark),
+  ].join('\n')
+} else {
+  const label = isDark ? 'Dark theme' : 'Light theme'
+  colorsSection = `## Colors — ${label}\n\n${colorTable(rootColors)}`
+}
+
+const figmaReplacements = {
+  '__THEME_MODE__': answers.theme,
+  '__HEADING_FONT__': answers.headingFont,
+  '__BODY_FONT__': 'Inter',
+  '__ACCENT_PRIMARY__': answers.accentPrimary,
+  '__ACCENT_PRIMARY_HOVER__': answers.accentPrimary,
+  '__ACCENT_SECONDARY__': answers.accentSecondary,
+  '__COLORS_SECTION__': colorsSection,
+  '__CSS_BLOCK__': isBoth ? 'Both light and dark — see globals.css' : `Single theme (${answers.theme})`,
+}
+
+for (const [placeholder, value] of Object.entries(figmaReplacements)) {
+  figmaRules = figmaRules.replaceAll(placeholder, value)
+}
+
+await fs.writeFile(figmaRulesPath, figmaRules)
+
+// ─── Update root package.json ─────────────────────────────────────────────────
+
+console.log('📝 Updating package.json...')
+
+const rootPkgPath = path.join(projectPath, 'package.json')
+const rootPkg = await fs.readJson(rootPkgPath)
+rootPkg.name = projectName
+await fs.writeJson(rootPkgPath, rootPkg, { spaces: 2 })
+
+// ─── Done ─────────────────────────────────────────────────────────────────────
+
+console.log(`\n✅ Project "${projectName}" created!`)
+
+if (isBoth) {
+  console.log(`\n💡 Both themes enabled.`)
+  console.log(`   Light is the default. Add class="dark" to <html> to activate dark.`)
+}
+
+console.log(`\nNext steps:`)
+console.log(`  cd ${projectName}`)
+console.log(`  pnpm install`)
+console.log(`  pnpm dev\n`)

package/package.json

@@ -0,0 +1,13 @@
+{
+    "name": "create-better-system",
+    "version": "1.0.0",
+    "bin": {
+      "create-better-system": "index.js"
+    },
+    "type": "module",
+    "dependencies": {
+      "inquirer": "^9.0.0",
+      "execa": "^8.0.0",
+      "fs-extra": "^11.0.0"
+    }
+  }