@xeplr/cli 0.1.2 → 0.1.4

package/README.md

@@ -1,7 +1,7 @@
 # @xeplr/cli
 
-Creates a working xeplr application — an API, sign-in, and a UI — from four
-questions.
+Creates a working xeplr application — an API, sign-in, and a UI — from a few
+questions, installs it, and sets up its databases.
 
 ```bash
 npx @xeplr/cli new myapp
@@ -23,10 +23,29 @@ Already working, with nothing to wire up:
 - **A guarded API** — every address needs a valid token. An address you want
   open is named explicitly; there is no way to leave the whole thing public by
   forgetting.
-- **A sample form** — a table, a model, one line of routing, and a page, with
-  instructions beside it showing how to add your own.
+- **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)),
+  published when the API first starts.
+- **A Forms page** for Super Admin — every form in the app; make a new one by
+  hand (no Claude needed), design its form and its list, publish (which creates
+  or changes its table), open it. Nobody else sees it, and the API refuses
+  everyone else.
+- **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
 
@@ -54,20 +73,23 @@ shell.
 
 ## Then
 
+The installer has already run `npm install` in both halves and — when you gave
+the database connection — `npm run setup`, which creates both databases, the
+sign-in tables and the permissions. Start it:
+
 ```bash
-cd myapp/api
-npm install
-npm run setup        # creates both databases and their tables
-npm run start-auth   # sign-in
-npm run start-api    # your API
-
-cd ../ui
-npm install
-npm run dev
+cd myapp/api && npm run start-auth   # sign-in
+cd myapp/api && npm run start-api    # your API — publishes the sample screens on first start
+cd myapp/ui  && npm run dev          # the app
 ```
 
 Open the UI and sign in with the account you named.
 
+`xeplr new myapp --no-install` only writes the files; then run `npm install` in
+`api` and `ui`, and `npm run setup` in `api`, yourself. If set-up stops part
+way (Postgres not running, say), the installer says which step and the command
+to run again.
+
 ## Changing the database connection later
 
 A password rotates, the database moves, or the first answer was wrong. From
@@ -106,6 +128,8 @@ no defaults, ever.
 | Port decade | three consecutive ports — ui, sign-in, api |
 | 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` |
+| Database connection | host, port, user, password — or skip, and fill it in later |
 
 Encryption keys and signing secrets are **generated, never asked**.
 

package/bin/xeplr.js

@@ -6,6 +6,7 @@ var questions = require('../lib/questions');
 var plan = require('../lib/plan');
 var generate = require('../lib/generate');
 var nextSteps = require('../lib/nextSteps');
+var setup = require('../lib/setup');
 var encryptCmd = require('../lib/commands/encrypt');
 
 var HELP = [
@@ -13,7 +14,8 @@ var HELP = [
   '  xeplr — create a working xeplr application',
   '',
   '  Usage:',
-  '    xeplr new [name]     create a project',
+  '    xeplr new [name]     create a project, install it and set up its databases',
+  '    xeplr new [name] --no-install   only write the files',
   '    xeplr encrypt        redo the database connection',
   '',
   '  new      Creates a project with an API, sign-in and a UI, all talking',
@@ -52,7 +54,7 @@ async function main() {
 
   var session = prompt.createSession();
   try {
-    var answers = await questions.collect(session, argv[1]);
+    var answers = await questions.collect(session, argv[1] && argv[1].indexOf('--') !== 0 ? argv[1] : undefined);
     console.log(plan.describe(answers));
 
     var go = await session.confirm('  Create it?', true);
@@ -60,6 +62,8 @@ async function main() {
       console.log('\n  Nothing was written.\n');
       return 0;
     }
+    var installNow = argv.indexOf('--no-install') === -1 && await session.confirm(
+      answers.connection ? '  Install packages and set up the databases now?' : '  Install packages now?', true);
   } finally {
     session.close();
   }
@@ -67,8 +71,10 @@ async function main() {
   var target = path.resolve(process.cwd(), answers.name);
   var result = generate.generate(answers, target);
   console.log('\n  Wrote ' + result.written.length + ' files.');
-  console.log(nextSteps.describe(answers, target));
-  return 0;
+
+  var done = installNow ? await setup.run(answers, target) : null;
+  console.log(nextSteps.describe(answers, target, done));
+  return done && !done.ok ? 1 : 0;
 }
 
 main().then(function (code) { process.exit(code); }, function (err) {

package/lib/generate/index.js

@@ -3,6 +3,11 @@ var path = require('path');
 
 var TEMPLATES = path.join(__dirname, '..', '..', 'templates');
 
+// Files that exist ONLY in a multi-tenant app — the company tables, the picker,
+// the membership check. Laid over templates/ when tenancy is on; a file here
+// with the same path as one there replaces it.
+var TENANCY_TEMPLATES = path.join(__dirname, '..', '..', 'templates-tenancy');
+
 // 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
@@ -17,7 +22,7 @@ var RENAME = {
 // never filled shows up as a missing key rather than as the literal
 // __SOMETHING__ in a generated file.
 function substitutions(answers) {
-  return {
+  return Object.assign({
     __NAME__: answers.name,
     __PREFIX__: answers.prefix,
     __UI_PORT__: String(answers.ports.ui),
@@ -29,9 +34,111 @@ function substitutions(answers) {
     __ADMIN_PASSWORD__: answers.admin.password,
     __DB_CONNECTION__: answers.connection || '',
     __CONNECTION_NOTE__: connectionNote(answers)
+  }, tenancySubstitutions(answers.tenancy || []));
+}
+
+/**
+ * The code a multi-tenant app has and a plain one does not.
+ *
+ * Every token exists in both, so a template can use it unconditionally: in a
+ * plain app each expands to nothing, and a line holding only that token is
+ * removed rather than left blank (see fill).
+ */
+function tenancySubstitutions(levels) {
+  var on = levels.length > 0;
+  var slots = {};
+  levels.forEach(function (l) { slots[l.key] = { name: l.name, header: l.header }; });
+  var first = levels[0];
+  return {
+    __MT_TENANCY_JSON__: JSON.stringify({ levels: levels, slots: slots }, null, 2),
+    __MT_LEVEL_NAMES__: levels.map(function (l) { return l.label.toLowerCase(); }).join(' → '),
+    __MT_SWITCH_NAME__: on ? 'Switch ' + first.label.toLowerCase() : '',
+    __MT_TABLES_SQL__: levels.map(tenantTableSql).join('\n'),
+
+    // api/db/setup.js
+    __MT_DB_REGISTER__: on ? [
+      '',
+      '// TENANCY — the levels data belongs to (' + levels.map(function (l) { return l.label.toLowerCase(); }).join(', ') + '), from tenancy.js.',
+      '// The UI registers the same ones, so its requests carry the same headers.',
+      "require('@xeplr/db').registerMTs(require('../tenancy').slots);"
+    ].join('\n') : '',
+
+    // api/app.js
+    __MT_APP_REQUIRE__: on ? [
+      "var { mtMiddleware } = require('@xeplr/db');",
+      "var tenants = require('./routes/tenants');"
+    ].join('\n') : '',
+    __MT_APP_MIDDLEWARE__: on ? [
+      '    // Puts the request\'s ' + levels.map(function (l) { return l.header; }).join(' / ') + ' on every query: rows are',
+      '    // stamped with it on insert, and only its rows are read.',
+      '    middleware: [mtMiddleware()],'
+    ].join('\n') : '',
+    __MT_APP_ROUTES__: on ? [
+      '      // The ' + levels.map(function (l) { return l.table; }).join(' / ') + ' the picker lists and adds to.',
+      "      '/api/tenants': tenants.router,"
+    ].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 ? [
+      "import { registerMTs } from '@xeplr/ui-account'",
+      "import { tenancy } from './tenancy.js'"
+    ].join('\n') : '',
+    __MT_UI_REGISTER__: on ? [
+      '',
+      '// TENANCY — the same levels as the API. authFetch then sends the chosen',
+      '// ' + levels.map(function (l) { return l.label.toLowerCase(); }).join(' and ') + ' on every request.',
+      'registerMTs(tenancy.slots)'
+    ].join('\n') : '',
+
+    // ui/src/App.jsx
+    __MT_APP_UI_IMPORTS__: on ? "import SelectScope, { ScopeGate } from './pages/SelectScope.jsx'" : '',
+    __MT_DRAWER_ITEM__: on ? "    { name: 'Switch " + first.label.toLowerCase() + "', icon: SwitchIcon, clickHandler: () => navigate('/select') }," : '',
+    __MT_SWITCH_ICON__: on ? [
+      'const SwitchIcon = (',
+      '  <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"',
+      '       strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">',
+      '    <path d="M17 1l4 4-4 4" /><path d="M3 11V9a4 4 0 0 1 4-4h14" />',
+      '    <path d="M7 23l-4-4 4-4" /><path d="M21 13v2a4 4 0 0 1-4 4H3" />',
+      '  </svg>',
+      ')',
+      ''
+    ].join('\n') : '',
+    __MT_SELECT_ROUTE__: on ? [
+      '      {/* Picking the ' + levels.map(function (l) { return l.label.toLowerCase(); }).join(' and ') + ' — signed in, but outside the gate below. */}',
+      '      <Route element={<ProtectedRoute><Shell /></ProtectedRoute>}>',
+      '        <Route path="/select" element={<SelectScope />} />',
+      '      </Route>',
+      ''
+    ].join('\n') : '',
+    __MT_GATE_OPEN__: on ? '<ScopeGate>' : '',
+    __MT_GATE_CLOSE__: on ? '</ScopeGate>' : ''
   };
 }
 
+/** 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';
+  return [
+    '-- ' + level.label + ' (' + level.key + ', header ' + level.header + ') — parents: ' + parents + '.',
+    'CREATE TABLE IF NOT EXISTS "' + level.table + '" (',
+    '  "id"                  varchar(25) PRIMARY KEY,',
+    '  "name"                varchar(200) NOT NULL,',
+    '  "isActive"            boolean DEFAULT true,',
+    '  "mtId1"               varchar(25),',
+    '  "mtId2"               varchar(25),',
+    '  "mtId3"               varchar(25),',
+    '  "mtId4"               varchar(25),',
+    '  "recordCreatedDate"   timestamptz DEFAULT now(),',
+    '  "recordModifiedDate"  timestamptz DEFAULT now(),',
+    '  "recordCreatedBy"     varchar(25),',
+    '  "recordModifiedBy"    varchar(25)',
+    ');',
+    ''
+  ].join('\n');
+}
+
 /**
  * The comment above the connection setting.
  *
@@ -72,6 +179,11 @@ function connectionNote(answers) {
 }
 
 function fill(body, subs) {
+  // A line holding nothing but a token that expands to nothing goes entirely —
+  // the plain app's files read as if the tenancy lines were never there.
+  body = body.replace(/^[ \t]*(__[A-Z][A-Z0-9_]*[A-Z0-9]__)[ \t]*\r?\n/gm, function (line, token) {
+    return subs[token] === '' ? '' : line;
+  });
   // The inner name must START and END with a letter or digit.
   //
   // Without that, a greedy match on `__PREFIX___PORT` takes `__PREFIX___` —
@@ -120,8 +232,14 @@ function generate(answers, target) {
   var subs = substitutions(answers);
   var written = [];
 
-  walk(TEMPLATES).forEach(function (src) {
-    var rel = path.relative(TEMPLATES, src);
+  var sources = {};
+  walk(TEMPLATES).forEach(function (src) { sources[path.relative(TEMPLATES, src)] = src; });
+  if (answers.tenancy && answers.tenancy.length) {
+    walk(TENANCY_TEMPLATES).forEach(function (src) { sources[path.relative(TENANCY_TEMPLATES, src)] = src; });
+  }
+
+  Object.keys(sources).forEach(function (rel) {
+    var src = sources[rel];
     var dir = path.dirname(rel);
     var base = path.basename(rel);
     var outName = RENAME[base] || base;

package/lib/nextSteps.js

@@ -1,37 +1,52 @@
+var path = require('path');
+
 /**
- * What to do now that the files exist.
+ * What to do now that the files exist — and, when the installer set the
+ * project up itself, only what is left.
  *
- * Printed at the end because the one thing a generator cannot do for you is
- * the database connection — and a project that looks finished but will not
- * start is worse than one that says what is left.
+ * @param setup  the result of lib/setup.js, or null when it was not run
  */
-function describe(answers, dir) {
-  var p = answers.prefix;
+function describe(answers, dir, setup) {
+  var api = answers.name + '/api';
   var head = ['', '  Created ' + dir, ''];
+  var installed = setup && (setup.ok || (setup.failed && setup.failed.args[0] !== 'install'));
+
+  if (setup && !setup.ok) {
+    head = head.concat([
+      '  SET-UP STOPPED at: ' + setup.failed.label,
+      '  The messages above say why. Fix that, then run it again:',
+      '',
+      '    cd ' + path.join(answers.name, path.basename(setup.failed.cwd)) + '  &&  npm ' + setup.failed.args.join(' '),
+      ''
+    ]);
+  }
 
   if (!answers.connection) {
     head = head.concat([
       '  ONE THING LEFT — your database connection:',
       '',
-      '    cd ' + answers.name + '/api  &&  npm install  &&  npm run db:encrypt',
+      '    cd ' + api + '  &&  ' + (installed ? '' : 'npm install  &&  ') + 'npm run db:encrypt  &&  npm run setup',
       '',
       '  It asks for your database details and fills them in for you.',
       ''
     ]);
   }
 
-  return head.concat([
-    '  Then:',
-    '',
-    '    cd ' + answers.name + '/api   &&  npm install  &&  npm run setup',
-    '    npm run start-auth            # sign-in, port ' + answers.ports.auth,
-    '    npm run start-api             # your API, port ' + answers.ports.api,
-    '',
-    '    cd ../ui                      &&  npm install',
-    '    npm run dev                   # the app, port ' + answers.ports.ui,
+  var ready = setup && setup.ok && setup.databases;
+  var start = ready ? ['  Start it — three terminals:', ''] : ['  Then:', ''];
+  if (!ready && answers.connection) {
+    start.push('    cd ' + api + '   &&  npm install  &&  npm run setup');
+    start.push('    cd ../ui' + ' '.repeat(Math.max(1, api.length - 5)) + '&&  npm install');
+    start.push('');
+  }
+
+  return head.concat(start, [
+    '    cd ' + api + '  &&  npm run start-auth     # sign-in, port ' + answers.ports.auth,
+    '    cd ' + api + '  &&  npm run start-api      # your API, port ' + answers.ports.api,
+    '    cd ' + answers.name + '/ui   &&  npm run dev            # the app, port ' + answers.ports.ui,
     '',
-    '  Then open http://localhost:' + answers.ports.ui + ' and sign in as',
-    '  ' + answers.admin.email + '.',
+    '  Sign-in needs Redis running. Then open http://localhost:' + answers.ports.ui,
+    '  and sign in as ' + answers.admin.email + '.',
     ''
   ]).join('\n');
 }

package/lib/plan.js

@@ -21,8 +21,16 @@ function describe(answers) {
   L.push('');
   L.push('  You will sign in as ' + answers.admin.email + '.');
   L.push('');
+  if (answers.tenancy && answers.tenancy.length) {
+    L.push('  Multi-tenant: ' + answers.tenancy.map(function (l) { return l.label.toLowerCase() + ' (' + l.header + ')'; }).join(' → ') + '.');
+    L.push('  Choosing one is the first screen after signing in.');
+  } else {
+    L.push('  Not multi-tenant: data belongs to the app as a whole.');
+  }
+  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/lib/questions.js

@@ -20,6 +20,46 @@ function envPrefix(name) {
   return name.toUpperCase().replace(/-/g, '_');
 }
 
+// ── tenancy ──────────────────────────────────────────────────────────────
+//
+// At most four levels — @xeplr/db has four tenant columns (mtId1-4) — named
+// outermost first: "company", or "company, workspace".
+var LEVEL_RE = /^[a-z][a-z ]{0,30}[a-z]$/;
+
+function plural(word) {
+  if (/[^aeiou]y$/.test(word)) return word.slice(0, -1) + 'ies';
+  if (/(s|x|z|ch|sh)$/.test(word)) return word + 'es';
+  return word + 's';
+}
+
+/**
+ * "company, business unit" → one entry per level, every name derived once:
+ *   { key: 'l2', label: 'Business unit', name: 'businessUnitId',
+ *     header: 'x-business-unit-id', table: 'business_units' }
+ *
+ * @returns {object[]}  or throws, with a sentence to show
+ */
+function tenancyLevels(text) {
+  var words = String(text || '').split(',').map(function (w) { return w.trim().toLowerCase().replace(/\s+/g, ' '); }).filter(Boolean);
+  if (!words.length) throw new Error('Name at least one level, e.g. company.');
+  if (words.length > 4) throw new Error('At most four levels.');
+  words.forEach(function (w) {
+    if (!LEVEL_RE.test(w)) throw new Error('"' + w + '" — letters and spaces only, e.g. company or business unit.');
+  });
+  if (new Set(words).size !== words.length) throw new Error('Each level needs a different name.');
+  return words.map(function (w, i) {
+    var parts = w.split(' ');
+    var camel = parts[0] + parts.slice(1).map(function (p) { return p[0].toUpperCase() + p.slice(1); }).join('');
+    return {
+      key: 'l' + (i + 1),
+      label: w[0].toUpperCase() + w.slice(1),
+      name: camel + 'Id',
+      header: 'x-' + parts.join('-') + '-id',
+      table: parts.slice(0, -1).concat(plural(parts[parts.length - 1])).join('_')
+    };
+  });
+}
+
 function secret() {
   return crypto.randomBytes(32).toString('hex');
 }
@@ -76,6 +116,24 @@ async function collect(session, argvName) {
     }
   });
 
+  // ── tenancy ───────────────────────────────────────────────────────────
+  //
+  // Whether data belongs to companies (or workspaces, or both). Off, the app
+  // has no tenancy at all. On, every row is stamped with the company it was
+  // made in, every query sees only that company's rows, and picking one is
+  // the first screen after signing in.
+  var tenancy = [];
+  var multiTenant = await session.confirm('Multi-tenant — does data belong to companies (or similar)?', false);
+  if (multiTenant) {
+    var levelsText = await session.ask('  Tenancy levels, outermost first?', {
+      default: 'company',
+      validate: function (v) {
+        try { tenancyLevels(v); return true; } catch (err) { return err.message; }
+      }
+    });
+    tenancy = tenancyLevels(levelsText);
+  }
+
   // ── the database ──────────────────────────────────────────────────────
   //
   // ASKED, not defaulted, and not left for the reader to do by hand either.
@@ -115,6 +173,7 @@ async function collect(session, argvName) {
     ports: { ui: base, auth: base + 1, api: base + 2 },
     databases: { auth: name + '_auth', api: name + '_api' },
     admin: { email: adminEmail, password: adminPassword },
+    tenancy: tenancy,
 
     // GENERATED, never asked. Nobody should be inventing these by hand, and a
     // prompt invites a weak answer or a reused one.
@@ -122,4 +181,4 @@ async function collect(session, argvName) {
   };
 }
 
-module.exports = { collect: collect, envPrefix: envPrefix, NAME_RE: NAME_RE };
+module.exports = { collect: collect, envPrefix: envPrefix, tenancyLevels: tenancyLevels, NAME_RE: NAME_RE };

package/lib/setup.js

@@ -0,0 +1,59 @@
+var { spawn } = require('child_process');
+var path = require('path');
+
+/**
+ * The steps that turn written files into a project that starts: packages
+ * installed, both databases created, sign-in tables and permissions in place.
+ *
+ * The database step needs the connection. Without one it is left out, and
+ * nextSteps says how to finish.
+ */
+function steps(answers, target) {
+  var api = path.join(target, 'api');
+  var ui = path.join(target, 'ui');
+  var list = [
+    { label: 'Installing the API packages', cwd: api, args: ['install'] },
+    { label: 'Installing the UI packages', cwd: ui, args: ['install'] }
+  ];
+  if (answers.connection) {
+    list.push({ label: 'Creating the databases, sign-in tables and permissions', cwd: api, args: ['run', 'setup'] });
+  }
+  return list;
+}
+
+/**
+ * npm, streaming its output as it goes — an install is minutes of silence
+ * otherwise, and its own error text is the most useful thing to see if it
+ * fails.
+ *
+ * shell on Windows only: npm is npm.cmd there, and Node refuses to spawn a
+ * .cmd without a shell. Nowhere else does anything go through one.
+ */
+function npm(args, cwd, runner) {
+  if (runner) return runner(args, cwd);
+  return new Promise(function (resolve) {
+    var child = spawn('npm', args, { cwd: cwd, stdio: 'inherit', shell: process.platform === 'win32' });
+    child.on('error', function (err) { console.error('  ' + err.message); resolve(1); });
+    child.on('exit', function (code) { resolve(code === null ? 1 : code); });
+  });
+}
+
+/**
+ * @param options.runner  (args, cwd) → Promise<exit code>; for tests
+ * @param options.log     line printer (default console.log)
+ * @returns {Promise<{ ok: boolean, databases: boolean, failed?: object }>}
+ */
+async function run(answers, target, options) {
+  options = options || {};
+  var log = options.log || console.log;
+  var list = steps(answers, target);
+  for (var i = 0; i < list.length; i++) {
+    var step = list[i];
+    log('\n  ' + step.label + '…  (npm ' + step.args.join(' ') + ', in ' + path.relative(process.cwd(), step.cwd) + ')\n');
+    var code = await npm(step.args, step.cwd, options.runner);
+    if (code !== 0) return { ok: false, databases: false, failed: step };
+  }
+  return { ok: true, databases: !!answers.connection };
+}
+
+module.exports = { run: run, steps: steps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/cli",
-  "version": "0.1.2",
+  "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>",
@@ -31,6 +31,7 @@
     "bin/",
     "lib/",
     "templates/",
+    "templates-tenancy/",
     "README.md"
   ],
   "dependencies": {

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,5 +1,12 @@
 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.
@@ -16,6 +23,29 @@ module.exports = function buildApp(extraRoutes) {
       publicPaths: ['/health']
     },
     log: { logDir: process.env.LOG_DIR || './logs' },
-    routes: Object.assign({}, extraRoutes || {}, { '/': routes })
+__MT_APP_MIDDLEWARE__
+    routes: Object.assign({}, extraRoutes || {}, {
+      '/': routes,
+__MT_APP_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
+      //
+      // access: true — each route answers only a caller whose permissions name
+      // it ("Save factory record", "Publish factory screen", ...). Granted to
+      // Super Admin and CompanyAdmin (everything), Creator (use the screens) and
+      // Viewer (read) by node_modules/@xeplr/factory/migrations-auth.
+      '/api': factory.router({
+        access: true,
+        auth: {
+          view: memberGate,
+          write: memberGate,
+          // Designing, new forms and publishing change tables: Super Admin
+          // only (routes/access.js).
+          design: [memberGate, access.superAdminOnly]
+        }
+      })
+    })
   });
 };