# @bloomneo/bloom v4.0.0 Scaffolding CLI for full-stack apps combining `@bloomneo/appkit` (Express backend) and `@bloomneo/uikit` (React frontend) with Feature-Based Component Architecture (FBCA). Cross-surface: web, desktop (Electron), mobile (Capacitor). This file is the canonical machine-readable reference for the bloom CLI. Agents working in a scaffolded project should read the project's own `docs/appkit.md` + `docs/uikit.md` for library APIs — this file is only about `bloom create` and `bloom start`. --- ## Commands ### `bloom create [template]` Scaffolds a new project at `.//` from a template. ``` bloom create my-app # Default: basicapp bloom create my-app userapp # Named template bloom create . userapp # Scaffold into current dir bloom create my-app userapp --skip-install # Scaffold files only, no npm install bloom create my-app userapp --verbose # Debug logging ``` Refuses to overwrite an existing directory (except `.`). Exits 1 on conflict. ### `bloom start` Runs a scaffolded project's production server. Requires a prior `npm run build` — exits 1 with an actionable message if dist/ is absent. Equivalent to running `npm run start:api` inside the project. ### `bloom --help | -h | help` Prints usage. Exits 0. ### `bloom --version | -v | version` Prints the installed bloom version. Exits 0. --- ## Templates | Name | Surface | Backend | Data | First-run command | |---|---|---|---|---| | `basicapp` | Web | Express (appkit) | — | `npm run dev` | | `userapp` | Web | Express + Prisma + auth | Prisma (Postgres/SQLite) | `npx prisma db push && npm run dev` | | `desktop-basicapp` | Desktop (Electron) | Embedded Express | — | `npm run dev` | | `desktop-userapp` | Desktop (Electron) | Embedded Express | better-sqlite3 | `npm run dev` | | `mobile-basicapp` | Mobile (Capacitor) | **None (UI-only)** | — | `npx cap sync ios\|android` + native build | ### Template picker - **Plain fullstack web app** → `basicapp` - **Fullstack + auth + users** → `userapp` - **Cross-platform desktop** → `desktop-basicapp` or `desktop-userapp` - **Native mobile (no backend)** → `mobile-basicapp` (needs a `basicapp` / `userapp` deployed separately) --- ## What scaffold produces Every template includes: - `AGENTS.md` — project-level agent rules (placeholders replaced at scaffold + re-filled by postinstall) - `package.json` — pins `@bloomneo/uikit@^2.0.1` + (where applicable) `@bloomneo/appkit@^4.0.0`, plus a `postinstall` hook - `scripts/copy-agent-docs.js` — postinstall script that populates: - `docs/appkit.md`, `docs/appkit-agents.md` - `docs/uikit.md`, `docs/uikit-agents.md` - `.claude/skills/` (every appkit + uikit skill) - `src/web/` (or `src/mobile/`) with FBCA feature structure - `src/api/` (web + desktop templates) with appkit + feature routes - Language: TypeScript; bundler: Vite; router: FBCA auto-discovery --- ## Flags ``` --verbose Debug logging during scaffold (stdio: inherit for npm install) --skip-install Scaffold files only; skip npm install (CI / dry-run) --no-install Alias for --skip-install ``` --- ## Exit codes ``` 0 Success (scaffold complete, help printed, version printed, start succeeded) 1 Usage error (no command, unknown command, invalid template name, directory conflict, missing build, npm install failure) ``` --- ## FBCA in scaffolded projects Features live under `src/web/features//pages/`. Each `.tsx` file becomes a route. Auto-discovery via `import.meta.glob` — no manual route registration. Dynamic segments use `[param]`; catch-all uses `[...path]`. Adding a new page = creating a file. Don't edit the page-router. --- ## Migration Current release: **4.0.0**. Jumping from any pre-4 version needs the breaking ecosystem-pin bumps below. Existing scaffolded projects keep working against their pinned versions — nothing auto-upgrades. ### From `@bloomneo/bloom@1.5.x` / 2.x / 3.x → `4.0.0` 1. Re-scaffold (preferred — `bloom create` on a fresh project) or apply manual changes: - `@bloomneo/appkit` pin: `^1.5.1` / `^2.0.0` → `^4.0.0` - `@bloomneo/uikit` pin: `^1.5.1` → `^2.0.1` 2. Source changes for the appkit 2.0 rename: - `auth.user(req)` → `auth.getUser(req)` - `auth.can(user, perm)` → `auth.hasPermission(user, perm)` (if you used it — templates didn't) - `security.csrf()` → `security.forms()` (if you used it) - `handleErrors({ includeStack })` → `handleErrors({ showStack })` 3. Source changes for the uikit 2.0 rename: - `` → `` (if you used it — templates didn't) 4. Re-run `npm install` — the 3.x postinstall copies appkit's and uikit's `AGENTS.md` + `llms.txt` + skill trees into the scaffolded `docs/` and `.claude/skills/`. ### Why three majors in one day `bloom@2.0.0` bumped the appkit pin (`^1.5.1` / `^2.0.0` → `^4.0.0`) because appkit 2.0 was on npm `latest` and templates needed the modern API. `bloom@3.0.0` bumped the uikit pin (`^1.5.1` → `^2.0.1`) because uikit 2.0.1 also reached npm `latest`. Both peer-dependency major bumps are breaking per semver, so each gets its own major. ### What 1.6.0 through 3.0.0 added (cumulative, since they were all ### unpublished until 3.0.1 on npm, then 3.0.2 for doc alignment) - Root `AGENTS.md` (this doc's sibling) + `llms.txt` (this file) - `scripts/check-doc-drift.mjs` + `scripts/scaffold-smoke.test.mjs` - `.github/workflows/ci.yml` (Node 18/20/22 matrix) - `--help` / `-h` / `help`, `--version` / `-v` / `version`, `--skip-install` flags on the CLI - Unified `scripts/copy-agent-docs.js` across all 5 templates: copies appkit + uikit `llms.txt`, `AGENTS.md`, and skill trees into the scaffolded project's `docs/` and `.claude/skills/`; fills `{{PROJECT_NAME}}` placeholders; survives gracefully when a package (e.g. appkit for the mobile template) isn't installed. - Templates use `"name": "{{PROJECT_NAME}}"` (was hard-coded `bloom-