@xeplr/cli 0.1.9 → 0.1.11

package/README.md

@@ -26,9 +26,11 @@ Already working, with nothing to wire up:
   open is named explicitly; there is no way to leave the whole thing public by
   forgetting.
 - **A sample built with the screen designer** — a task list whose New and Edit
-  open the task form in a popup, saving as you type into an ordinary `tasks`
-  table. Neither is written by hand: both are screens
-  ([`@xeplr/ui-factory`](https://www.npmjs.com/package/@xeplr/ui-factory)),
+  open the task form on a page of its own, filled in over three steps and saving
+  as you type into an ordinary `tasks` table. It uses every control there is:
+  text, dropdown, radio buttons, tick box, date, date and time, a multi-select
+  and a file upload. Neither the list nor the form is written by hand: both are
+  screens ([`@xeplr/ui-factory`](https://www.npmjs.com/package/@xeplr/ui-factory)),
   published when the API first starts.
 - **Configure UI** for Super Admin, in the settings menu (top right) — not in
   the side rail, which is for the pages people use:
@@ -39,6 +41,9 @@ 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, if you run Xeplr Workflow** — your forms one after another, where
+  what someone fills in decides the next screen. Designed in Configure UI →
+  Flows, walked at `/journey/<key>`, and resumable, since Workflow keeps the run.
 - **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,
@@ -53,8 +58,10 @@ Already working, with nothing to wire up:
 
   > 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.
+  > acres (number, at least 0), Started on (date), Certifications (choose several:
+  > Organic, Fair trade, Rainforest), Inspection at (date and time), Licence
+  > (file: .pdf or .jpg), Notes (long text). Show Name, Region and Area in the
+  > list. Follow "Create a new UI" in CLAUDE.md.
 
 ## Rules the generated app follows
 
@@ -129,8 +136,10 @@ Two ways, both in the running app's project:
 
   > 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.
+  > acres (number, at least 0), Started on (date), Certifications (choose several:
+  > Organic, Fair trade, Rainforest), Inspection at (date and time), Licence
+  > (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
   (`npx xeplr-factory screens … --no-pages`), the page with its front-end hooks,
@@ -189,10 +198,17 @@ no defaults, ever.
 | Super admin email | the account you sign in with |
 | Super admin password | its password |
 | Multi-tenant? | no — or the levels, outermost first: `company`, `company, workspace` |
+| Flows — is Xeplr Workflow running? | no — or its address (`http://localhost:19122`) and its backend folder. Yes adds **Configure UI → Flows**, a `/journey/<key>` page, and `/api/flows` forwarded to Workflow — and sets multi-tenancy to Workflow's own levels, company then workspace, since it keeps every journey inside both |
 | Database connection | host, port, user, password — or skip, and fill it in later |
 
 Encryption keys and signing secrets are **generated, never asked**.
 
+**Flows need Workflow to share the app's sign-in.** Workflow is a separate
+service, not a package the project installs: set its `AUTH_URL` and
+`AUTH_DB_NAME` to the new app's, and the app's sign-in service loads Workflow's
+access rules from the folder you gave. The generated README says exactly which
+values.
+
 ## Licence
 
 MIT

package/lib/generate/index.js

@@ -8,6 +8,10 @@ var TEMPLATES = path.join(__dirname, '..', '..', 'templates');
 // with the same path as one there replaces it.
 var TENANCY_TEMPLATES = path.join(__dirname, '..', '..', 'templates-tenancy');
 
+// Files that exist ONLY in an app connected to Xeplr Workflow — the route that
+// forwards flows to it, the designer, and the page a journey runs on.
+var FLOWS_TEMPLATES = path.join(__dirname, '..', '..', 'templates-flows');
+
 // Files whose names cannot ship as-is. `.env` and `.gitignore` are both
 // swallowed on the way here — npm refuses to pack a .gitignore, and an .env in
 // a published package is a mistake waiting to happen — so they travel under a
@@ -34,7 +38,51 @@ function substitutions(answers) {
     __ADMIN_PASSWORD__: answers.admin.password,
     __DB_CONNECTION__: answers.connection || '',
     __CONNECTION_NOTE__: connectionNote(answers)
-  }, tenancySubstitutions(answers.tenancy || []));
+  }, tenancySubstitutions(answers.tenancy || []), flowsSubstitutions(answers.workflow || null, answers));
+}
+
+/**
+ * The lines an app connected to Xeplr Workflow has, and one without it does
+ * not. Like tenancy, every token exists either way and expands to nothing when
+ * flows are off, so no template needs a condition of its own.
+ */
+function flowsSubstitutions(workflow, answers) {
+  var on = Boolean(workflow);
+  return {
+    __WF_ENV__: on ? [
+      '# ── Flows (Xeplr Workflow) ──',
+      '# Your forms, one after another — Workflow runs the journey. It is a separate',
+      '# service: start it, and point it at THIS app\'s sign-in (see README, "Flows").',
+      'WORKFLOW_URL=' + workflow.url,
+      ''
+    ].join('\n') : '',
+    // Workflow's access rules — who may design a flow, who may run one — are
+    // loaded by this app's sign-in service, after the app's own.
+    __WF_AUTH_MIGRATIONS__: on && workflow.dir ? ',' + workflow.dir + '/migrations-auth' : '',
+    __WF_REQUIRED_ENV__: on ? "  // Where Xeplr Workflow is — flows are forwarded to it.\n  'WORKFLOW_URL'," : '',
+    __WF_API_ROUTE__: on ? [
+      '// Flows go to Xeplr Workflow (WORKFLOW_URL), behind this app\'s own gate.',
+      "router.use('/api/flows', require('./flows'));"
+    ].join('\n') : '',
+    __WF_UI_IMPORTS__: on ? [
+      "import FlowDesigner from './pages/FlowDesigner.jsx'",
+      "import Journey from './pages/Journey.jsx'"
+    ].join('\n') : '',
+    __WF_UI_ROUTES__: on ? [
+      '        <Route path="/configure/flows/:flow" element={<FlowDesigner />} />',
+      '        {/* A journey: its run id joins the address once it starts, so it can be resumed. */}',
+      '        <Route path="/journey/:flow" element={<Journey />} />',
+      '        <Route path="/journey/:flow/:run" element={<Journey />} />'
+    ].join('\n') : '',
+    __WF_TAB_IMPORT__: on ? "import Flows from './Flows.jsx'" : '',
+    __WF_TAB__: on ? "  { id: 'flows', label: 'Flows', Page: Flows }," : '',
+    __WF_TAB_NOTE__: on ? '//   Flows  forms one after another — what is filled in decides the next; run by Xeplr Workflow' : '',
+    __WF_README__: on ? flowsReadme(workflow, answers) : '',
+    __WF_CLAUDE__: on ? [
+      '**Flows** — forms one after another, run by Xeplr Workflow (`WORKFLOW_URL`). Design them in Configure UI → Flows, never in code: a flow is data in Workflow, reached through `/api/flows`, and walked at `/journey/<key>`. An arrow tests one field of the screen it leaves; a form that is a step must be published first.',
+      ''
+    ].join('\n') : ''
+  };
 }
 
 /**
@@ -118,6 +166,37 @@ function tenancySubstitutions(levels) {
   };
 }
 
+/**
+ * The README's Flows section — what a flow is, and the one thing that has to
+ * be true for it to work: Workflow and this app share a sign-in.
+ */
+function flowsReadme(workflow, answers) {
+  return [
+    '## Flows',
+    '',
+    'Your forms, one after another: what someone fills in on one decides which comes next. Design one in **Configure UI → Flows**, publish it, and open it 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**, a separate service at `WORKFLOW_URL` (' + workflow.url + '). The API forwards `/api/flows/…` to it unchanged; each screen still saves into its own table.',
+    '',
+    'Workflow keeps every journey inside a **company and a workspace** — the two levels it registers — which is why this app has exactly those: a flow is made, and a run started, in the company and workspace picked after signing in.',
+    '',
+    '**Workflow must use this app\'s sign-in.** In Workflow\'s own `development.env`:',
+    '',
+    '```sh',
+    'AUTH_URL=http://localhost:' + answers.ports.auth + '      # this app\'s sign-in service',
+    'AUTH_DB_NAME=' + answers.name + '_auth               # and its database',
+    'REDIS_PREFIX=' + answers.name + ':',
+    '```',
+    '',
+    'If Workflow\'s database server is not this app\'s, also set `AUTH_DB_CONNECTION_INFO_ENCRYPTED` in Workflow to this app\'s server, encrypted with **Workflow\'s** `ENCRYPTION_KEY` (`npm run db:encrypt` in Workflow\'s backend). Otherwise every flow call fails with *database "' + answers.name + '_auth" does not exist*.',
+    '',
+    workflow.dir
+      ? 'Its access rules — who may design a flow, who may run one — are loaded by this app\'s sign-in service from `' + workflow.dir + '/migrations-auth` (in `XEPLR_AUTH_MIGRATIONS`). Restart the sign-in service after changing it.'
+      : 'Its access rules — who may design a flow, who may run one — live in Workflow\'s `backend/migrations-auth`. Add that folder to `XEPLR_AUTH_MIGRATIONS` in `api/development.env` (comma separated, after `./migrations-auth`) and restart the sign-in service; until then, flows answer 403.',
+    ''
+  ].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';
@@ -230,6 +309,15 @@ function generate(answers, target) {
     throw new Error(target + ' already exists and is not empty.');
   }
 
+  // Workflow files every flow and run under a company; an app without
+  // companies would build, start, and then refuse every flow it tried to make.
+  if (answers.workflow) {
+    var q = require('../questions');
+    if (!q.sameLevels(answers.tenancy || [], q.tenancyLevels(q.WORKFLOW_LEVELS))) {
+      throw new Error('Flows need the same multi-tenancy as Xeplr Workflow — levels "' + q.WORKFLOW_LEVELS + '" — because Workflow keeps every journey inside a company and a workspace.');
+    }
+  }
+
   var subs = substitutions(answers);
   var written = [];
 
@@ -238,6 +326,9 @@ function generate(answers, target) {
   if (answers.tenancy && answers.tenancy.length) {
     walk(TENANCY_TEMPLATES).forEach(function (src) { sources[path.relative(TENANCY_TEMPLATES, src)] = src; });
   }
+  if (answers.workflow) {
+    walk(FLOWS_TEMPLATES).forEach(function (src) { sources[path.relative(FLOWS_TEMPLATES, src)] = src; });
+  }
 
   Object.keys(sources).forEach(function (rel) {
     var src = sources[rel];

package/lib/prompt.js

@@ -124,7 +124,10 @@ function createSession(options) {
     return /^y/i.test(v);
   }
 
-  return { ask: ask, askSecret: askSecret, confirm: confirm, close: function () { rl.close(); } };
+  /** A line of explanation between questions — no answer expected. */
+  function say(text) { output.write(text + '\n'); }
+
+  return { ask: ask, askSecret: askSecret, confirm: confirm, say: say, close: function () { rl.close(); } };
 }
 
 module.exports = { createSession: createSession };

package/lib/questions.js

@@ -134,6 +134,40 @@ async function collect(session, argvName) {
     tenancy = tenancyLevels(levelsText);
   }
 
+  // ── flows ─────────────────────────────────────────────────────────────
+  //
+  // Screens one after another, where what someone filled in decides the next
+  // screen. The journey is run by Xeplr Workflow — a separate service, not a
+  // package — so this only asks where it is. Off, the app has no flows at all.
+  var workflow = null;
+  var wantsFlows = await session.confirm('Flows — is Xeplr Workflow running for this app?', false);
+  if (wantsFlows) {
+    var workflowUrl = await session.ask('  Workflow API address?', {
+      default: 'http://localhost:19122',
+      validate: function (v) { return /^https?:\/\/[^\s]+$/.test(v) ? true : 'An http:// or https:// address.'; }
+    });
+    // Workflow keeps its access rules (who may design a flow, who may run one)
+    // in migrations-auth/. This app's sign-in service has to load them, so it
+    // needs to know where they are. Blank is allowed: the README says how.
+    var workflowDir = await session.ask('  Workflow backend folder (for its access rules — blank to add later)?', {
+      default: '',
+      validate: function (v) { return !v || !/\s/.test(v) ? true : 'A path without spaces.'; }
+    });
+    workflow = { url: workflowUrl.replace(/\/+$/, ''), dir: workflowDir.replace(/\/+$/, '') };
+
+    // Workflow files every flow and every run under a company and a workspace
+    // — the two levels it registers, with those headers. An app that sends
+    // anything else builds, starts, and then has every flow refused, so the
+    // levels that make flows work are set here, and said out loud.
+    if (!sameLevels(tenancy, tenancyLevels(WORKFLOW_LEVELS))) {
+      tenancy = tenancyLevels(WORKFLOW_LEVELS);
+      if (session.say) {
+        session.say('  Flows need the same tenancy as Xeplr Workflow — company, then workspace —');
+        session.say('  so this app uses those two levels.');
+      }
+    }
+  }
+
   // ── the database ──────────────────────────────────────────────────────
   //
   // ASKED, not defaulted, and not left for the reader to do by hand either.
@@ -174,6 +208,7 @@ async function collect(session, argvName) {
     databases: { auth: name + '_auth', api: name + '_api' },
     admin: { email: adminEmail, password: adminPassword },
     tenancy: tenancy,
+    workflow: workflow,
 
     // GENERATED, never asked. Nobody should be inventing these by hand, and a
     // prompt invites a weak answer or a reused one.
@@ -181,4 +216,12 @@ async function collect(session, argvName) {
   };
 }
 
-module.exports = { collect: collect, envPrefix: envPrefix, tenancyLevels: tenancyLevels, NAME_RE: NAME_RE };
+/** The tenancy Xeplr Workflow registers: a flows app must send the same headers. */
+var WORKFLOW_LEVELS = 'company, workspace';
+
+/** Same levels, in the same order, with the same headers. */
+function sameLevels(a, b) {
+  return a.length === b.length && a.every(function (l, i) { return l.header === b[i].header; });
+}
+
+module.exports = { collect: collect, envPrefix: envPrefix, tenancyLevels: tenancyLevels, sameLevels: sameLevels, WORKFLOW_LEVELS: WORKFLOW_LEVELS, NAME_RE: NAME_RE };

package/package.json

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

@@ -45,10 +45,11 @@ Then change only what the request asks for:
 
 - **`multiselect`** — several ids in ONE text column, comma separated, and an array in your code. An option's id may not contain a comma.
 - **`file`** — the column holds the **path**, never the file. Say which extensions (`"accept": ".pdf,.docx"`) and how large (`"maxSize": 10`, in MB); the API enforces both, by extension, and keeps the file under `FACTORY_FILES_DIR`. Uploading needs `multer` in `api/` (already in package.json).
-- **`stepper`** — a journey across the top. Every other field says which step it is on (`"step": "Planning"`), and one without a `step` shows on every step. `step(ctx)` in the front-end hooks runs before each move.
+- **`stepper`** — a journey across the top. Every other field says which step it is on (`"step": "Planning"`), and one without a `step` shows on every step. `step(ctx)` in the front-end hooks runs before each move: return `false` to stay, a step's key to go there, `ctx.disable(['planning'])` to rule steps out (struck through on the bar, passed over by Next and Back) and `ctx.enable()` to bring them back.
 
 **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 Done goes 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

package/templates/README.md

@@ -34,6 +34,7 @@ Open http://localhost:__UI_PORT__ and sign in as `__ADMIN_EMAIL__`.
 
   > 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 |

package/templates/api/development.env.tpl

@@ -42,7 +42,7 @@ 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
+XEPLR_AUTH_MIGRATIONS=./node_modules/@xeplr/factory/migrations-auth,./migrations-auth__WF_AUTH_MIGRATIONS__
 
 # ── The first account you sign in with ──
 # Created for you when you set up the database. Change the password here and
@@ -57,6 +57,7 @@ AUTH_SUPER_ADMIN_PASSWORD=__ADMIN_PASSWORD__
 AUTH_ACTIVATION_URL=http://localhost:__UI_PORT__/auth/activate
 AUTH_INVITE_URL=http://localhost:__UI_PORT__/auth/accept-invite
 
+__WF_ENV__
 # ── Uploaded files ──
 # Where a form's FILE field puts what people upload. The path is what the
 # record stores; the file itself is served only through the API's own route,

package/templates/api/env.required.js

@@ -25,5 +25,6 @@ module.exports = [
   // clean, migrates, serves traffic and reads as EMPTY DATA rather than as an
   // error — the most expensive way for this to go wrong.
   'DB_API',
-  '__PREFIX___CONNECTION'
+  '__PREFIX___CONNECTION',
+__WF_REQUIRED_ENV__
 ];

package/templates/api/package.json

@@ -21,7 +21,7 @@
     "@xeplr/base-apis": "^2.0.0",
     "@xeplr/db": "^1.0.6",
     "@xeplr/factory": "^1.0.6",
-    "@xeplr/ui-factory": "^1.0.11",
+    "@xeplr/ui-factory": "^1.0.14",
     "@xeplr/utils": "^1.0.11",
     "dotenv": "^17.4.2",
     "express": "^5.2.0",

package/templates/api/routes/index.js

@@ -34,4 +34,6 @@ router.get('/whoami', function(req, res) {
 //   var { genericRoute } = require('@xeplr/base-apis');
 //   router.use('/api/things', genericRoute({ key: 'thing', model: require('../models').Thing }));
 
+__WF_API_ROUTE__
+
 module.exports = router;

package/templates/ui/package.json

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

package/templates/ui/src/App.jsx

@@ -4,6 +4,7 @@ import { authRoutes, authPath, NavPage, ProtectedRoute, useAccess } from '@xeplr
 import Home from './pages/Home.jsx'
 import Tasks from './pages/Tasks.jsx'
 import EditTask from './pages/EditTask.jsx'
+__WF_UI_IMPORTS__
 import ConfigureUI from './pages/ConfigureUI.jsx'
 import { FORM_MENU_PREFIX } from './menu.js'
 import FormDesigner from './pages/FormDesigner.jsx'
@@ -112,6 +113,7 @@ __MT_SELECT_ROUTE__
         <Route path="/forms/:form" element={<FormRecords />} />
         <Route path="/configure" element={<ConfigureUI />} />
         <Route path="/configure/forms/:form/design/:part" element={<FormDesigner />} />
+__WF_UI_ROUTES__
       </Route>
 
       <Route path="*" element={<Navigate to="/auth/login" replace />} />

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

@@ -3,15 +3,18 @@
 //   Forms  every UI in the app: make one, design it, publish it, open it, add it
 //          to the side rail
 //   Menu   the side rail's items: rename, reorder, hide
+__WF_TAB_NOTE__
 //
 // Configuration lives here, not in the side rail — the rail is for the pages
 // people use.
 import { useSearchParams } from 'react-router-dom'
 import Forms from './Forms.jsx'
 import MenuSettings from './MenuSettings.jsx'
+__WF_TAB_IMPORT__
 
 const TABS = [
   { id: 'forms', label: 'Forms', Page: Forms },
+__WF_TAB__
   { id: 'menu', label: 'Menu', Page: MenuSettings }
 ]
 

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

@@ -38,8 +38,18 @@ export class TaskHooks extends FactoryHooks {
 
   /**
    * Before a stepper moves — Next, Back, or a click on the bar.
-   * Return false to stay where you are, or a step number to go there instead.
-   * The step's own required fields are checked before this runs.
+   *
+   * Return false to stay where you are, or a step (its key or its number) to
+   * go there instead. ctx.disable(['planning']) rules steps out — they stay on
+   * the bar, struck through, and Next and Back pass over them; ctx.enable()
+   * brings them all back. The step's own required fields are checked before
+   * this runs, so this is for your rules, not theirs. For example:
+   *
+   *   if (ctx.from === 0 && ctx.values.priority === 'low') {
+   *     ctx.disable(['planning'])
+   *     return 'attachment'
+   *   }
+   *   ctx.enable()
    */
   step(ctx) {
     return super.step(ctx)