@xeplr/cli 0.1.3 → 0.1.4

package/README.md

@@ -28,15 +28,24 @@ 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 Designer page** — move, add and restyle fields, then Publish; the table
-  gains its new columns as you do. Only the admin roles see it, and the API
-  refuses everyone else.
+- **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.
 - **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.
+- **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):
+
+  > 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.
 
 ## Before you start
 

package/lib/generate/index.js

@@ -77,10 +77,8 @@ function tenancySubstitutions(levels) {
       '      // The ' + levels.map(function (l) { return l.table; }).join(' / ') + ' the picker lists and adds to.',
       "      '/api/tenants': tenants.router,"
     ].join('\n') : '',
-    __MT_FACTORY_AUTH__: on ? [
-      '        // …and only for a ' + first.label.toLowerCase() + ' the caller belongs to.',
-      '        auth: tenants.memberGate'
-    ].join('\n') : '',
+    __MT_MEMBER_GATE__: on ? 'tenants.memberGate' : 'access.anyone',
+    __MT_MEMBER_NOUN__: on ? levels.map(function (l) { return l.label.toLowerCase(); }).join(' and ') : 'data (no tenancy: nothing to check)',
 
     // ui/src/main.jsx
     __MT_UI_IMPORTS__: on ? [

package/lib/plan.js

@@ -30,6 +30,7 @@ function describe(answers) {
   L.push('');
   L.push('  Settings written for you:');
   L.push('    ' + p + '_PORT, AUTH_PORT, AUTH_URL, DB_API, AUTH_DB_NAME');
+  L.push('    REDIS_PREFIX                            ' + answers.name + ':');
   L.push('    ENCRYPTION_KEY and AUTH_JWT_SECRET      generated, not asked');
   L.push('    AUTH_SUPER_ADMIN_EMAIL / _PASSWORD      from your answers');
   L.push('');

package/package.json

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

package/templates/CLAUDE.md

@@ -0,0 +1,57 @@
+# __NAME__
+
+An xeplr app: `api/` (Node, @xeplr/base-apis, sign-in by @xeplr/auth) and `ui/` (React + Vite, @xeplr/ui-account).
+Forms are **screens** made with @xeplr/ui-factory and served by @xeplr/factory. The sample is **Tasks**.
+
+Read `api/node_modules/@xeplr/ui-factory/AUTHORING.md` for what screens, hooks and models mean. This file says where they go in **this** app.
+
+## Create a new UI
+
+A new UI is a **form**: a list, and an add / edit form it opens in a popup, saved in its own table. Use the singular for `<form>` (`farming_department`), the plural for the page (`FarmingDepartments`).
+
+Create every file below — the hooks and the model run the defaults (`super`) until the request needs more.
+
+1. **The spec** — `api/screens/<form>/<form>.entity.json`: the name and the fields in reading order. Copy `api/screens/task/task.entity.json`; the format is "The entity spec" in AUTHORING.md. A dropdown on another form's table needs that form to exist first.
+2. **Screens + server files** — from `api/`:
+   ```sh
+   npx xeplr-factory screens screens/<form>/<form>.entity.json -o screens/<form> --no-pages
+   npx xeplr-factory validate screens/<form>/<form>-edit.screen.json
+   npx xeplr-factory validate screens/<form>/<form>-list.screen.json
+   ```
+   Writes `<form>-list.screen.json`, `<form>-edit.screen.json`, `<form>.hooks.js` (server hooks), `<form>.model.js` (server model).
+3. **Register them** in `api/screens/index.js`: both screens in `documents` (edit before list), `<form>_edit: require('./<form>/<form>.hooks')` in `hooks`, `require('./<form>/<form>.model')` in `models`.
+4. **The form's page, with the front-end hooks** — `ui/src/pages/Edit<Form>.jsx`: copy `EditTask.jsx`; rename `TaskHooks` → `<Form>Hooks`, `taskHooks` → `<form>Hooks`, `'task_edit'` → `'<form>_edit'`. Keep every method calling `super`.
+5. **The list's page** — `ui/src/pages/<Forms>.jsx`: copy `Tasks.jsx`; load `'<form>_list'`, import `<form>Hooks` from `./Edit<Form>.jsx`, drop `TasksHelp`.
+6. **Route and side-rail item** — `ui/src/App.jsx`: import the list page, add `<Route path="/<forms>" element={<Forms />} />` next to `/tasks`, and a `drawerItems` entry with an **icon** (a collapsed rail shows icons only).
+7. **The menu row** — `api/migrations-auth/000N_<forms>_menu.sql` (next free number): copy `0002_tasks_menu.sql`, with the item's name spelled **exactly** as in `drawerItems` — an unknown name is dropped silently. Then, in `api/`: `npm run migrate:auth`, and restart the sign-in service (menus are cached for 10 minutes).
+8. **Restart the API.** It publishes screens that were never published — creating the table — and logs `[api] published screens: <form>_edit, <form>_list`.
+9. **Check** — open the page, New, fill in the form; the popup says "All changes saved" and the row is in the table.
+
+Then change only what the request asks for:
+
+| the request says… | change |
+|---|---|
+| a field, label, rule, dropdown, layout, colour | the screen JSON → validate → publish on the Forms page (or, never published yet, restart the API) |
+| hide / filter rows on screen, an extra button on each row, fill in a value before saving | front-end hooks — `ui/src/pages/Edit<Form>.jsx` |
+| must / only if / check against / email when / only managers see | server hooks — `api/screens/<form>/<form>.hooks.js` |
+| store as / convert / comma-separated ↔ array / work out X from Y | server model — `api/screens/<form>/<form>.model.js` |
+| a query in your own server code | `factory.table('<forms table>')` — this company, active rows, the model applied |
+
+**Without code:** Super Admin can also make a form on the **Forms** page (New form → design → Publish → Open). It gets no page, hooks or model files; add them with the steps above when it needs them.
+
+### The prompt
+
+> 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.
+
+Replace the bold parts. Add behaviour in the same message if you want it — "a Mark active button on each row", "Region is required when Area is over 100", "store tags as an array".
+
+## Rules
+
+- **Records live in real tables, one column per field — never JSON.** A screen's design is the only JSON, in the `factory_screens` table.
+- **Never rename a field that is already a column** — it would drop the column and its data. Add a new field instead.
+- A published screen's design lives in the **database**. Editing its `.screen.json` changes nothing afterwards: publish the change on the Forms page.
+- Every data address is under `/api` (a page and a data path must never collide). New routes go in `api/routes/index.js`, and `ui/vite.config.js` must proxy their prefix.
+- Designing and publishing are **Super Admin only** (`api/routes/access.js`); every other route checks the permission catalog.
+- The browser is not a security boundary: anything that must hold goes in server hooks.
+- Hooks and models are **methods** calling `super` — never arrow-function properties.
+- `authFetch` returns the parsed body, not a Response.

package/templates/api/app.js

@@ -1,8 +1,13 @@
 var createApp = require('@xeplr/base-apis/express');
 var factory = require('@xeplr/factory');
 var routes = require('./routes');
+var access = require('./routes/access');
 __MT_APP_REQUIRE__
 
+// Every screen route first checks the caller may use the request's
+// __MT_MEMBER_NOUN__.
+var memberGate = __MT_MEMBER_GATE__;
+
 // No `|| __API_PORT__` fallback — the port is required in env.required.js, so a
 // default could only ever fire in a process that skipped that check.
 var port = process.env.__PREFIX___PORT;
@@ -23,7 +28,7 @@ __MT_APP_MIDDLEWARE__
       '/': routes,
 __MT_APP_ROUTES__
 
-      // THE SCREENS — every entity made with the Designer, one set of routes:
+      // THE SCREENS — every form, one set of routes:
       //   /api/factory/screens/...   designs: load, save draft, publish
       //   /api/factory/records/...   a screen's records: list, one, save, delete
       //
@@ -33,7 +38,13 @@ __MT_APP_ROUTES__
       // Viewer (read) by node_modules/@xeplr/factory/migrations-auth.
       '/api': factory.router({
         access: true,
-__MT_FACTORY_AUTH__
+        auth: {
+          view: memberGate,
+          write: memberGate,
+          // Designing, new forms and publishing change tables: Super Admin
+          // only (routes/access.js).
+          design: [memberGate, access.superAdminOnly]
+        }
       })
     })
   });

package/templates/api/bin/www

@@ -58,12 +58,13 @@ async function start() {
   // time has no connection at all until this has finished.
   var knex = await require('../db/setup');
 
-  // The screens. A hooks file with a typo ("beforeSave") stops startup here,
-  // rather than silently never running.
-  await factory.init({ knex: knex, hooks: screens.hooks });
+  // The screens, their hooks and their models. A hooks file with a typo
+  // ("beforeSave") or a malformed model stops startup here, rather than
+  // silently never running.
+  await factory.init({ knex: knex, hooks: screens.hooks, models: screens.models });
 
   // Screens never published yet are published now, creating their tables.
-  // Ones already published are left alone — the Designer owns them.
+  // Ones already published are left alone — the Forms page owns them.
   var published = await factory.publishScreens(screens.documents);
   if (published.published.length) console.log('[api] published screens: ' + published.published.join(', '));
 

package/templates/api/development.env.tpl

@@ -29,6 +29,11 @@ AUTH_DB_NAME=__NAME___auth
 # localhost:6379; set REDIS_HOST / REDIS_PORT to point elsewhere. Without it
 # the service refuses to start and says so — rather than letting every login
 # succeed and every request afterwards fail as "Invalid or expired token".
+#
+# REDIS_PREFIX keeps this app's keys apart from any other app on the same
+# Redis. Required, and unique per app: two apps sharing one see each other's
+# menus and permissions.
+REDIS_PREFIX=__NAME__:
 AUTH_PORT=__AUTH_PORT__
 AUTH_JWT_SECRET=__JWT_SECRET__
 

package/templates/api/env.required.js

@@ -9,7 +9,7 @@
  */
 module.exports = [
   // ENCRYPTION_KEY, AUTH_JWT_SECRET, AUTH_PORT, AUTH_DB_NAME,
-  // XEPLR_AUTH_MIGRATIONS
+  // XEPLR_AUTH_MIGRATIONS, AUTH_SUPER_ADMIN_EMAIL / _PASSWORD, REDIS_PREFIX
   ...require('@xeplr/auth').requiredEnv,
 
   // ── this app's own ──

package/templates/api/migrations/README.md

@@ -4,6 +4,6 @@ Hand-written `.sql` files, applied once each, in name order, every time the API
 starts (`0001_something.sql`, `0002_…`).
 
 **Tables for screens are not written here.** A screen's table (`tasks`) is
-created and changed by **Publish** in the Designer page — see `screens/`.
+created and changed by **Publish** on the Forms page — see `screens/`.
 
 Put here only tables no screen owns: lookup data, a table your own code writes.

package/templates/api/migrations-auth/0003_forms_menu.sql

@@ -0,0 +1,19 @@
+-- "Forms" — the drawer item for every form in the app: see them, make a new
+-- one, design it, publish it (ui/src/pages/Forms.jsx).
+--
+-- SUPER ADMIN ONLY: publishing changes database tables. The API refuses
+-- everyone else as well (api/routes/access.js); this keeps the menu honest
+-- about it.
+--
+-- The name must match ui/src/App.jsx's drawerItems entry EXACTLY.
+
+INSERT INTO "menus" (id, name, "menuGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), 'Forms', '', false, true, '*', now(), now()
+WHERE NOT EXISTS (SELECT 1 FROM "menus" WHERE name = 'Forms');
+
+INSERT INTO "menuRolesMapping" (id, "roleId", "menuId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), r.id, m.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "menus" m
+WHERE r.name = 'Super Admin'
+  AND m.name = 'Forms'
+  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);

package/templates/api/models/index.js

@@ -2,7 +2,7 @@
 // class extending @xeplr/db's BaseModel, handed to genericRoute in
 // routes/index.js.
 //
-// Tables made with the Designer (screens/) need no model: @xeplr/factory saves
+// Tables made as forms (Forms page, screens/) need no model: @xeplr/factory saves
 // and reads them from the screen itself.
 
 module.exports = {};

package/templates/api/package.json

@@ -20,7 +20,8 @@
     "@xeplr/auth": "^1.1.2",
     "@xeplr/base-apis": "^2.0.0",
     "@xeplr/db": "^1.0.6",
-    "@xeplr/factory": "^1.0.3",
+    "@xeplr/factory": "^1.0.4",
+    "@xeplr/ui-factory": "^1.0.5",
     "@xeplr/utils": "^1.0.8",
     "dotenv": "^17.4.2",
     "express": "^5.2.0"

package/templates/api/routes/access.js

@@ -0,0 +1,25 @@
+// WHO MAY DO WHAT — beyond the permission catalog every route already checks.
+//
+// Designing screens, making new forms and publishing them change the
+// database's tables, so they are kept to Super Admin alone, whatever else a
+// role has been granted. Relax superAdminOnly here when your app has decided
+// who else should.
+
+var FORBIDDEN = { code: 'FORBIDDEN', message: 'Only Super Admin can design and publish forms', error: null, dataArray: [] };
+
+function isSuperAdmin(req) {
+  var roles = (req.access && req.access.roles) || (req.user && req.user.roles) || [];
+  return roles.indexOf('Super Admin') !== -1;
+}
+
+function superAdminOnly(req, res, next) {
+  if (isSuperAdmin(req)) return next();
+  res.status(403).send(FORBIDDEN);
+}
+
+/** No check of its own — the token and the permission catalog still apply. */
+function anyone(req, res, next) {
+  next();
+}
+
+module.exports = { isSuperAdmin: isSuperAdmin, superAdminOnly: superAdminOnly, anyone: anyone };

package/templates/api/routes/index.js

@@ -26,7 +26,7 @@ router.get('/whoami', function(req, res) {
 // path which to forward. Serve data at /tasks and the UI's own /tasks page is
 // shadowed by it — opening that page shows raw JSON instead of the app.
 //
-// Screens made in the Designer (tasks) need nothing here — @xeplr/factory
+// Forms (tasks, and any made on the Forms page) need nothing here — @xeplr/factory
 // serves them at /api/factory/..., mounted in app.js.
 //
 // A table you write by hand gets its four addresses from one line:

package/templates/api/screens/index.js

@@ -6,16 +6,18 @@
 //
 // On startup (bin/www) every screen here that has never been published is
 // published — which creates its table. After that the DATABASE holds the
-// design: change it in the app's Designer page, where Publish changes the
+// design: change it on the app's Forms page, where Publish changes the
 // table to match. Editing a .screen.json later changes nothing for an
 // already-published screen.
 //
-// ADD AN ENTITY:
+// ADD ONE: follow "Create a new UI" in the project's CLAUDE.md — or ask Claude
+// to, with the prompt there. Every form's folder holds the same files:
 //
-//   npx xeplr-factory screens screens/project/project.entity.json -o screens/project
-//
-// then list its two screens and its hooks below, and add a page and a menu
-// entry for it (see the UI's src/pages/Tasks.jsx and migrations-auth/).
+//   screens/<form>/<form>.entity.json       its name and fields
+//   screens/<form>/<form>-list.screen.json  the list
+//   screens/<form>/<form>-edit.screen.json  the add / edit form
+//   screens/<form>/<form>.hooks.js          server hooks — save / get / delete
+//   screens/<form>/<form>.model.js          server model — getters / setters
 
 module.exports = {
   // Publish order is worked out for you: a table before the dropdowns that
@@ -28,5 +30,10 @@ module.exports = {
   // Your own code around save / get / delete, per screen — see task/task.hooks.js.
   hooks: {
     task_edit: require('./task/task.hooks')
-  }
+  },
+
+  // How each table's values are shaped — see task/task.model.js.
+  models: [
+    require('./task/task.model')
+  ]
 };

package/templates/api/screens/task/task.model.js

@@ -0,0 +1,29 @@
+// The model for task records — how values are shaped between your code and
+// the "tasks" table, like Sequelize's getters and setters.
+//
+// Register with @xeplr/factory:  factory.init({ knex, hooks, models: [require('./task.model')] })
+//
+// Used everywhere: the screens' routes and factory.table('tasks'). Models shape
+// data; the hooks file decides behaviour.
+
+var { FactoryModel } = require('@xeplr/factory');
+
+class TaskModel extends FactoryModel {
+  static table = 'tasks';
+
+  // Per field: set(value, values) before it is written, get(value, row) after it is read.
+  //   tags: { set: (v) => (Array.isArray(v) ? v.join(',') : v), get: (v) => (v ? v.split(',') : []) }
+  static fields = {};
+
+  /** Every value about to be written. Override for more than one field at a time. */
+  static toDb(values) {
+    return super.toDb(values);
+  }
+
+  /** Every row just read. */
+  static fromDb(row) {
+    return super.fromDb(row);
+  }
+}
+
+module.exports = TaskModel;

package/templates/ui/package.json

@@ -12,7 +12,7 @@
     "@tanstack/react-table": "^8.21.3",
     "@xeplr/ui-account": "^1.0.6",
     "@xeplr/ui-canvas": "^1.0.2",
-    "@xeplr/ui-factory": "^1.0.4",
+    "@xeplr/ui-factory": "^1.0.5",
     "@xeplr/ui-table": "^1.0.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",

package/templates/ui/src/App.jsx

@@ -3,7 +3,9 @@ import { Routes, Route, Outlet, Navigate, useNavigate } from 'react-router-dom'
 import { authRoutes, authPath, NavPage, ProtectedRoute } from '@xeplr/ui-account'
 import Home from './pages/Home.jsx'
 import Tasks from './pages/Tasks.jsx'
-import Designer from './pages/Designer.jsx'
+import Forms from './pages/Forms.jsx'
+import FormDesigner from './pages/FormDesigner.jsx'
+import FormRecords from './pages/FormRecords.jsx'
 __MT_APP_UI_IMPORTS__
 
 // The rail is ICON-ONLY when collapsed, so a drawer item without one is
@@ -17,7 +19,7 @@ const TasksIcon = (
   </svg>
 )
 
-const DesignerIcon = (
+const FormsIcon = (
   <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
        strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
     <rect x="3" y="3" width="18" height="18" rx="2" />
@@ -54,8 +56,8 @@ function Shell() {
   const drawerItems = useMemo(() => [
     { name: 'Home', icon: HomeIcon, clickHandler: () => navigate('/home') },
     { name: 'Tasks', icon: TasksIcon, clickHandler: () => navigate('/tasks') },
-    // Shown only to roles given the "Designer" menu (migrations-auth/0003).
-    { name: 'Designer', icon: DesignerIcon, clickHandler: () => navigate('/designer') },
+    // Super Admin only — the "Forms" menu (migrations-auth/0003).
+    { name: 'Forms', icon: FormsIcon, clickHandler: () => navigate('/forms') },
 __MT_DRAWER_ITEM__
   ], [navigate])
 
@@ -91,7 +93,9 @@ __MT_SELECT_ROUTE__
         <Route path="/" element={<Navigate to="/home" replace />} />
         <Route path="/home" element={<Home />} />
         <Route path="/tasks" element={<Tasks />} />
-        <Route path="/designer" element={<Designer />} />
+        <Route path="/forms" element={<Forms />} />
+        <Route path="/forms/:form" element={<FormRecords />} />
+        <Route path="/forms/:form/design/:part" element={<FormDesigner />} />
       </Route>
 
       <Route path="*" element={<Navigate to="/auth/login" replace />} />

package/templates/ui/src/api/factory.js

@@ -1,4 +1,4 @@
-// MODEL LAYER — every call the screens and the Designer make, to the API's
+// MODEL LAYER — every call the screens and the Forms pages make, to the API's
 // @xeplr/factory routes (mounted at /api in api/app.js).
 //
 // authFetch attaches the signed-in user's token (and the active company, when

package/templates/ui/src/index.css

@@ -274,6 +274,30 @@ body { margin: 0; }
   .app-help { position: static; margin-top: 28px; width: auto; }
 }
 
+/* ── Forms ────────────────────────────────────────────────────────────── */
+.app-forms-new { display: flex; gap: 8px; max-width: 640px; margin: 0 0 18px; }
+
+.app-forms-new input {
+  flex: 1;
+  padding: 9px 11px;
+  border-radius: 6px;
+  border: 1px solid var(--xeplr-input-border);
+  background: var(--xeplr-input-bg);
+  color: var(--xeplr-input-text);
+  font: inherit;
+}
+
+.app-forms-pending { color: var(--xeplr-warning); }
+
+.app-notice {
+  margin: 0 0 14px;
+  padding: 10px 14px;
+  border-radius: 6px;
+  border: 1px solid var(--xeplr-success-border);
+  background: var(--xeplr-success-bg);
+  color: var(--xeplr-success);
+}
+
 /* ── Designer ─────────────────────────────────────────────────────────── */
 /* The builder fills the space it is given, so it needs a height: the page
    below the top bar, less .main's padding. */
@@ -298,3 +322,14 @@ body { margin: 0; }
   border-radius: 8px;
   overflow: hidden;
 }
+
+.app-help-prompt {
+  white-space: pre-wrap;
+  font-size: 12px;
+  line-height: 1.5;
+  padding: 10px 12px;
+  margin: 8px 0;
+  border-radius: 6px;
+  background: var(--xeplr-bg-tertiary);
+  border: 1px solid var(--xeplr-border-primary);
+}

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

@@ -0,0 +1,57 @@
+// THE TASK FORM — and what the task screens do in the browser.
+//
+// The form itself is the "task_edit" screen, designed on the Forms page. This
+// module holds its HOOKS, used by this page, by the Tasks list and by the
+// popup the list opens.
+import { useEffect, useState } from 'react'
+import { FactoryScreen, FactoryHooks } from '@xeplr/ui-factory'
+import { factory } from '../api/factory.js'
+
+// ── WHAT THE TASK SCREENS DO IN THE BROWSER ──────────────────────────────
+// Every method runs the default (super). Change the ones you need; leave the
+// rest as they are.
+//
+//   before    change the input, then call super
+//   after     call super, then use or change what it returns
+//   override  do not call super
+//
+// ctx.screen says which screen is calling ("task_list" or "task_edit").
+// Keep them as methods (save(values, ctx) { … }) — super does not work in
+// arrow functions. Rules that must hold belong in the server's hooks
+// (api/screens/task/task.hooks.js).
+export class TaskHooks extends FactoryHooks {
+  /** A list's rows (ctx.many), or the record Edit opens (ctx.id). */
+  get(ctx) {
+    return super.get(ctx)
+  }
+
+  /** Every autosave — keep it quick. Returns the saved record. */
+  save(values, ctx) {
+    return super.save(values, ctx)
+  }
+
+  /** A list row, after the person confirmed. */
+  delete(record, ctx) {
+    return super.delete(record, ctx)
+  }
+
+  /** Extra row buttons beside Edit / Delete: [{ label, onClick: (record, ctx) => … }]. ctx.refresh() reloads. */
+  actions(ctx) {
+    return super.actions(ctx)
+  }
+}
+
+export const taskHooks = new TaskHooks()
+
+/** The task form on a page of its own: <EditTask /> for a new task, <EditTask record={task} /> for one. */
+export default function EditTask({ record }) {
+  const [screen, setScreen] = useState(null)
+  const [error, setError] = useState(null)
+
+  useEffect(() => {
+    factory.loadScreen('task_edit').then(setScreen, (e) => setError(e.message))
+  }, [])
+
+  if (error) return <div className="app-error">Could not load the task form — {error}</div>
+  return screen ? <FactoryScreen document={screen} record={record} {...factory.screenProps} hooks={taskHooks} /> : null
+}

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

@@ -0,0 +1,74 @@
+// DESIGN ONE FORM — its add / edit form, or its list. Move and resize fields,
+// add new ones, change labels, rules, fonts and colours.
+//
+// Edits are kept as a DRAFT automatically; nobody sees them until Publish,
+// which also changes the table to match: a new field adds a column; removing
+// one asks first, because its column and every value in it would be deleted.
+import { useCallback, useEffect, useState } from 'react'
+import { useNavigate, useParams } from 'react-router-dom'
+import { FactoryBuilder } from '@xeplr/ui-factory'
+import { factory } from '../api/factory.js'
+
+const PARTS = [
+  { part: 'form', suffix: '_edit', label: 'Form' },
+  { part: 'list', suffix: '_list', label: 'List' }
+]
+
+export default function FormDesigner() {
+  const { form, part } = useParams()
+  const navigate = useNavigate()
+  const screenKey = form + (part === 'list' ? '_list' : '_edit')
+  const [current, setCurrent] = useState(null)      // { key, document, lockedNames }
+  const [error, setError] = useState(null)
+
+  useEffect(() => {
+    let cancelled = false
+    setCurrent(null)
+    // The draft if there is one, else the published version — with the field
+    // names that are already columns, which cannot be renamed.
+    factory.loadDraft(screenKey).then(
+      (row) => { if (!cancelled) { setCurrent({ key: screenKey, document: row.document, lockedNames: row.lockedNames || [] }); setError(null) } },
+      (e) => { if (!cancelled) setError(e.message) }
+    )
+    return () => { cancelled = true }
+  }, [screenKey])
+
+  const publish = useCallback(async (doc, options) => {
+    const result = await factory.publish(doc, options)
+    const row = await factory.loadDraft(doc.id)
+    setCurrent((c) => (c && c.key === doc.id ? { ...c, lockedNames: row.lockedNames || [] } : c))
+    return result
+  }, [])
+
+  return (
+    <div className="app-designer">
+      <div className="app-designer-bar">
+        <button type="button" className="app-btn app-btn-quiet" onClick={() => navigate('/forms')}>← Forms</button>
+        <span className="app-designer-title">{current ? current.document.name : form}</span>
+        {PARTS.map((p) => (
+          <button
+            key={p.part}
+            type="button"
+            className={'app-btn app-btn-quiet' + ((part === 'list') === (p.part === 'list') ? ' is-active' : '')}
+            onClick={() => navigate('/forms/' + form + '/design/' + p.part)}
+          >
+            {p.label}
+          </button>
+        ))}
+      </div>
+      {error && <div className="app-error">{error}</div>}
+      {current && (
+        <div className="app-designer-canvas">
+          <FactoryBuilder
+            key={current.key}
+            {...factory.builderProps}
+            document={current.document}
+            lockedNames={current.lockedNames}
+            onPublish={publish}
+            screens={PARTS.map((p) => ({ id: form + p.suffix, name: p.label }))}
+          />
+        </div>
+      )}
+    </div>
+  )
+}

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

@@ -0,0 +1,24 @@
+// USE ANY FORM — its published list, with New / Edit opening the form in a
+// popup. Tasks.jsx is the same thing for one form, with a help panel beside it.
+import { useEffect, useState } from 'react'
+import { useParams } from 'react-router-dom'
+import { FactoryScreen } from '@xeplr/ui-factory'
+import { factory } from '../api/factory.js'
+
+export default function FormRecords() {
+  const { form } = useParams()
+  const [screen, setScreen] = useState(null)
+  const [error, setError] = useState(null)
+
+  useEffect(() => {
+    setScreen(null)
+    factory.loadScreen(form + '_list').then((doc) => { setScreen(doc); setError(null) }, (e) => setError(e.message))
+  }, [form])
+
+  return (
+    <div className="app-page">
+      {error && <div className="app-error">Could not open this form — {error}</div>}
+      {screen && <FactoryScreen key={form} document={screen} {...factory.screenProps} />}
+    </div>
+  )
+}

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

@@ -0,0 +1,144 @@
+// FORMS — every form in the app, for Super Admin: see them, make a new one,
+// design it, publish it, open it.
+//
+// A form is two screens: a LIST of its records, and the add / edit FORM the
+// list opens in a popup. Records live in an ordinary table named for the form
+// ("farming_departments"), created when the form is first published.
+//
+// Claude can make forms too (api/screens/, `npx xeplr-factory screens`); this
+// page is the same thing by hand.
+import { useCallback, useEffect, useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { factory } from '../api/factory.js'
+
+/** listScreens rows → one entry per form: { key, name, source, list, edit }. */
+function groupForms(rows) {
+  const byKey = new Map()
+  rows.forEach((row) => {
+    const m = /^(.*)_(list|edit)$/.exec(row.screenKey)
+    const key = m ? m[1] : row.screenKey
+    const entry = byKey.get(key) || { key, name: null, source: null, list: null, edit: null }
+    if (m) entry[m[2]] = row
+    else entry.edit = row
+    if (m && m[2] === 'list') entry.name = row.name
+    entry.name = entry.name || row.name
+    entry.source = entry.source || row.source
+    byKey.set(key, entry)
+  })
+  return [...byKey.values()].sort((a, b) => String(a.name).localeCompare(String(b.name)))
+}
+
+function state(screen) {
+  if (!screen) return { label: '—', unpublished: false }
+  if (screen.version === null) return { label: 'Not published yet', unpublished: true }
+  return { label: 'v' + screen.version + (screen.hasDraft ? ' · unpublished changes' : ''), unpublished: screen.hasDraft }
+}
+
+export default function Forms() {
+  const navigate = useNavigate()
+  const [forms, setForms] = useState(null)
+  const [error, setError] = useState(null)
+  const [notice, setNotice] = useState(null)
+  const [name, setName] = useState('')
+  const [busy, setBusy] = useState(null)
+
+  const load = useCallback(() => {
+    factory.listScreens().then((rows) => { setForms(groupForms(rows)); setError(null) }, (e) => setError(e.message))
+  }, [])
+  useEffect(load, [load])
+
+  const create = async (e) => {
+    e.preventDefault()
+    setBusy('new')
+    try {
+      const made = await factory.createEntity({ entity: name })
+      // Straight into its form, to add the fields.
+      navigate('/forms/' + made.edit.replace(/_edit$/, '') + '/design/form')
+    } catch (err) {
+      setError(err.message)
+      setBusy(null)
+    }
+  }
+
+  // The form first — publishing it creates or changes the table — then the list.
+  const publish = async (form) => {
+    setBusy(form.key)
+    setNotice(null)
+    try {
+      for (const screen of [form.edit, form.list]) {
+        if (!screen || (screen.version !== null && !screen.hasDraft)) continue
+        const row = await factory.loadDraft(screen.screenKey)
+        await factory.publish(row.document)
+      }
+      setNotice('Published "' + form.name + '"')
+      setError(null)
+      load()
+    } catch (err) {
+      // Removing a field drops its column — that is confirmed in the designer,
+      // where the columns and their values are shown.
+      setError(err.confirm
+        ? 'Publishing "' + form.name + '" would remove columns and their data — open Design form and publish there to see what, and confirm.'
+        : err.message)
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  return (
+    <div className="app-page app-forms">
+      <h1>Forms</h1>
+      <p className="app-page-lead">
+        Every form in the app. A new one starts with a Name field — add the rest in its design, then publish to create its table.
+      </p>
+
+      <form className="app-forms-new" onSubmit={create}>
+        <input
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          placeholder='New form — one record is a… e.g. "farming department"'
+          aria-label="New form name"
+        />
+        <button type="submit" className="app-btn" disabled={!name.trim() || busy === 'new'}>
+          {busy === 'new' ? 'Creating…' : 'New form'}
+        </button>
+      </form>
+
+      {error && <div className="app-error">{error}</div>}
+      {notice && <div className="app-notice">{notice}</div>}
+
+      {forms && forms.length === 0 && <p className="app-sub">No forms yet.</p>}
+      {forms && forms.length > 0 && (
+        <table className="app-table">
+          <thead>
+            <tr><th>Name</th><th>Table</th><th>Form</th><th>List</th><th /></tr>
+          </thead>
+          <tbody>
+            {forms.map((form) => {
+              const edit = state(form.edit)
+              const list = state(form.list)
+              const canOpen = form.list && form.list.version !== null
+              return (
+                <tr key={form.key}>
+                  <td><strong>{form.name || form.key}</strong><div className="app-sub">{form.key}</div></td>
+                  <td><code>{form.source || '—'}</code></td>
+                  <td className={edit.unpublished ? 'app-forms-pending' : undefined}>{edit.label}</td>
+                  <td className={list.unpublished ? 'app-forms-pending' : undefined}>{list.label}</td>
+                  <td className="app-row-actions">
+                    <button className="app-btn app-btn-quiet" disabled={!canOpen} title={canOpen ? '' : 'Publish it first'} onClick={() => navigate('/forms/' + form.key)}>Open</button>
+                    {form.edit && <button className="app-btn app-btn-quiet" onClick={() => navigate('/forms/' + form.key + '/design/form')}>Design form</button>}
+                    {form.list && <button className="app-btn app-btn-quiet" onClick={() => navigate('/forms/' + form.key + '/design/list')}>Design list</button>}
+                    {(edit.unpublished || list.unpublished) && (
+                      <button className="app-btn" disabled={busy === form.key} onClick={() => publish(form)}>
+                        {busy === form.key ? 'Publishing…' : 'Publish'}
+                      </button>
+                    )}
+                  </td>
+                </tr>
+              )
+            })}
+          </tbody>
+        </table>
+      )}
+    </div>
+  )
+}

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

@@ -59,8 +59,8 @@ export default function Home() {
           sample logo, in the top bar and the side rail.
         </li>
         <li>
-          <strong>Designer</strong>, in the side rail — change the sample task
-          screens, or see how they are made. Publish changes the table too.
+          <strong>Forms</strong>, in the side rail — make a new form, or change the
+          sample task screens. Publish creates or changes the table too.
         </li>
         <li>
           <code>src/App.jsx</code> — add your own pages, and the side-rail items

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

@@ -2,12 +2,14 @@
 // where it saves itself as you type; there is no Save button.
 //
 // Nothing about tasks is written in this file. The list and the form are
-// SCREENS, designed in the Designer page and stored by the API; this page only
-// loads the published "task_list" and hands it the calls it needs.
+// SCREENS, designed on the Forms page and stored by the API; this page only
+// loads the published "task_list" and hands it the calls it needs — and the
+// task hooks (EditTask.jsx), which the popup uses too.
 import { useEffect, useState } from 'react'
 import { FactoryScreen } from '@xeplr/ui-factory'
 import { factory } from '../api/factory.js'
 import TasksHelp from './TasksHelp.jsx'
+import { taskHooks } from './EditTask.jsx'
 
 export default function Tasks() {
   const [screen, setScreen] = useState(null)
@@ -22,7 +24,7 @@ export default function Tasks() {
       <div className="app-page-main">
         {error && <div className="app-error">Could not load the task list — {error}</div>}
         {/* loadScreen lets the list's Edit / New fetch "task_edit" when first opened. */}
-        {screen && <FactoryScreen document={screen} {...factory.screenProps} />}
+        {screen && <FactoryScreen document={screen} {...factory.screenProps} hooks={taskHooks} />}
       </div>
       <TasksHelp />
     </div>

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

@@ -1,11 +1,41 @@
+import { useState } from 'react'
+
 // The panel beside the sample. It is here so the first thing anybody builds is
 // explained where they are looking, rather than in a document they have to go
 // and find.
+
+// The same prompt as in CLAUDE.md. Replace the form and its fields.
+const PROMPT = '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.'
+
 export default function TasksHelp() {
+  const [copied, setCopied] = useState(false)
+  const copy = () => {
+    navigator.clipboard.writeText(PROMPT).then(() => {
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    }, () => {})
+  }
+
   return (
     <aside className="app-help">
       <div className="app-help-badge">Sample</div>
-      <h2>This page is an example</h2>
+      <h2>Create your own UI with Claude</h2>
+      <p>
+        Open Claude in this project's folder (the one with <code>api</code> and{' '}
+        <code>ui</code>) and give it this — change the name and the fields:
+      </p>
+      <pre className="app-help-prompt">{PROMPT}</pre>
+      <button type="button" className="app-btn app-btn-quiet" onClick={copy}>
+        {copied ? 'Copied' : 'Copy prompt'}
+      </button>
+      <p>
+        Add behaviour in the same message if you want it — "a Mark active button
+        on each row", "Region is required when Area is over 100". When Claude is
+        done, restart the sign-in service and the API: the menu item appears and
+        the table is created.
+      </p>
+
+      <h3>This page is an example</h3>
       <p>
         A task has a title, a status, a due date and a description. Neither the
         list nor the form is written by hand — both are <strong>screens</strong>,
@@ -15,44 +45,28 @@ export default function TasksHelp() {
 
       <h3>Change it</h3>
       <p>
-        Open <strong>Designer</strong> in the side rail. Add a field, move one,
-        change a label or a colour — then <strong>Publish</strong>. The table
-        gains its new column as you publish.
+        Open <strong>Forms</strong> in the side rail and{' '}
+        <strong>Design form</strong> on Tasks. Add a field, move one, change a
+        label or a colour — then <strong>Publish</strong>. The table gains its
+        new column as you publish.
       </p>
 
-      <h3>Add your own</h3>
-      <ol className="app-help-steps">
-        <li>
-          <strong>Describe it</strong>
-          <code>api/screens/project/project.entity.json</code>
-          <span>Its name and fields — copy <code>task/task.entity.json</code>.</span>
-        </li>
-        <li>
-          <strong>Make its screens</strong>
-          <code>npx xeplr-factory screens screens/project/project.entity.json -o screens/project</code>
-          <span>From the api folder. Then list them in <code>api/screens/index.js</code>.</span>
-        </li>
-        <li>
-          <strong>The page</strong>
-          <code>ui/src/pages/Projects.jsx</code>
-          <span>Copy <code>Tasks.jsx</code> and load <code>project_list</code>.</span>
-        </li>
-        <li>
-          <strong>The menu entry</strong>
-          <code>api/migrations-auth/000N_projects_menu.sql</code>
-          <span>
-            The side-rail item appears only if its name exists in the database,
-            spelled exactly the same.
-          </span>
-        </li>
-      </ol>
-      <p>Restart the API and the new table is created for you.</p>
+      <h3>Or by hand</h3>
+      <p>
+        <strong>Forms → New form</strong>: name it, design it, publish it, open
+        it — no code. The full steps for a form with its own page, hooks and
+        model are in <code>CLAUDE.md</code>, under "Create a new UI".
+      </p>
 
       <h3>More than saving</h3>
       <p>
-        A value worked out on save, an email afterwards, a list only managers
-        see: <code>api/screens/task/task.hooks.js</code> — before, after, error
-        and override, for save, get and delete.
+        In the browser — a value added before saving, rows filtered for display,
+        an extra button on each row: <code>ui/src/pages/EditTask.jsx</code>.
+        Every method calls <code>super</code>; change the one you need.
+      </p>
+      <p>
+        On the server — a check against other records, an email afterwards, a
+        list only managers see: <code>api/screens/task/task.hooks.js</code>.
       </p>
 
       <h3>Two things that catch people</h3>
@@ -60,7 +74,7 @@ export default function TasksHelp() {
         <li>
           Once a screen is published, the <em>database</em> holds its design.
           Editing its <code>.screen.json</code> afterwards changes nothing — use
-          the Designer.
+          Forms.
         </li>
         <li>
           A new menu entry is remembered for ten minutes. Restart the sign-in

package/templates-tenancy/api/routes/tenants.js

@@ -18,6 +18,7 @@ var { respond } = require('@xeplr/utils/lib/response');
 var { HTTP, STATUS } = require('@xeplr/utils/isomorphic');
 var authLib = require('@xeplr/auth');
 var tenancy = require('../tenancy');
+var { isSuperAdmin } = require('./access');
 var appDatabase = require('../db/setup');
 
 // The sign-in database, read directly — this app does not run the sign-in
@@ -29,11 +30,6 @@ var auth = authLib.attach();
 var CREATOR_ROLE = { 1: 'CompanyAdmin' };
 var DEEPER_ROLE = 'Creator';
 
-function isSuperAdmin(req) {
-  var roles = (req.access && req.access.roles) || (req.user && req.user.roles) || [];
-  return roles.indexOf('Super Admin') !== -1;
-}
-
 var membership = null;
 
 /**

package/templates/api/migrations-auth/0003_designer_menu.sql

@@ -1,19 +0,0 @@
--- "Designer" — the drawer item for designing screens (ui/src/pages/Designer.jsx).
---
--- NOT public: Publish changes database tables, so only the roles that hold
--- @xeplr/factory's design permission see the item. The API refuses everyone
--- else anyway ("Access denied: Publish factory screen"); this keeps the menu
--- honest about it.
---
--- The name must match ui/src/App.jsx's drawerItems entry EXACTLY.
-
-INSERT INTO "menus" (id, name, "menuGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
-SELECT encode(gen_random_bytes(12), 'hex'), 'Designer', '', false, true, '*', now(), now()
-WHERE NOT EXISTS (SELECT 1 FROM "menus" WHERE name = 'Designer');
-
-INSERT INTO "menuRolesMapping" (id, "roleId", "menuId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
-SELECT encode(gen_random_bytes(12), 'hex'), r.id, m.id, true, '*', now(), now()
-FROM "roles" r CROSS JOIN "menus" m
-WHERE r.name IN ('Super Admin', 'CompanyAdmin')
-  AND m.name = 'Designer'
-  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);

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

@@ -1,74 +0,0 @@
-// THE DESIGNER — change any screen: move and resize fields, add new ones,
-// change labels, rules, fonts and colours.
-//
-// Your edits are kept as a DRAFT automatically. Nobody else sees them until
-// you press Publish, which also changes the screen's database table to match:
-// a new field adds a column; removing one asks first, because its column and
-// every value in it would be deleted.
-import { useCallback, useEffect, useState } from 'react'
-import { FactoryBuilder } from '@xeplr/ui-factory'
-import { factory } from '../api/factory.js'
-
-export default function Designer() {
-  const [screens, setScreens] = useState([])
-  const [current, setCurrent] = useState(null)      // { key, document, lockedNames }
-  const [error, setError] = useState(null)
-
-  useEffect(() => {
-    factory.listScreens().then((rows) => {
-      setScreens(rows)
-      if (rows.length) open(rows[0].screenKey)
-    }, (e) => setError(e.message))
-  }, [])                                              // eslint-disable-line react-hooks/exhaustive-deps
-
-  const open = useCallback(async (key) => {
-    try {
-      // The draft if there is one, else the published version — with the field
-      // names that are already columns, which the Designer will not let you rename.
-      const row = await factory.loadDraft(key)
-      setCurrent({ key, document: row.document, lockedNames: row.lockedNames || [] })
-      setError(null)
-    } catch (e) {
-      setError(e.message)
-    }
-  }, [])
-
-  const publish = useCallback(async (doc, options) => {
-    const result = await factory.publish(doc, options)
-    // New columns are now locked names too.
-    const row = await factory.loadDraft(doc.id)
-    setCurrent((c) => (c && c.key === doc.id ? { ...c, lockedNames: row.lockedNames || [] } : c))
-    return result
-  }, [])
-
-  return (
-    <div className="app-designer">
-      <div className="app-designer-bar">
-        <span className="app-designer-title">Designer</span>
-        {screens.map((s) => (
-          <button
-            key={s.screenKey}
-            type="button"
-            className={'app-btn app-btn-quiet' + (current && current.key === s.screenKey ? ' is-active' : '')}
-            onClick={() => open(s.screenKey)}
-          >
-            {s.name || s.screenKey}
-          </button>
-        ))}
-      </div>
-      {error && <div className="app-error">{error}</div>}
-      {current && (
-        <div className="app-designer-canvas">
-          <FactoryBuilder
-            key={current.key}
-            {...factory.builderProps}
-            document={current.document}
-            lockedNames={current.lockedNames}
-            onPublish={publish}
-            screens={screens.map((s) => ({ id: s.screenKey, name: s.name || s.screenKey }))}
-          />
-        </div>
-      )}
-    </div>
-  )
-}