@xeplr/cli 0.1.2 → 0.1.3

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

@@ -1,64 +1,66 @@
-// The panel beside the sample form. It is here so the first thing anybody
-// builds is explained where they are looking, rather than in a document they
-// have to go and find.
+// The panel beside the sample. It is here so the first thing anybody builds is
+// explained where they are looking, rather than in a document they have to go
+// and find.
 export default function TasksHelp() {
   return (
     <aside className="app-help">
       <div className="app-help-badge">Sample</div>
       <h2>This page is an example</h2>
       <p>
-        A task has a title, a description, a status and a due date. Nothing here
-        is special — it is the same five pieces you will write for anything your
-        app stores. Delete it once you have your own.
+        A task has a title, a status, a due date and a description. Neither the
+        list nor the form is written by hand — both are <strong>screens</strong>,
+        and the tasks are saved in an ordinary <code>tasks</code> table with one
+        column per field.
       </p>
 
-      <h3>Add your own, in five pieces</h3>
+      <h3>Change it</h3>
+      <p>
+        Open <strong>Designer</strong> in the side rail. Add a field, move one,
+        change a label or a colour — then <strong>Publish</strong>. The table
+        gains its new column as you publish.
+      </p>
+
+      <h3>Add your own</h3>
       <ol className="app-help-steps">
         <li>
-          <strong>The table</strong>
-          <code>api/migrations/0002_things.sql</code>
-          <span>Runs by itself when the API next starts.</span>
-        </li>
-        <li>
-          <strong>The model</strong>
-          <code>api/models/Thing.js</code>
-          <span>
-            Names the table and lists the fields, with the rules for each. Those
-            rules are checked on every save.
-          </span>
+          <strong>Describe it</strong>
+          <code>api/screens/project/project.entity.json</code>
+          <span>Its name and fields — copy <code>task/task.entity.json</code>.</span>
         </li>
         <li>
-          <strong>The routes</strong>
-          <code>api/routes/index.js</code>
-          <span>
-            One line — hand the model to <code>genericRoute</code> and you get
-            list, fetch, save and delete. You write none of them.
-          </span>
+          <strong>Make its screens</strong>
+          <code>npx xeplr-factory screens screens/project/project.entity.json -o screens/project</code>
+          <span>From the api folder. Then list them in <code>api/screens/index.js</code>.</span>
         </li>
         <li>
           <strong>The page</strong>
-          <code>ui/src/pages/Things.jsx</code>
-          <span>
-            Plus a file for the calls and one for the form's behaviour, so a new
-            look means replacing the page only.
-          </span>
+          <code>ui/src/pages/Projects.jsx</code>
+          <span>Copy <code>Tasks.jsx</code> and load <code>project_list</code>.</span>
         </li>
         <li>
           <strong>The menu entry</strong>
-          <code>api/migrations-auth/000N_things_menu.sql</code>
+          <code>api/migrations-auth/000N_projects_menu.sql</code>
           <span>
             The side-rail item appears only if its name exists in the database,
             spelled exactly the same.
           </span>
         </li>
       </ol>
+      <p>Restart the API and the new table is created for you.</p>
+
+      <h3>More than saving</h3>
+      <p>
+        A value worked out on save, an email afterwards, a list only managers
+        see: <code>api/screens/task/task.hooks.js</code> — before, after, error
+        and override, for save, get and delete.
+      </p>
 
       <h3>Two things that catch people</h3>
       <ul className="app-help-notes">
         <li>
-          Keep every data address under <code>/api</code>. Serve data at{' '}
-          <code>/things</code> and it hides the <em>page</em> at the same
-          address — you get raw data instead of your app.
+          Once a screen is published, the <em>database</em> holds its design.
+          Editing its <code>.screen.json</code> afterwards changes nothing — use
+          the Designer.
         </li>
         <li>
           A new menu entry is remembered for ten minutes. Restart the sign-in

package/templates/ui/vite.config.js

@@ -43,7 +43,7 @@ export default defineConfig(({ mode }) => {
     plugins: [react()],
     // Force every import to THIS app's copy, so hook-using libraries don't
     // load twice and break the rules of hooks in ways that read as impossible.
-    resolve: { dedupe: ['react', 'react-dom', 'react-router-dom'] },
+    resolve: { dedupe: ['react', 'react-dom', 'react-router-dom', '@xeplr/ui-canvas', '@xeplr/ui-table'] },
     server: { port, strictPort: true, proxy },
     preview: { port, strictPort: true }
   }

package/templates-tenancy/api/migrations/0001_tenants.sql

@@ -0,0 +1,8 @@
+-- The tables the picker lists and adds to: __MT_LEVEL_NAMES__.
+--
+-- Deliberately plain — an id and a name. Add what your app needs (an address,
+-- a plan) with a later migration. Who may use one is NOT here: that is a
+-- membership row in the sign-in database (userTenantsMapping), made for
+-- whoever adds it.
+
+__MT_TABLES_SQL__

package/templates-tenancy/api/migrations-auth/0004_switch_menu.sql

@@ -0,0 +1,10 @@
+-- "__MT_SWITCH_NAME__" — the drawer item that goes back to the picker.
+--
+-- Public: everybody who signs in works inside one, so everybody can change it.
+-- The name must match ui/src/App.jsx's drawerItems entry EXACTLY.
+
+INSERT INTO "menus" (id, name, "menuGroup", "isPublic", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), '__MT_SWITCH_NAME__', '', true, true, '*', now(), now()
+WHERE NOT EXISTS (SELECT 1 FROM "menus" WHERE name = '__MT_SWITCH_NAME__');
+
+UPDATE "menus" SET "isPublic" = true WHERE name = '__MT_SWITCH_NAME__';

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

@@ -0,0 +1,130 @@
+// THE TENANTS — what the picker lists and adds to (__MT_LEVEL_NAMES__), and
+// the check that a caller belongs to the one their request names.
+//
+//   GET  /api/tenants/l1          the ones at that level the caller belongs to
+//   POST /api/tenants/l1 { name } add one — and make the caller a member of it
+//
+// A level below the first lists only the children of the one chosen above it,
+// which arrives as that level's header like on every other request.
+//
+// MEMBERSHIP lives in the sign-in database (userTenantsMapping): user, level,
+// id, role. Adding one makes you its member. Super Admin sees and may enter
+// every one.
+
+var express = require('express');
+var { getMtContext } = require('@xeplr/db');
+var { generateId } = require('@xeplr/utils');
+var { respond } = require('@xeplr/utils/lib/response');
+var { HTTP, STATUS } = require('@xeplr/utils/isomorphic');
+var authLib = require('@xeplr/auth');
+var tenancy = require('../tenancy');
+var appDatabase = require('../db/setup');
+
+// The sign-in database, read directly — this app does not run the sign-in
+// service in its own process, it only needs its membership table.
+var auth = authLib.attach();
+
+// Whoever creates one is its member, with this role: the outermost level's
+// admin, a creator below it. Roles from @xeplr/factory's access migration.
+var CREATOR_ROLE = { 1: 'CompanyAdmin' };
+var DEEPER_ROLE = 'Creator';
+
+function isSuperAdmin(req) {
+  var roles = (req.access && req.access.roles) || (req.user && req.user.roles) || [];
+  return roles.indexOf('Super Admin') !== -1;
+}
+
+var membership = null;
+
+/**
+ * Refuses a request naming a company (or any level) the caller is not a
+ * member of — 403 "Not authorized for companyId …". A header that is absent
+ * is let through: nothing is read or written without one anyway.
+ */
+async function memberGate(req, res, next) {
+  if (isSuperAdmin(req)) return next();
+  if (!membership) {
+    await auth.ready();
+    membership = authLib.mtMembershipMiddleware({ userTenantsMapping: auth.model('UserTenantsMapping') });
+  }
+  return membership(req, res, next);
+}
+
+function levelOf(key) {
+  var level = tenancy.levels.filter(function(l) { return l.key === key; })[0];
+  if (!level) throw status(HTTP.NOT_FOUND, 'No tenancy level "' + key + '"');
+  return level;
+}
+
+/** The chosen parents, as mtIdN values — refusing if one is not chosen yet. */
+function parentsOf(level) {
+  var ctx = getMtContext();
+  var index = Number(level.key.slice(1));
+  var values = {};
+  for (var i = 1; i < index; i++) {
+    var parent = tenancy.levels[i - 1];
+    if (!ctx['mtId' + i]) throw status(HTTP.BAD_REQUEST, 'Choose a ' + parent.label.toLowerCase() + ' first');
+    values['mtId' + i] = ctx['mtId' + i];
+  }
+  return values;
+}
+
+var router = express.Router();
+router.use(express.json());
+router.use(memberGate);
+
+router.get('/:level', handle(async function(req) {
+  var level = levelOf(req.params.level);
+  var knex = await appDatabase;
+  var query = knex(level.table).select('id', 'name').where('isActive', true).where(parentsOf(level)).orderBy('name');
+  if (!isSuperAdmin(req)) {
+    await auth.ready();
+    var ids = await auth.conn()('userTenantsMapping')
+      .where({ userId: req.user.id, level: level.key, isActive: true })
+      .pluck('value');
+    query.whereIn('id', ids);
+  }
+  return query;
+}));
+
+router.post('/:level', handle(async function(req) {
+  var level = levelOf(req.params.level);
+  var name = String((req.body && req.body.name) || '').trim();
+  if (!name || name.length > 200) throw status(HTTP.VALIDATION_ERROR, 'Give the ' + level.label.toLowerCase() + ' a name, up to 200 characters');
+  var who = String(req.user.id).slice(0, 25);
+  var now = new Date();
+  var row = Object.assign({ id: generateId(), name: name, isActive: true, recordCreatedDate: now, recordModifiedDate: now, recordCreatedBy: who, recordModifiedBy: who }, parentsOf(level));
+
+  var knex = await appDatabase;
+  await knex(level.table).insert(row);
+
+  await auth.ready();
+  var conn = auth.conn();
+  var roleName = CREATOR_ROLE[Number(level.key.slice(1))] || DEEPER_ROLE;
+  var role = await conn('roles').where({ name: roleName, isActive: true }).first('id');
+  await conn('userTenantsMapping').insert({
+    id: generateId(), userId: req.user.id, level: level.key, value: row.id, roleId: role ? role.id : null,
+    isActive: true, mtId1: '*', recordCreatedDate: now, recordModifiedDate: now, recordCreatedBy: who, recordModifiedBy: who
+  });
+  return [{ id: row.id, name: row.name }];
+}));
+
+function handle(fn) {
+  return async function(req, res) {
+    try {
+      respond(res, HTTP.OK, STATUS.SUCCESS, 'success', { dataArray: (await fn(req)) || [] });
+    } catch (err) {
+      var code = err.status || HTTP.SERVER_ERROR;
+      if (code >= 500) console.error('[tenants]', err);
+      res.status(code).send({ code: code >= 500 ? STATUS.SERVER_ERROR : STATUS.BAD_REQUEST, message: code >= 500 ? 'Something went wrong' : err.message, error: null, dataArray: [] });
+    }
+  };
+}
+
+function status(code, message) {
+  var e = new Error(message);
+  e.status = code;
+  return e;
+}
+
+module.exports = { router: router, memberGate: memberGate };

package/templates-tenancy/api/tenancy.js

@@ -0,0 +1,12 @@
+// TENANCY — the levels this app's data belongs to, outermost first
+// (__MT_LEVEL_NAMES__).
+//
+// Every row a screen saves is stamped with the chosen one(s) in mtId1… and
+// every read sees only those rows. The UI registers the SAME levels
+// (ui/src/tenancy.js) so its requests carry the same headers; keep the two in
+// step if you ever change them.
+//
+//   levels  one entry per level: its header, the column name it stands for,
+//           and the table its choices live in
+//   slots   the shape @xeplr/db's registerMTs takes
+module.exports = __MT_TENANCY_JSON__;

package/templates-tenancy/ui/src/pages/SelectScope.css

@@ -0,0 +1,45 @@
+.app-select { max-width: 560px; }
+
+.app-select h1 { font-size: 26px; margin: 0 0 6px; }
+
+.app-select-level {
+  margin: 22px 0;
+  padding: 16px 18px;
+  border: 1px solid var(--xeplr-border-primary);
+  border-radius: 10px;
+  background: var(--xeplr-bg-secondary);
+}
+
+.app-select-level.is-disabled { opacity: 0.55; }
+
+.app-select-level h2 { font-size: 15px; margin: 0 0 10px; }
+
+.app-select-items { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 12px; }
+
+.app-select-item {
+  padding: 8px 14px;
+  border-radius: 8px;
+  border: 1px solid var(--xeplr-border-primary);
+  background: var(--xeplr-bg-primary);
+  color: var(--xeplr-text-primary);
+  font: inherit;
+  cursor: pointer;
+}
+
+.app-select-item.is-chosen {
+  border-color: var(--xeplr-accent);
+  background: var(--xeplr-accent-muted);
+  color: var(--xeplr-text-primary);
+}
+
+.app-select-add { display: flex; gap: 8px; }
+
+.app-select-add input {
+  flex: 1;
+  padding: 8px 10px;
+  border-radius: 8px;
+  border: 1px solid var(--xeplr-input-border);
+  background: var(--xeplr-input-bg);
+  color: var(--xeplr-input-text);
+  font: inherit;
+}

package/templates-tenancy/ui/src/pages/SelectScope.jsx

@@ -0,0 +1,154 @@
+// THE FIRST SCREEN AFTER SIGNING IN — choose the __MT_LEVEL_NAMES__ to work in.
+//
+// Everything the app shows and saves afterwards belongs to that choice:
+// authFetch sends it as a header on every request, the API stamps new rows
+// with it and reads only its rows.
+//
+// Shown once per browser tab (ScopeGate below), with the last choice already
+// selected, so returning is one click. "__MT_SWITCH_NAME__" in the side rail
+// comes back here.
+import { useCallback, useEffect, useState } from 'react'
+import { Navigate, useLocation, useNavigate } from 'react-router-dom'
+import {
+  authFetch, getActiveScope, setActiveScope, getLastScope, setLastScope, saveReturnTo, consumeReturnTo
+} from '@xeplr/ui-account'
+import { tenancy } from '../tenancy.js'
+import './SelectScope.css'
+
+// Per tab: a new tab, or a new sign-in, asks again.
+const CONFIRMED = 'app:scopeConfirmed'
+const confirmed = () => { try { return sessionStorage.getItem(CONFIRMED) === '1' } catch (e) { return false } }
+const setConfirmed = (yes) => { try { yes ? sessionStorage.setItem(CONFIRMED, '1') : sessionStorage.removeItem(CONFIRMED) } catch (e) {} }
+
+/** Lets the app's pages render only once every level is chosen in this tab. */
+export function ScopeGate({ children }) {
+  const location = useLocation()
+  const complete = tenancy.levels.every((l) => getActiveScope(l.key))
+  if (!complete || !confirmed()) {
+    saveReturnTo(location)
+    return <Navigate to="/select" replace />
+  }
+  return children
+}
+
+export default function SelectScope() {
+  const navigate = useNavigate()
+  // What is chosen so far, per level — starting from the active or last choice.
+  // Made active straight away — before the lists below load, since a level's
+  // list is asked for with the level above it as a header.
+  const [chosen, setChosen] = useState(() => {
+    const start = Object.fromEntries(tenancy.levels.map((l) => [l.key, getActiveScope(l.key) || getLastScope(l.key) || null]))
+    tenancy.levels.forEach((l) => setActiveScope(l.key, start[l.key]))
+    return start
+  })
+
+  const choose = useCallback((index, item) => {
+    setChosen((c) => {
+      const next = { ...c, [tenancy.levels[index].key]: item }
+      // A different parent: whatever was chosen below it belonged to the old one.
+      tenancy.levels.slice(index + 1).forEach((l) => { next[l.key] = null })
+      return next
+    })
+    // Set as it is chosen, so the level below lists this one's children.
+    setActiveScope(tenancy.levels[index].key, item)
+    tenancy.levels.slice(index + 1).forEach((l) => setActiveScope(l.key, null))
+    setConfirmed(false)
+  }, [])
+
+  const complete = tenancy.levels.every((l) => chosen[l.key])
+
+  const go = () => {
+    tenancy.levels.forEach((l) => { setActiveScope(l.key, chosen[l.key]); setLastScope(l.key, chosen[l.key]) })
+    setConfirmed(true)
+    navigate(consumeReturnTo() || '/home', { replace: true })
+  }
+
+  return (
+    <div className="app-select">
+      <h1>Where are you working?</h1>
+      <p className="app-page-lead">Everything you see and save next belongs to this choice.</p>
+
+      {tenancy.levels.map((level, i) => {
+        const parentChosen = tenancy.levels.slice(0, i).every((l) => chosen[l.key])
+        return (
+          <LevelChoice
+            key={level.key + (i ? ':' + (chosen[tenancy.levels[i - 1].key] || {}).id : '')}
+            level={level}
+            enabled={parentChosen}
+            value={chosen[level.key]}
+            onChoose={(item) => choose(i, item)}
+          />
+        )
+      })}
+
+      <button type="button" className="app-btn" disabled={!complete} onClick={go}>Continue</button>
+    </div>
+  )
+}
+
+function LevelChoice({ level, enabled, value, onChoose }) {
+  const [items, setItems] = useState(null)
+  const [error, setError] = useState(null)
+  const [adding, setAdding] = useState('')
+  const [busy, setBusy] = useState(false)
+  const noun = level.label.toLowerCase()
+
+  useEffect(() => {
+    if (!enabled) return
+    authFetch('/api/tenants/' + level.key).then((body) => {
+      const rows = body.dataArray || []
+      setItems(rows)
+      // A remembered choice that is no longer on the list is not a choice.
+      if (value && !rows.some((r) => r.id === value.id)) onChoose(null)
+      else if (!value && rows.length === 1) onChoose(rows[0])
+    }, (e) => setError(e.message))
+  }, [enabled, level.key])            // eslint-disable-line react-hooks/exhaustive-deps
+
+  const add = async (e) => {
+    e.preventDefault()
+    setBusy(true)
+    try {
+      const body = await authFetch('/api/tenants/' + level.key, { method: 'POST', body: JSON.stringify({ name: adding }) })
+      const created = body.dataArray[0]
+      setItems((list) => [...(list || []), created].sort((a, b) => a.name.localeCompare(b.name)))
+      setAdding('')
+      setError(null)
+      onChoose(created)
+    } catch (err) {
+      setError(err.message)
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <section className={'app-select-level' + (enabled ? '' : ' is-disabled')}>
+      <h2>{level.label}</h2>
+      {!enabled && <p className="app-sub">Choose the one above first.</p>}
+      {enabled && items === null && !error && <p className="app-sub">Loading…</p>}
+      {error && <div className="app-error">{error}</div>}
+      {enabled && items && (
+        <>
+          {items.length === 0 && <p className="app-sub">No {noun} yet — add the first one.</p>}
+          <div className="app-select-items">
+            {items.map((item) => (
+              <button
+                key={item.id}
+                type="button"
+                className={'app-select-item' + (value && value.id === item.id ? ' is-chosen' : '')}
+                aria-pressed={!!value && value.id === item.id}
+                onClick={() => onChoose(item)}
+              >
+                {item.name}
+              </button>
+            ))}
+          </div>
+          <form className="app-select-add" onSubmit={add}>
+            <input value={adding} onChange={(e) => setAdding(e.target.value)} placeholder={'New ' + noun + ' name'} aria-label={'New ' + noun + ' name'} />
+            <button type="submit" className="app-btn app-btn-quiet" disabled={busy || !adding.trim()}>Add {noun}</button>
+          </form>
+        </>
+      )}
+    </section>
+  )
+}

package/templates-tenancy/ui/src/tenancy.js

@@ -0,0 +1,3 @@
+// TENANCY — the same levels as the API's api/tenancy.js (__MT_LEVEL_NAMES__).
+// Keep the two in step.
+export const tenancy = __MT_TENANCY_JSON__

package/templates/api/migrations/0001_tasks.sql

@@ -1,23 +0,0 @@
--- The sample table.
---
--- `id` is varchar(25) because ids are minted by the framework
--- (@xeplr/utils' generateId) rather than by the database.
---
--- `isActive` is what makes a delete SOFT: the generic delete route sets it
--- false and every query filters on it, so a deleted row stops appearing
--- without ever leaving the table.
-
-CREATE TABLE IF NOT EXISTS "tasks" (
-  "id"                  varchar(25) PRIMARY KEY,
-  "title"               varchar(200) NOT NULL,
-  "description"         varchar(1000),
-  "status"              varchar(20) NOT NULL DEFAULT 'todo',
-  "dueDate"             date,
-  "isActive"            boolean DEFAULT true,
-  "recordCreatedDate"   timestamptz,
-  "recordModifiedDate"  timestamptz,
-  "recordCreatedBy"     varchar(25),
-  "recordModifiedBy"    varchar(25)
-);
-
-CREATE INDEX IF NOT EXISTS "tasks_status_idx" ON "tasks" ("status");

package/templates/api/models/Task.js

@@ -1,48 +0,0 @@
-var { BaseModel } = require('@xeplr/db');
-
-/**
- * A task. The sample model — deliberately small, and deliberately showing the
- * three things almost every real model needs: required fields, a value
- * restricted to a known set, and a date.
- *
- * `jsonSchema` is not decoration. It is checked on every insert and update, so
- * a bad value is refused by the API with a message naming the field, rather
- * than reaching the database and failing as a constraint error nobody can read.
- */
-class Task extends BaseModel {
-  static get tableName() { return 'tasks'; }
-  static get idColumn() { return 'id'; }
-
-  // Rows are NOT scoped to a company/workspace here, because this app has not
-  // declared any tenancy levels. Leave it as the default (true) and add
-  // registerMTs() later, and every row written before that has no owner.
-  static get multiTenant() { return false; }
-
-  static get jsonSchema() {
-    return {
-      type: 'object',
-      required: ['title'],
-      properties: {
-        // 25 characters, because that is what the framework's own id generator
-        // produces (see genericController — ids are minted there, not here).
-        id: { type: 'string', maxLength: 25 },
-        title: { type: 'string', minLength: 1, maxLength: 200 },
-        description: { type: ['string', 'null'], maxLength: 1000 },
-        status: { type: 'string', enum: ['todo', 'in_progress', 'done'] },
-        dueDate: { type: ['string', 'null'] },
-        isActive: { type: 'boolean' },
-        recordCreatedDate: { type: ['string', 'null'] },
-        recordModifiedDate: { type: ['string', 'null'] },
-        recordCreatedBy: { type: ['string', 'null'], maxLength: 25 },
-        recordModifiedBy: { type: ['string', 'null'], maxLength: 25 }
-      }
-    };
-  }
-
-  $beforeInsert() {
-    super.$beforeInsert();   // keeps recordCreatedDate / isActive handling
-    if (!this.status) this.status = 'todo';
-  }
-}
-
-module.exports = Task;

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

@@ -1,34 +0,0 @@
-// MODEL LAYER — plain functions, no React.
-//
-// Kept apart from the screen on purpose: this file could be called from a
-// test, a script, or a different design entirely. `authFetch` attaches the
-// signed-in user's token and returns the PARSED body, throwing on failure.
-import { authFetch } from '@xeplr/ui-account'
-
-export async function listTasks() {
-  const res = await authFetch('/api/tasks')
-  return res.dataArray || []
-}
-
-/**
- * Create and update in one call.
- *
- * The API takes a CHANGESET — an array where each entry is judged by what it
- * carries: no id means create, an id means update, an id plus `deleted: true`
- * means remove. One request can do all three, and the whole array is applied
- * in a single transaction, so a later failure undoes the earlier entries
- * rather than leaving half of them written.
- */
-export function saveTasks(changeset) {
-  return authFetch('/api/tasks/save', {
-    method: 'POST',
-    body: JSON.stringify(changeset)
-  })
-}
-
-export function deleteTasks(ids) {
-  return authFetch('/api/tasks/delete', {
-    method: 'POST',
-    body: JSON.stringify({ ids })
-  })
-}