@xeplr/cli 0.1.6 → 0.1.8

package/README.md

@@ -45,6 +45,8 @@ Already working, with nothing to wire up:
   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):

package/bin/xeplr.js

@@ -54,7 +54,14 @@ async function main() {
 
   var session = prompt.createSession();
   try {
-    var answers = await questions.collect(session, argv[1] && argv[1].indexOf('--') !== 0 ? argv[1] : undefined);
+    // A folder that already has something in it is refused NOW, before a
+    // single question is asked — not after the database password.
+    var argName = argv[1] && argv[1].indexOf('--') !== 0 ? argv[1] : undefined;
+    if (argName && generate.isOccupied(path.resolve(process.cwd(), argName))) {
+      console.error('\n  ' + path.resolve(process.cwd(), argName) + ' already exists and is not empty.\n');
+      return 1;
+    }
+    var answers = await questions.collect(session, argName);
     console.log(plan.describe(answers));
 
     var go = await session.confirm('  Create it?', true);

package/lib/generate/index.js

@@ -226,7 +226,7 @@ function walk(dir) {
  * @returns {{ written: string[] }}
  */
 function generate(answers, target) {
-  if (fs.existsSync(target) && fs.readdirSync(target).length > 0) {
+  if (isOccupied(target)) {
     throw new Error(target + ' already exists and is not empty.');
   }
 
@@ -270,4 +270,9 @@ function generate(answers, target) {
   return { written: written.sort() };
 }
 
-module.exports = { generate: generate, substitutions: substitutions, fill: fill };
+/** A folder that exists and has something in it — generating there could overwrite work. */
+function isOccupied(target) {
+  return fs.existsSync(target) && fs.readdirSync(target).length > 0;
+}
+
+module.exports = { isOccupied: isOccupied, generate: generate, substitutions: substitutions, fill: fill };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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/api/development.env.tpl

@@ -56,3 +56,16 @@ AUTH_SUPER_ADMIN_PASSWORD=__ADMIN_PASSWORD__
 # email template can carry a token as a value but cannot build an address.
 AUTH_ACTIVATION_URL=http://localhost:__UI_PORT__/auth/activate
 AUTH_INVITE_URL=http://localhost:__UI_PORT__/auth/accept-invite
+
+# ── Email (optional) ──
+# Without it sign-in works, but activation, invite and password-reset links
+# cannot be sent. The sign-in service checks it at start and says so in its
+# banner: "email ✓ smtp — host:587, connected" or "✗ NOT WORKING — reason".
+# Providers: smtp | brevo | aws | azure — see @xeplr/utils' README.
+# EMAIL_PROVIDER=smtp
+# SMTP_HOST=
+# SMTP_PORT=587
+# SMTP_USER=
+# SMTP_PASS=
+# SMTP_FROM=
+# (smtp also needs `npm install nodemailer` in this folder)

package/templates/api/package.json

@@ -28,6 +28,6 @@
   },
   "devDependencies": {
     "dotenv-cli": "^8.0.0",
-    "@xeplr/cli": "^0.1.0"
+    "@xeplr/cli": "^0.1.6"
   }
 }

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`.

package/templates/ui/src/pages/TasksHelp.jsx

@@ -51,7 +51,7 @@ export default function TasksHelp() {
         new column as you publish.
       </p>
 
-      <h3>Or by hand</h3>
+      <h3>Or without code</h3>
       <p>
         <strong>Configure UI → Forms → New form</strong>: label and key, design,
         publish, add to menu — no code. The full steps for a form with its own page, hooks and