@xeplr/cli 0.1.5 → 0.1.7

package/README.md

@@ -4,9 +4,11 @@ Creates a working xeplr application — an API, sign-in, and a UI — from a few
 questions, installs it, and sets up its databases.
 
 ```bash
-npx @xeplr/cli new myapp
+npx @xeplr/cli@latest new myapp
 ```
 
+`@latest` makes npx fetch the newest version rather than one it cached earlier.
+
 ## What you get
 
 ```
@@ -28,16 +30,23 @@ Already working, with nothing to wire up:
   table. Neither is written by hand: both are screens
   ([`@xeplr/ui-factory`](https://www.npmjs.com/package/@xeplr/ui-factory)),
   published when the API first starts.
-- **A Forms page** for Super Admin — every form in the app; make a new one by
-  hand (no Claude needed), design its form and its list, publish (which creates
-  or changes its table), open it. Nobody else sees it, and the API refuses
-  everyone else.
+- **Configure UI** for Super Admin, in the settings menu (top right) — not in
+  the side rail, which is for the pages people use:
+  - **Forms**: every UI in the app. New form (a **label** people see and a
+    **key** that names its table), design its form and its list, publish (which
+    creates or changes its table), open it, **add it to the side rail** — no
+    code, no Claude needed.
+  - **Menu**: rename, reorder and hide the side rail's items.
+
+  Nobody else sees it, and the API refuses everyone else.
 - **Multi-tenancy, if you ask for it** — companies (or companies and
   workspaces, up to four levels). Every row is stamped with the one it was made
   in, every read sees only its rows, membership is checked on every request,
   and choosing one is the first screen after signing in.
 - **A welcome screen** that checks it can reach everything and tells you which
   files to change first.
+- **READMEs** at the project root and in `api/` and `ui/`: how to start it,
+  every command, where things live, and the rules the app follows.
 - **A `CLAUDE.md`** that tells Claude how to create a new UI in this app — the
   screens, the page with its front-end hooks, the server hooks and model, the
   route and menu entry — and a ready prompt (also shown beside the sample):
@@ -47,6 +56,21 @@ Already working, with nothing to wire up:
   > acres (number, at least 0), Started on (date), Notes (long text). Show Name,
   > Region and Area in the list. Follow "Create a new UI" in CLAUDE.md.
 
+## Rules the generated app follows
+
+These are architecture decisions, not defaults to tune — each one exists because the alternative failed quietly.
+
+| Rule | Where | Why |
+|---|---|---|
+| **Records live in real tables, one column per field — never JSON.** | `@xeplr/factory` | `select * from tasks` and plain-SQL reports must work. Only a screen's *design* is JSON (the `factory_screens` table). |
+| **A key and a label, everywhere.** A form's key (`farming_department`) names its screens and table and never changes once published; its label is renamed any time. A menu item's key (`menus.name`, used by `drawerItems` / `settingsOverrides` in `ui/src/App.jsx` and `ui/src/menu.js`) is what code matches; its label is what the rail shows. | `@xeplr/auth`, `@xeplr/ui-account` | Code must never break because someone renamed something people read. No label is written in code. |
+| **`REDIS_PREFIX` is required and unique per app** (`api/development.env`, set to `<name>:`). | `@xeplr/auth`, `@xeplr/utils` | Two apps on one Redis under the shared default serve each other's sessions, menus and API permissions. Sign-in refuses to start without it, or with `xeplr:`. |
+| **Designing, new forms and publishing are Super Admin only.** | `api/routes/access.js`, `@xeplr/auth` menu routes | Publishing changes database tables. Every other screen route checks the permission catalog. |
+| **The browser is not a security boundary.** Front-end hooks (`ui/src/pages/Edit<Form>.jsx`) shape what people see and send; anything that must hold goes in server hooks (`api/screens/<form>/<form>.hooks.js`); data shape in the model (`<form>.model.js`). | `@xeplr/ui-factory`, `@xeplr/factory` | |
+| **Every data address is under `/api`.** | `api/routes`, `ui/vite.config.js` | A page path and a data path must never collide. |
+| **No guessed database names or connections.** | `api/development.env` | A wrong-but-present value starts cleanly and reads as empty data. |
+| **Email is checked at start, never fatal.** The sign-in banner shows `email ✓ …` or `✗ NOT WORKING — reason`. | `@xeplr/auth` | Sign-in works without email; activation, invite and reset links cannot be sent until `EMAIL_PROVIDER` is set. |
+
 ## Before you start
 
 - **Node.js** 18 or later
@@ -83,13 +107,49 @@ cd myapp/api && npm run start-api    # your API — publishes the sample screens
 cd myapp/ui  && npm run dev          # the app
 ```
 
-Open the UI and sign in with the account you named.
+Open the UI and sign in with the account you named. As Super Admin you will
+see **Configure UI** in the settings menu, top right.
+
+**Use a new project name for a new app.** The name decides the database names
+(`<name>_auth`, `<name>_api`); an existing database is kept as it is, with its
+accounts — the super admin you enter is created only in a fresh one.
 
 `xeplr new myapp --no-install` only writes the files; then run `npm install` in
 `api` and `ui`, and `npm run setup` in `api`, yourself. If set-up stops part
 way (Postgres not running, say), the installer says which step and the command
 to run again.
 
+## Creating a new UI
+
+Two ways, both in the running app's project:
+
+- **No code** — Configure UI → Forms → New form → design → Publish → Add to menu.
+- **With Claude** — open Claude in the project folder and give it this (it is
+  also beside the sample, with a Copy button):
+
+  > Create a new UI for farming departments. One record is a farming department
+  > with: Name (required), Region (dropdown: North, South, East, West), Area in
+  > acres (number, at least 0), Started on (date), Notes (long text). Show Name,
+  > Region and Area in the list. Follow "Create a new UI" in CLAUDE.md.
+
+  Claude follows `CLAUDE.md`: the screens and server hooks and model
+  (`npx xeplr-factory screens … --no-pages`), the page with its front-end hooks,
+  the route, the side-rail item and its menu row. Then restart the sign-in
+  service and the API — the API publishes the new screens and creates the table.
+
+## Commands in a generated project
+
+| Where | Command | Does |
+|---|---|---|
+| `api/` | `npm run setup` | create both databases, the sign-in tables, permissions and menus |
+| `api/` | `npm run start-auth` | the sign-in service |
+| `api/` | `npm run start-api` | the API — runs migrations and publishes never-published screens on start |
+| `api/` | `npm run migrate:auth` | apply new `migrations-auth/*.sql` (e.g. a new menu row) |
+| `api/` | `npm run db:encrypt` | redo the encrypted database connection |
+| `api/` | `npx xeplr-factory screens screens/<form>/<form>.entity.json -o screens/<form> --no-pages` | a form's screens, server hooks and model from its spec |
+| `api/` | `npx xeplr-factory validate <screen>.json` | check a screen document |
+| `ui/` | `npm run dev` | the app |
+
 ## Changing the database connection later
 
 A password rotates, the database moves, or the first answer was wrong. From

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Creates a working xeplr application — API, sign-in and UI — from a few answers.",
   "license": "MIT",
   "author": "xeppie <admin@xeplr.com>",

package/templates/README.md

@@ -0,0 +1,48 @@
+# __NAME__
+
+An xeplr application, created by [`@xeplr/cli`](https://www.npmjs.com/package/@xeplr/cli).
+
+```
+__NAME__/
+├─ api/        the API and the sign-in service          → api/README.md
+├─ ui/         the React app                           → ui/README.md
+└─ CLAUDE.md   how to change this app — for Claude, and a good read for people
+```
+
+## Start it
+
+Needs **PostgreSQL** and **Redis** running.
+
+```bash
+cd api && npm run start-auth     # sign-in           http://localhost:__AUTH_PORT__
+cd api && npm run start-api      # the API           http://localhost:__API_PORT__
+cd ui  && npm run dev            # the app           http://localhost:__UI_PORT__
+```
+
+Open http://localhost:__UI_PORT__ and sign in as `__ADMIN_EMAIL__`.
+
+## What is in it
+
+- **Sign-in** — login, register, password reset, profile, and the admin screens for users, roles and permissions (`@xeplr/auth`, `@xeplr/ui-account`).
+- **Tasks** — a sample built from screens: a list, and a form it opens in a popup, saved into an ordinary `tasks` table.
+- **Configure UI** — in the settings menu, for Super Admin: every form (make one, design it, publish it, add it to the side rail) and the side rail itself (rename, reorder, hide).
+
+## Create a new UI
+
+- **Without code** — Configure UI → Forms → New form → design → Publish → Add to menu.
+- **With Claude** — open Claude in this folder and give it (change the name and the fields):
+
+  > Create a new UI for farming departments. One record is a farming department with: Name (required), Region (dropdown: North, South, East, West), Area in acres (number, at least 0), Started on (date), Notes (long text). Show Name, Region and Area in the list. Follow "Create a new UI" in CLAUDE.md.
+
+## Rules this app follows
+
+| Rule | Why |
+|---|---|
+| Records live in **real tables**, one column per field — never JSON. | Reports stay plain SQL. |
+| A **key** and a **label**, everywhere: code uses keys (form keys, menu keys); people read labels, renamed in Configure UI. | Renaming what people see never breaks code. |
+| **`REDIS_PREFIX`** in `api/development.env` is required and unique to this app. | Apps sharing a Redis would otherwise serve each other's sessions and permissions. |
+| Designing and publishing forms is **Super Admin only**. | Publishing changes database tables. |
+| Rules that must hold go in **server hooks**; the browser only shapes what people see and send. | The browser is not a security boundary. |
+| Every data address is under **`/api`**. | A page and a data path must never collide. |
+
+The full list, and where each piece lives, is in `CLAUDE.md`.

package/templates/api/README.md

@@ -0,0 +1,40 @@
+# __NAME__ — api
+
+The API (`@xeplr/base-apis`) and the sign-in service (`@xeplr/auth`), with this app's forms served by `@xeplr/factory`.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `npm run setup` | create both databases (`__NAME___auth`, `__NAME___api`), the sign-in tables, permissions and menus |
+| `npm run start-auth` | the sign-in service, port __AUTH_PORT__ — refuses to start without Redis or `REDIS_PREFIX`; its banner says whether email works |
+| `npm run start-api` | the API, port __API_PORT__ — runs `migrations/` and publishes never-published screens on start |
+| `npm run migrate:auth` | apply new `migrations-auth/*.sql` (a new menu row, say), then restart sign-in |
+| `npm run db:encrypt` | redo the encrypted database connection |
+| `npm run check-env` | check every required setting is present |
+| `npx xeplr-factory screens screens/<form>/<form>.entity.json -o screens/<form> --no-pages` | a form's screens, server hooks and model from its spec |
+| `npx xeplr-factory validate <screen>.json` | check a screen document |
+
+## Layout
+
+| Path | What |
+|---|---|
+| `development.env` | every setting — ports, the encrypted connection, `REDIS_PREFIX`, secrets, the super admin, email |
+| `env.required.js` | the settings that must be present; the API refuses to start and names any that are missing |
+| `app.js` | the Express app: the auth gate, and the routes |
+| `routes/index.js` | this app's own routes — every data address under `/api` |
+| `routes/access.js` | who may design and publish forms (Super Admin) |
+| `screens/` | the forms this app ships with: per form, its spec, list and edit screens, server hooks and model — registered in `screens/index.js` |
+| `migrations/` | hand-written SQL for tables no form owns |
+| `migrations-auth/` | this app's rows in the sign-in database — menus (by key), permissions |
+| `models/` | models for hand-written tables |
+
+## Settings to know
+
+| Setting | |
+|---|---|
+| `REDIS_PREFIX` | **required, unique to this app** (`__NAME__:`) |
+| `__PREFIX___CONNECTION`, `AUTH_DB_CONNECTION_INFO_ENCRYPTED` | the database, encrypted — `npm run db:encrypt` |
+| `DB_API`, `AUTH_DB_NAME` | the two database names — never guessed |
+| `AUTH_SUPER_ADMIN_EMAIL` / `_PASSWORD` | the first account — created once, when the sign-in database is first set up |
+| `EMAIL_PROVIDER` and its settings | optional; without them sign-in works, but activation and reset links cannot be sent |

package/templates/ui/README.md

@@ -0,0 +1,28 @@
+# __NAME__ — ui
+
+The React app (Vite), using `@xeplr/ui-account` for sign-in and the app shell and `@xeplr/ui-factory` for forms.
+
+```bash
+npm run dev       # http://localhost:__UI_PORT__
+npm run build     # → dist/
+```
+
+`.env` holds the port and where the sign-in service and the API are; `vite.config.js` proxies `/auth/api` to sign-in and `/api` (and `/health`, `/whoami`) to the API. A new data prefix must be added there too.
+
+## Layout
+
+| Path | What |
+|---|---|
+| `src/main.jsx` | `ThemeProvider` (required — the theme's colours exist only inside it) and `AccessProvider` |
+| `src/App.jsx` | routes, the side rail (`drawerItems`) and the settings menu (`settingsOverrides`) — **by key**, never by label |
+| `src/menu.js` | every menu key this app uses; forms added to the menu are `form:<key>` |
+| `src/api/factory.js` | the calls to the API's forms routes |
+| `src/pages/Tasks.jsx` | the sample list; `EditTask.jsx` holds the task form's **front-end hooks** (`TaskHooks extends FactoryHooks` — every method calls `super`) |
+| `src/pages/ConfigureUI.jsx` | Configure UI (Super Admin): `Forms.jsx` and `MenuSettings.jsx` tabs; `FormDesigner.jsx` designs one form |
+| `src/pages/FormRecords.jsx` | opens any published form — what a form added to the menu links to |
+
+## Rules
+
+- `authFetch` returns the **parsed body**, not a Response — no `.json()`.
+- A side-rail item needs an **icon** (a collapsed rail shows icons only) and its key must exist as a menu row, or it is dropped silently.
+- Set page backgrounds on a container inside the theme, never on `body`.