@xeplr/cli 0.3.3 → 0.3.5

package/README.md

@@ -41,6 +41,19 @@ Already working, with nothing to wire up:
   - **Menu**: rename, reorder and hide the side rail's items.
 
   Nobody else sees it, and the API refuses everyone else.
+- **Flows, in every app** — your forms one after another. Designed in
+  Configure UI → Flows: for each screen, the app's functions that run around
+  its records (its events) and where the journey goes once it is saved — a
+  screen, a function that decides, or the end. Walked at `/journey/<key>`, and
+  resumable. Run by `@xeplr/workflow-api` **inside the API**, in a database of
+  its own (`<name>_workflow`, created on first start) — nothing extra to start.
+  It follows the app's tenancy (none, or the levels you chose) and never creates
+  companies or workspaces of its own. Approvals (another person's turn) are not
+  part of it.
+- **Functions** — `api/functions/`: the app's own code, registered with
+  `@xeplr/actions` by the event it is for (`beforeSave`, `afterSave`, …,
+  `decide`) and picked by name in a screen's events or a flow step. Two to start
+  from: `tidyTaskTitle` (Tasks' `beforeSave`) and `byPriority` (a `decide`).
 - **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,
@@ -71,7 +84,7 @@ These are architecture decisions, not defaults to tune — each one exists becau
 | **`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` | |
-| **Anything every app would write identically lives in a package, not in the generated app.** A generated app is a starting point that then lives its own life — glue copied into it can never be fixed centrally, so an app made last month keeps that copy forever. When Configure UI → Masters needed to know which forms are masters, that answer went into `@xeplr/ui-factory` (`useScreenSource`) and the generated page only reads `masters`. | `@xeplr/ui-factory` | A fix or a new control type has to reach apps that already exist, and it cannot reach code that was copied into them. `test/cli.test.js` fails if the glue reappears in the generated app. |
+| **Anything every app would write identically lives in a package, not in the generated app.** A generated app is a starting point that then lives its own life — glue copied into it can never be fixed centrally, so an app made last month keeps that copy forever. When the flow designer needed this app's forms, its functions and its flows, the wiring went into `@xeplr/ui-factory` (`FlowDesignerPage`) and the generated page passes its two API clients. | `@xeplr/ui-factory` | A fix or a new control type has to reach apps that already exist, and it cannot reach code that was copied into them. `test/cli.test.js` fails if the glue reappears in the generated app. |
 | **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. |
@@ -119,6 +132,12 @@ see **Configure UI** in the settings menu, top right.
 (`<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.
 
+Dashes in the name become underscores in the database names: `my-app` gets
+`my_app_auth` and `my_app_api`. `@xeplr/db` creates only plain identifiers
+(letters, digits, `_`) because `CREATE DATABASE` cannot take its name as a
+parameter, and the project name itself cannot hold `_` (it is also a folder and
+a package name).
+
 `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
@@ -139,7 +158,7 @@ Two ways, both in the running app's project:
   > (file: .pdf or .jpg), 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
+  Claude follows `CLAUDE.md`: the screens and server functions 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.
@@ -153,7 +172,7 @@ Two ways, both in the running app's project:
 | `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 screens screens/<form>/<form>.entity.json -o screens/<form> --no-pages` | a form's screens, server functions and model from its spec |
 | `api/` | `npx xeplr-factory validate <screen>.json` | check a screen document |
 | `ui/` | `npm run dev` | the app |
 
@@ -200,6 +219,17 @@ no defaults, ever.
 
 Encryption keys and signing secrets are **generated, never asked**.
 
+**Flows, inside the API.** `@xeplr/workflow-api` is a dependency of `api/`,
+and `bin/www` starts it with `registerWorkflow` after the screens — in a
+database of its own (`DB_WORKFLOW`, `<name>_workflow`: a sub-product embedded in
+an app keeps its tables apart, and creates the database on first start), with
+`tenantTables: false` so it follows the app's tenancy rather than creating
+`companies` / `workspaces`, and `access: true` so each flows route checks the
+caller's permissions, which its `migrations-auth` grants (loaded through
+`XEPLR_AUTH_MIGRATIONS`). The designer is `@xeplr/ui-factory`'s
+`FlowDesignerPage`; the paid canvas designer (X-Flow) is not part of a
+generated app.
+
 ## Licence
 
 MIT

package/lib/generate/index.js

@@ -24,6 +24,9 @@ var RENAME = {
 function substitutions(answers) {
   return Object.assign({
     __NAME__: answers.name,
+    __DB_API__: answers.databases.api,
+    __DB_AUTH__: answers.databases.auth,
+    __DB_WORKFLOW__: answers.databases.workflow,
     __PREFIX__: answers.prefix,
     __UI_PORT__: String(answers.ports.ui),
     __AUTH_PORT__: String(answers.ports.auth),
@@ -34,7 +37,25 @@ function substitutions(answers) {
     __ADMIN_PASSWORD__: answers.admin.password,
     __DB_CONNECTION__: answers.connection || '',
     __CONNECTION_NOTE__: connectionNote(answers)
-  }, tenancySubstitutions(answers.tenancy || []));
+  }, tenancySubstitutions(answers.tenancy || []), flowsSubstitutions(answers));
+}
+
+/**
+ * FLOWS ARE IN EVERY APP, and so is what runs them: @xeplr/workflow, started
+ * INSIDE the API (bin/www → registerWorkflow) in the app's own database. There
+ * is no Workflow server to run, no port, no setting and nothing to connect, so
+ * nothing here depends on an answer — these tokens only carry text.
+ */
+function flowsSubstitutions(answers) {
+  return {
+    __WF_README__: flowsReadme(answers),
+    __WF_CLAUDE__: [
+      '**Flows** — forms one after another, run by `@xeplr/workflow-api` INSIDE this API (bin/www starts it, workflow.js) in a database of its own (`DB_WORKFLOW`). Design them in Configure UI → Flows, never in code: a flow is data, reached through `/api/workflow/flows`, and walked at `/journey/<key>`. After a step, a flow goes to a screen, lets one of the app\'s `decide` functions choose, or finishes. Workflow follows this app\'s tenancy — it never creates companies or workspaces of its own.',
+      '',
+      '**Functions** — the code around a form\'s records lives in `api/functions/`, registered with `@xeplr/actions` under the event it is for (`beforeLoad`, `beforeSave`, `afterSave`, `beforeDelete`, `onError`, or `decide` for a flow), and is picked BY NAME in the screen\'s `events` or a flow step\'s navigation. There are no hook files. A screen naming a function nobody registered is refused at publish.',
+      ''
+    ].join('\n')
+  };
 }
 
 /**
@@ -118,6 +139,42 @@ function tenancySubstitutions(levels) {
   };
 }
 
+/** The README's Flows section. */
+function flowsReadme(answers) {
+  var tenancy = answers.tenancy || [];
+  return [
+    '## Flows',
+    '',
+    'Your forms, one after another. Design one in **Configure UI → Flows**: pick the screens, and for each one say what runs around its records (its **events**) and where the journey goes once it is saved — a screen, a **function that decides**, or the end. Publish it, and people start it from **Flows** in the side rail (or at `/journey/<key>`). The run id joins the address once it starts, so a journey can be reloaded, left, or handed to someone else and opened on the step it is on.',
+    '',
+    'Flows are run by **`@xeplr/workflow-api`**, **inside this API** — `bin/www` starts it after the screens. Nothing else to start:',
+    '',
+    '| | |',
+    '|---|---|',
+    '| **Database** | its own, `DB_WORKFLOW` (`' + answers.databases.workflow + '`), beside this app\'s — a sub-product embedded in an app keeps its tables apart. Created and migrated the first time the API starts. Each screen still saves into its own table in `DB_API`. |',
+    '| **Tenancy** | ' + (tenancy.length
+      ? 'this app\'s — flows and runs belong to the ' + tenancy.map(function (l) { return l.label.toLowerCase(); }).join(' and ') + ' chosen after signing in, checked by the same membership gate as everything else.'
+      : 'none, like the rest of this app — flows belong to the whole app.') + ' Workflow never creates companies or workspaces of its own. |',
+    '| **Permissions** | each route checks the caller\'s (`List flows`, `Start flow run`, `Publish flow`…), granted by `@xeplr/workflow-api`\'s `migrations-auth`, which `XEPLR_AUTH_MIGRATIONS` loads. |',
+    '',
+    '## Functions — your code, picked by name',
+    '',
+    'Code around a form\'s records — a check on save, an email after, a list narrowed to the user\'s own — is a **function** in `api/functions/`, registered with `@xeplr/actions` under the **event** it is for. A screen names it in its `events`; a flow step names a `decide` function to choose where to go next. The designer shows each event only the functions written for it, with what they are handed and return; the code stays in `api/functions/` and runs on the server.',
+    '',
+    '| event | runs | return |',
+    '|---|---|---|',
+    '| `beforeLoad` | before records are read | nothing, or a narrower `ctx.query` |',
+    '| `beforeSave` | before a record is written | the values to save; `ctx.reject(message, { field })` refuses |',
+    '| `afterSave` | once it is saved | (ignored) |',
+    '| `beforeDelete` | before a delete | nothing; `ctx.reject` refuses |',
+    '| `onError` | when load / save / delete failed | (ignored) |',
+    '| `decide` | a flow step is done | the next step\'s key |',
+    '',
+    '`api/functions/index.js` registers two to start from: `tidyTaskTitle` (Tasks\' `beforeSave`) and `byPriority` (a `decide`). A screen that names a function nobody registered is refused when it is published, by name.',
+    ''
+  ].join('\n');
+}
+
 /** One level's own table: what the picker lists. Its parents' ids in mtIdN. */
 function tenantTableSql(level, i) {
   var parents = i === 0 ? 'none — the outermost level' : i === 1 ? 'mtId1 holds the one above' : 'mtId1–mtId' + i + ' hold the ones above';

package/lib/plan.js

@@ -18,6 +18,7 @@ function describe(answers) {
   L.push('  Databases (created for you on first run):');
   L.push('    ' + answers.databases.auth + '    accounts, roles, permissions');
   L.push('    ' + answers.databases.api + '     your own data');
+  L.push('    ' + answers.databases.workflow + '  flows and their runs');
   L.push('');
   L.push('  You will sign in as ' + answers.admin.email + '.');
   L.push('');

package/lib/questions.js

@@ -20,6 +20,21 @@ function envPrefix(name) {
   return name.toUpperCase().replace(/-/g, '_');
 }
 
+// What @xeplr/db's ensureDatabase accepts: CREATE DATABASE cannot take its
+// name as a parameter, so it allows plain identifiers only.
+var DB_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function databaseNames(name) {
+  // my-app → my_app_auth, my_app_api. Dashes are fine in a folder and a
+  // package name but not in an unquoted identifier, and @xeplr/db refuses
+  // them ("Unsafe database name"). NAME_RE does not allow underscores, so
+  // without this every name with a separator in it failed at set-up.
+  var base = name.replace(/-/g, '_');
+  // Workflow gets a database of its own: a sub-product embedded in an app is
+  // given its own store, never a share of the app's (see the API's workflow.js).
+  return { auth: base + '_auth', api: base + '_api', workflow: base + '_workflow' };
+}
+
 // ── tenancy ──────────────────────────────────────────────────────────────
 //
 // At most four levels — @xeplr/db has four tenant columns (mtId1-4) — named
@@ -134,6 +149,10 @@ async function collect(session, argvName) {
     tenancy = tenancyLevels(levelsText);
   }
 
+  // ── flows ─────────────────────────────────────────────────────────────
+  // Nothing to ask: every app has flows, run by @xeplr/workflow inside its own
+  // API and database (see lib/generate's flowsSubstitutions).
+
   // ── the database ──────────────────────────────────────────────────────
   //
   // ASKED, not defaulted, and not left for the reader to do by hand either.
@@ -171,7 +190,7 @@ async function collect(session, argvName) {
     name: name,
     prefix: envPrefix(name),
     ports: { ui: base, auth: base + 1, api: base + 2 },
-    databases: { auth: name + '_auth', api: name + '_api' },
+    databases: databaseNames(name),
     admin: { email: adminEmail, password: adminPassword },
     tenancy: tenancy,
 
@@ -181,4 +200,4 @@ async function collect(session, argvName) {
   };
 }
 
-module.exports = { collect: collect, envPrefix: envPrefix, tenancyLevels: tenancyLevels, NAME_RE: NAME_RE };
+module.exports = { collect: collect, envPrefix: envPrefix, databaseNames: databaseNames, DB_NAME_RE: DB_NAME_RE, tenancyLevels: tenancyLevels, NAME_RE: NAME_RE };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/cli",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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

@@ -3,13 +3,13 @@
 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.
+Read `api/node_modules/@xeplr/ui-factory/AUTHORING.md` for what screens, functions, front-end 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 — on a page of its own (like Tasks) or 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.
+Create every file below — the front-end hooks and the model run the defaults (`super`) until the request needs more, and the server functions file registers nothing until it does.
 
 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. **Use the ready-made fields** for email, phone, website, LinkedIn, age, date of birth, gender, country, amount, percentage, yes/no and postal code — `"type": "email"` and so on ("Choosing controls" in AUTHORING.md): they bring the keyboard, format check and options with them, so don't write those by hand.
 2. **Screens + server files** — from `api/`:
@@ -18,8 +18,8 @@ Create every file below — the hooks and the model run the defaults (`super`) u
    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`.
+   Writes `<form>-list.screen.json`, `<form>-edit.screen.json`, `<form>.functions.js` (server functions, none registered yet), `<form>.model.js` (server model).
+3. **Register them** in `api/screens/index.js`: both screens in `documents` (edit before list), `require('./<form>/<form>.model')` in `models`; and in `api/functions/index.js`, `require('../screens/<form>/<form>.functions')`.
 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 `{ key: '<Forms>', icon, path: '/<forms>', clickHandler }` — by **key**, with an **icon** (a collapsed rail shows icons only) and the **path** (so the rail marks it as the current page). Never write the label in code.
@@ -33,11 +33,11 @@ Then change only what the request asks for:
 |---|---|
 | a field, label, rule, dropdown, layout, colour | the screen JSON → validate → publish in Configure UI → Forms (or, never published yet, restart the API) |
 | hide / filter rows on screen, an extra button on each row, fill in a value before saving, check something before Next moves on | front-end hooks — `ui/src/pages/Edit<Form>.jsx` (`get`, `save`, `delete`, `actions`, `step`) |
-| must / only if / check against / email when / only managers see | server hooks — `api/screens/<form>/<form>.hooks.js` |
+| must / only if / check against / email when / only managers see | a server function — registered in `api/screens/<form>/<form>.functions.js` with its `event`, then named in `<form>-edit.screen.json`'s `events` (or picked in Configure UI → Flows → Events). Register before naming: a screen naming an unregistered function is refused at publish |
 | 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 in **Configure UI → Forms** (settings menu, top right): New form (label + key) → design → Publish → Add to menu. It gets no page, hooks or model files; add them with the steps above when it needs them.
+**Without code:** Super Admin can also make a form in **Configure UI → Forms** (settings menu, top right): New form (label + key) → design → Publish → Add to menu. It gets no page, functions or model files; add them with the steps above when it needs them.
 
 ### The controls a field can be
 
@@ -49,6 +49,7 @@ Then change only what the request asks for:
 
 **A list opens its form on a page or in a popup** — `"openIn": "page"` in the entity spec, or Configure UI → Forms → the list. A page needs `onOpenRecord` on the list's page (where to navigate) and `onDone` on the form's page (where Save and Cancel go back to): `Tasks.jsx` and `EditTask.jsx` show both, with routes `/tasks/new` and `/tasks/:id` in `App.jsx`.
 
+__WF_CLAUDE__
 **Keys and labels.** A form's key names its screens and table and never changes once published; its label is the screens' name. A menu item's key (`menus.name`) is what `drawerItems` matches; its label is what the rail shows, renamed in Configure UI → Menu. Code only ever uses keys.
 
 ### The prompt
@@ -64,6 +65,7 @@ Replace the bold parts. Add behaviour in the same message if you want it — "a
 - A published screen's design lives in the **database**. Editing its `.screen.json` changes nothing afterwards: publish the change in Configure UI → Forms.
 - 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.
+- The browser is not a security boundary: anything that must hold goes in a server function, named in the screen's events.
 - Hooks and models are **methods** calling `super` — never arrow-function properties.
 - `authFetch` returns the parsed body, not a Response.
+- Sign-up needs email and `AUTH_REGISTER_ROLES` (the role a new account gets, in `api/development.env`); without either, registration is refused on purpose — never work around it by activating accounts or granting roles in SQL. An admin can activate an account from the User Roles screen.

package/templates/README.md

@@ -21,6 +21,9 @@ cd ui  && npm run dev            # the app           http://localhost:__UI_PORT_
 
 Open http://localhost:__UI_PORT__ and sign in as `__ADMIN_EMAIL__`.
 
+Flows (`@xeplr/workflow-api`) run **inside the API**, in a database of their
+own that the API creates on first start — nothing else to start.
+
 ## Where each address goes
 
 The browser only ever calls **paths** on the app's own address — never a port.
@@ -30,6 +33,7 @@ locally (`ui/vite.config.js`, from `ui/.env`), nginx in production.
 | path | served by | local (`ui/.env`) | production (nginx) |
 |---|---|---|---|
 | `/auth/api/…` | the sign-in service | `AUTH_URL` | `127.0.0.1:<AUTH_PORT>` |
+| `/api/workflow/…` | flows — `@xeplr/workflow-api`, inside the API | `API_URL` | `127.0.0.1:<__PREFIX___PORT>` |
 | `/api/…`, `/health`, `/whoami` | the API | `API_URL` | `127.0.0.1:<__PREFIX___PORT>` |
 
 ### Production
@@ -43,11 +47,11 @@ server {
   server_name app.example.com;
   root /srv/__NAME__/ui/dist;
 
-  location /auth/api/ { proxy_pass http://127.0.0.1:__AUTH_PORT__; }
-  location /api/      { proxy_pass http://127.0.0.1:__API_PORT__; }
-  location = /health  { proxy_pass http://127.0.0.1:__API_PORT__; }
-  location = /whoami  { proxy_pass http://127.0.0.1:__API_PORT__; }
-  location /          { try_files $uri /index.html; }   # the React app's own pages
+  location /auth/api/     { proxy_pass http://127.0.0.1:__AUTH_PORT__; }
+  location /api/          { proxy_pass http://127.0.0.1:__API_PORT__; }
+  location = /health      { proxy_pass http://127.0.0.1:__API_PORT__; }
+  location = /whoami      { proxy_pass http://127.0.0.1:__API_PORT__; }
+  location /              { try_files $uri /index.html; }   # the React app's own pages
 }
 ```
 
@@ -57,7 +61,9 @@ Every one of these checks the same sign-in token, so one login covers them all.
 
 - **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 on a page of its own, saved into an ordinary `tasks` table. The form is filled in over three steps and uses every control there is — text, a dropdown, radio buttons, a tick box, a date, a date and time, several tags at once, and a file.
-- **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).
+- **Configure UI** — in the settings menu, for Super Admin: every form (make one, design it, publish it, add it to the side rail), every flow (screens one after another — each screen's events, and where it goes next) and the side rail itself (rename, reorder, hide).
+- **Flows** — in the side rail: the journeys people can start, run by `@xeplr/workflow-api` inside the API.
+- **Functions** — `api/functions/`: your code, registered by event and picked by name in a screen's events or a flow step (see "Functions" below).
 
 ## Create a new UI
 
@@ -66,6 +72,7 @@ Every one of these checks the same sign-in token, so one login covers them all.
 
   > 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.
 
+__WF_README__
 ## Rules this app follows
 
 | Rule | Why |
@@ -74,7 +81,7 @@ Every one of these checks the same sign-in token, so one login covers them all.
 | 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. |
+| Rules that must hold go in **server functions** (`api/functions/`), named in a screen's events; 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

@@ -6,13 +6,13 @@ The API (`@xeplr/base-apis`) and the sign-in service (`@xeplr/auth`), with this
 
 | Command | Does |
 |---|---|
-| `npm run setup` | create both databases (`__NAME___auth`, `__NAME___api`), the sign-in tables, permissions and menus |
+| `npm run setup` | create both databases (`__DB_AUTH__`, `__DB_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 screens screens/<form>/<form>.entity.json -o screens/<form> --no-pages` | a form's screens, server functions and model from its spec |
 | `npx xeplr-factory validate <screen>.json` | check a screen document |
 
 ## Layout
@@ -24,7 +24,9 @@ The API (`@xeplr/base-apis`) and the sign-in service (`@xeplr/auth`), with this
 | `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` |
+| `screens/` | the forms this app ships with: per form, its spec, list and edit screens, server functions and model — registered in `screens/index.js` |
+| `functions/` | this app's functions — the code screens' events and flows' `decide` pick by name — registered with `@xeplr/actions` by event, loaded at startup |
+| `workflow.js` | flows: `@xeplr/workflow-api` started inside this API, in its own database (`DB_WORKFLOW`) |
 | `uploads/` | what people attach through a form's **file** field (`FACTORY_FILES_DIR`). Never committed, and never served: a file comes back only through the API's own route, which checks the caller the way reading a record does |
 | `migrations/` | hand-written SQL for tables no form owns |
 | `migrations-auth/` | this app's rows in the sign-in database — menus (by key), permissions |
@@ -39,4 +41,10 @@ The API (`@xeplr/base-apis`) and the sign-in service (`@xeplr/auth`), with this
 | `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 |
 | `AUTH_TENANT_HEADER` | `none`: one set of roles for everyone. A multi-tenant app names its company header (e.g. `x-company-id`), so a role made inside a company belongs to it |
-| `EMAIL_PROVIDER` and its settings | optional; without them sign-in works, but activation and reset links cannot be sent |
+| `AUTH_ACTIVATION_URL`, `AUTH_INVITE_URL`, `AUTH_RESET_URL` | the UI pages the emailed links open; the token is appended. The reset address is never taken from the request |
+| `AUTH_REGISTER_ROLES` | the role a new sign-up gets when activated (`Viewer`). **Required to register:** unset, or naming a role that does not exist, and registration is refused |
+| `EMAIL_PROVIDER` and its settings | needed to register, resend an activation link, invite or reset a password — each is refused while email does not work. Signing in works without it |
+
+## Sign-up
+
+Register → an activation email → the link (or an admin's **Activate** on the User Roles screen) → sign in. Lost the email? `/auth/resend-activation` sends a new one. Invited people set their password at `/auth/accept-invite`.

package/templates/api/app.js

@@ -13,6 +13,8 @@ var memberGate = __MT_MEMBER_GATE__;
 var port = process.env.__PREFIX___PORT;
 
 module.exports = buildApp;
+// bin/www hands the same gate to the flows router it starts (workflow.js).
+module.exports.memberGate = memberGate;
 
 function buildApp(extraRoutes) {
   return createApp(port, '__NAME___api', {

package/templates/api/bin/www

@@ -33,6 +33,10 @@ var path = require('path');
 var { resolveConfig } = require('@xeplr/db');
 var { up } = require('@xeplr/db').sqlMigrator;
 var factory = require('@xeplr/factory');
+// This app's functions — what screens' events and flows' "let a function
+// decide" pick by name. Registered before anything can publish a screen that
+// names one.
+require('../functions');
 var screens = require('../screens');
 
 async function start() {
@@ -58,15 +62,13 @@ async function start() {
   // time has no connection at all until this has finished.
   var knex = await require('../db/setup');
 
-  // 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.
+  // The screens and their models. A malformed model stops startup here,
+  // rather than silently never running.
   // filesDir: where a form's file field puts what people upload. Nothing is
   // served from it — a file comes back only through the factory's own route,
   // which checks the caller the way reading a record does.
   await factory.init({
     knex: knex,
-    hooks: screens.hooks,
     models: screens.models,
     filesDir: process.env.FACTORY_FILES_DIR
   });
@@ -76,7 +78,13 @@ async function start() {
   var published = await factory.publishScreens(screens.documents);
   if (published.published.length) console.log('[api] published screens: ' + published.published.join(', '));
 
-  require('../app')();
+  // FLOWS — @xeplr/workflow-api, inside this API, in a database of its own
+  // (DB_WORKFLOW — created and migrated on first start). It follows this
+  // app's tenancy and creates no companies or workspaces of its own.
+  var buildApp = require('../app');
+  require('../routes/flows').mount(await require('../workflow')(buildApp.memberGate));
+
+  buildApp();
 }
 
 start().catch(function(err) {

package/templates/api/db/setup.js

@@ -4,7 +4,7 @@
 var { getConnection } = require('@xeplr/db');
 __MT_DB_REGISTER__
 
-// No `|| '__NAME___api'` fallback. DB_API is required at startup
+// No `|| '__DB_API__'` fallback. DB_API is required at startup
 // (env.required.js), so a default could only ever fire in a process that
 // skipped that check — and silently connecting to a database nobody named is
 // exactly what the check exists to prevent.

package/templates/api/development.env.tpl

@@ -18,10 +18,12 @@ __PREFIX___CONNECTION=__DB_CONNECTION__
 AUTH_DB_CONNECTION_INFO_ENCRYPTED=__DB_CONNECTION__
 
 # ── Databases ──
-# Two of them: accounts in one, your own data in the other. Both are created
-# for you the first time you run the setup.
-DB_API=__NAME___api
-AUTH_DB_NAME=__NAME___auth
+# Three of them: accounts, your own data, and flows (workflow's own, kept apart
+# from yours). The first two are created by the setup; the flows one by the API
+# the first time it starts.
+DB_API=__DB_API__
+AUTH_DB_NAME=__DB_AUTH__
+DB_WORKFLOW=__DB_WORKFLOW__
 
 # ── Sign-in service ──
 #
@@ -40,9 +42,10 @@ AUTH_JWT_SECRET=__JWT_SECRET__
 # Where the sign-in service is. Your API asks it to check every token.
 AUTH_URL=http://localhost:__AUTH_PORT__
 
-# Sign-in setup files: the screens' permissions (@xeplr/factory's), then this
-# app's own — menu entries and anything else it adds. Comma-separated, in order.
-XEPLR_AUTH_MIGRATIONS=./node_modules/@xeplr/factory/migrations-auth,./migrations-auth
+# Sign-in setup files: the screens' permissions (@xeplr/factory's), flows'
+# (@xeplr/workflow-api's), then this app's own — menu entries and anything else
+# it adds. Comma-separated, in order.
+XEPLR_AUTH_MIGRATIONS=./node_modules/@xeplr/factory/migrations-auth,./node_modules/@xeplr/workflow-api/migrations-auth,./migrations-auth
 
 # ── The first account you sign in with ──
 # Created for you when you set up the database. Change the password here and
@@ -62,6 +65,16 @@ AUTH_TENANT_HEADER=none
 # 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
+# Never taken from the request: a link built from its Host header could point
+# a real user's reset mail at someone else's site. Unset, reset is refused.
+AUTH_RESET_URL=http://localhost:__UI_PORT__/auth/reset-password
+
+# ── The role a new sign-up gets ──
+# Given when the account is activated. Without a role a person can sign in
+# and do nothing — not even open their own profile. No default: unset, or a
+# role that does not exist, and registration is refused. Comma-separate for
+# more than one; Super Admin is never allowed here.
+AUTH_REGISTER_ROLES=Viewer
 
 # ── Uploaded files ──
 # Where a form's FILE field puts what people upload. The path is what the
@@ -69,10 +82,12 @@ AUTH_INVITE_URL=http://localhost:__UI_PORT__/auth/accept-invite
 # which checks the caller the way reading a record does. Relative to api/.
 FACTORY_FILES_DIR=./uploads/factory
 
-# ── 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".
+# ── Email ──
+# Needed for anyone but the super admin to get in: registration, resending an
+# activation link, invites and password reset all send a link, and each is
+# refused while email does not work — no half-made accounts. Signing in keeps
+# working without it. 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=
@@ -80,4 +95,3 @@ FACTORY_FILES_DIR=./uploads/factory
 # SMTP_USER=
 # SMTP_PASS=
 # SMTP_FROM=
-# (smtp also needs `npm install nodemailer` in this folder)

package/templates/api/env.required.js

@@ -9,7 +9,9 @@
  */
 module.exports = [
   // ENCRYPTION_KEY, AUTH_JWT_SECRET, AUTH_PORT, AUTH_DB_NAME,
-  // XEPLR_AUTH_MIGRATIONS, AUTH_SUPER_ADMIN_EMAIL / _PASSWORD, REDIS_PREFIX
+  // XEPLR_AUTH_MIGRATIONS, AUTH_SUPER_ADMIN_EMAIL / _PASSWORD, REDIS_PREFIX,
+  // AUTH_TENANT_HEADER, and the sign-up settings: AUTH_REGISTER_ROLES,
+  // AUTH_ACTIVATION_URL, AUTH_RESET_URL
   ...require('@xeplr/auth').requiredEnv,
 
   // ── this app's own ──
@@ -26,4 +28,8 @@ module.exports = [
   // error — the most expensive way for this to go wrong.
   'DB_API',
   '__PREFIX___CONNECTION',
+
+  // Flows' own database (DB_WORKFLOW) — workflow is embedded in this API but
+  // keeps its tables apart from yours. The library names it.
+  ...require('@xeplr/workflow-api').embedRequiredEnv,
 ];

package/templates/api/functions/index.js

@@ -0,0 +1,47 @@
+// THIS APP'S FUNCTIONS — the code a screen's events and a flow's "let a
+// function decide" run. Loaded once at startup (bin/www), before the screens.
+//
+// A function is registered under the EVENT it is written for, and picked BY
+// NAME in the designer: Configure UI → Flows → a step → Events & navigation
+// (or a screen's own `events` in its .screen.json). The designer only ever
+// sees the name, the description and what the event hands it — the code
+// stays here, and runs on the server.
+//
+//   event          runs                                   ctx adds              return
+//   beforeLoad     before records are read                query (narrow it)     nothing, or a new query
+//   beforeSave     before a record is written             values, isNew,        the values to save
+//                                                         previous
+//   afterSave      once it is saved                       result                (ignored)
+//   beforeDelete   before a delete                        previous              nothing
+//   onError        when load / save / delete failed       error                 (ignored)
+//   decide         a flow step is done: where next?       values, targets       a step key
+//
+// Every ctx has user, tenant, knex, db() (this form's table, scoped) and
+// reject(message, { field }) — which refuses with the message on that field.
+//
+// A screen that names a function nobody registered is refused when it is
+// published, by name — so renaming one here means renaming it there too.
+// Add files beside this one and require them below as the app grows.
+var { register } = require('@xeplr/actions');
+
+register({
+  name: 'tidyTaskTitle',
+  event: 'beforeSave',
+  description: 'Trims a task\'s title and squeezes repeated spaces, so "  Plant   seeds " is saved as "Plant seeds".',
+  execute: function(ctx) {
+    var title = String(ctx.values.title || '').replace(/\s+/g, ' ').trim();
+    if (!title) ctx.reject('A task needs a title', { field: 'title' });
+    return Object.assign({}, ctx.values, { title: title });
+  }
+});
+
+register({
+  name: 'byPriority',
+  event: 'decide',
+  description: 'High-priority tasks go to the first screen it may choose; everything else to the second.',
+  execute: function(ctx) {
+    // ctx.targets: the steps ticked under "It may choose", in the flow's order.
+    var high = ctx.values && ctx.values.priority === 'high';
+    return high ? ctx.targets[0] : (ctx.targets[1] || ctx.targets[0]);
+  }
+});

package/templates/api/migrations-auth/0005_flows_menu.sql

@@ -0,0 +1,14 @@
+-- "Flows" — the side-rail item for journeys across the app's forms.
+--
+-- ALWAYS THERE: flows are run by @xeplr/workflow inside this app's own API,
+-- so there is nothing to switch on.
+--
+-- The name is the KEY: it must match ui/src/App.jsx's drawerItems `key`
+-- EXACTLY. What people read is the label, changed in Configure UI → Menu.
+-- (0005, not 0004: a multi-tenant app's own 0004 is the switch menu.)
+
+INSERT INTO "menus" (id, name, "menuGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), 'Flows', '', true, true, '*', now(), now()
+WHERE NOT EXISTS (SELECT 1 FROM "menus" WHERE name = 'Flows');
+
+UPDATE "menus" SET "isPublic" = true WHERE name = 'Flows';