@xeplr/cli 0.1.1 → 0.1.3

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,8 +23,18 @@ 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 Designer page** — move, add and restyle fields, then Publish; the table
+  gains its new columns as you do. Only the admin roles see it, and the API
+  refuses everyone else.
+- **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.
 
@@ -32,23 +42,45 @@ Already working, with nothing to wire up:
 
 - **Node.js** 18 or later
 - **PostgreSQL**, running, with a user allowed to create databases
+- **Redis**, running — sign-in sessions are kept there
+
+```bash
+# macOS
+brew services start redis
+
+# Linux
+sudo systemctl start redis
+
+# Windows — Redis has no native build, so Docker or WSL
+docker run -d -p 6379:6379 redis
+```
+
+Without Redis, login appears to work and then every request is refused as
+"Invalid or expired token". The sign-in service checks for it at startup and
+refuses to start rather than let you meet that message.
+
+Works on macOS, Linux and Windows. Nothing it generates depends on a unix
+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
@@ -87,6 +119,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,113 @@ 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_FACTORY_AUTH__: on ? [
+      '        // …and only for a ' + first.label.toLowerCase() + ' the caller belongs to.',
+      '        auth: tenants.memberGate'
+    ].join('\n') : '',
+
+    // 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 +181,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 +234,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;
@@ -136,7 +256,14 @@ function generate(answers, target) {
     }
 
     // bin/www is executed directly, so it has to keep the bit that says so.
-    if (outName === 'www') fs.chmodSync(dest, 0o755);
+    //
+    // Wrapped because this is a unix idea. Windows has no executable bit —
+    // chmod there only touches the read-only flag — and a filesystem that
+    // refuses it entirely must not take the whole generation down over a
+    // permission that platform does not use.
+    if (outName === 'www') {
+      try { fs.chmodSync(dest, 0o755); } catch (err) { /* not a unix filesystem */ }
+    }
 
     written.push(path.join(dir, outName));
   });

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,6 +21,13 @@ 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('    ENCRYPTION_KEY and AUTH_JWT_SECRET      generated, not asked');

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.1",
+  "version": "0.1.3",
   "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/api/app.js

@@ -1,5 +1,7 @@
 var createApp = require('@xeplr/base-apis/express');
+var factory = require('@xeplr/factory');
 var routes = require('./routes');
+__MT_APP_REQUIRE__
 
 // 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 +18,23 @@ 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 entity made with the Designer, 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,
+__MT_FACTORY_AUTH__
+      })
+    })
   });
 };

package/templates/api/bin/www

@@ -32,6 +32,8 @@ require('@xeplr/base-apis').checkEnv(require('../env.required.js'), { appName: '
 var path = require('path');
 var { resolveConfig } = require('@xeplr/db');
 var { up } = require('@xeplr/db').sqlMigrator;
+var factory = require('@xeplr/factory');
+var screens = require('../screens');
 
 async function start() {
   // Name the connection before anything uses it — the migrator resolves by
@@ -40,18 +42,30 @@ async function start() {
 
   // Migrations run ON BOOT, so starting the API is the only thing anyone has
   // to remember. Already-applied ones are skipped.
+  //
+  // The screens' own table (factory_screens) first, then this app's.
   var result = await up({
     db: process.env.DB_API,
-    dir: path.join(__dirname, '..', 'migrations'),
+    dir: factory.migrationsDir,
+    extDir: path.join(__dirname, '..', 'migrations'),
     connectionName: 'api'
   });
   console.log(result.migrations.length
     ? '[api] ran ' + result.migrations.length + ' migrations'
     : '[api] migrations up to date');
 
-  // AWAITED before the app is built: routes/index.js hands MODEL CLASSES to
-  // genericRoute at build time, and an unbound class has no connection at all.
-  await require('../db/setup');
+  // AWAITED before the app is built: a model handed to genericRoute at build
+  // time has no connection at all until this has finished.
+  var knex = await require('../db/setup');
+
+  // The screens. A hooks file with a typo ("beforeSave") stops startup here,
+  // rather than silently never running.
+  await factory.init({ knex: knex, hooks: screens.hooks });
+
+  // Screens never published yet are published now, creating their tables.
+  // Ones already published are left alone — the Designer owns them.
+  var published = await factory.publishScreens(screens.documents);
+  if (published.published.length) console.log('[api] published screens: ' + published.published.join(', '));
 
   require('../app')();
 }

package/templates/api/db/setup.js

@@ -2,6 +2,7 @@
 // wire the models to it. Exports the connection promise, awaited by callers
 // that need it ready.
 var { getConnection } = require('@xeplr/db');
+__MT_DB_REGISTER__
 
 // No `|| '__NAME___api'` fallback. DB_API is required at startup
 // (env.required.js), so a default could only ever fire in a process that