@xeplr/cli 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Creates a working xeplr application — API, sign-in and UI — from a few answers.",
   "license": "MIT",
   "author": "xeppie <admin@xeplr.com>",

package/templates/api/README.md

@@ -38,4 +38,5 @@ The API (`@xeplr/base-apis`) and the sign-in service (`@xeplr/auth`), with this
 | `__PREFIX___CONNECTION`, `AUTH_DB_CONNECTION_INFO_ENCRYPTED` | the database, encrypted — `npm run db:encrypt` |
 | `DB_API`, `AUTH_DB_NAME` | the two database names — never guessed |
 | `AUTH_SUPER_ADMIN_EMAIL` / `_PASSWORD` | the first account — created once, when the sign-in database is first set up |
+| `AUTH_TENANT_HEADER` | `none`: one set of roles for everyone. A multi-tenant app names its company header (e.g. `x-company-id`), so a role made inside a company belongs to it |
 | `EMAIL_PROVIDER` and its settings | optional; without them sign-in works, but activation and reset links cannot be sent |

package/templates/api/development.env.tpl

@@ -50,6 +50,12 @@ XEPLR_AUTH_MIGRATIONS=./node_modules/@xeplr/factory/migrations-auth,./migrations
 AUTH_SUPER_ADMIN_EMAIL=__ADMIN_EMAIL__
 AUTH_SUPER_ADMIN_PASSWORD=__ADMIN_PASSWORD__
 
+# ── Which company a role belongs to ──
+# none: this app has one set of roles for everyone. A multi-tenant app names
+# the header that carries the company id instead (e.g. x-company-id), so a
+# role made inside a company belongs to that company.
+AUTH_TENANT_HEADER=none
+
 # ── Links that go out in emails ──
 # FULLY QUALIFIED, and they point at UI pages rather than at the API. The
 # sign-in service builds these links and appends the token as ?token=... — an

package/templates/api/production.env.example

@@ -30,6 +30,8 @@ AUTH_URL=http://127.0.0.1:__AUTH_PORT__
 XEPLR_AUTH_MIGRATIONS=./node_modules/@xeplr/factory/migrations-auth,./migrations-auth,./node_modules/@xeplr/workflow/migrations-auth
 AUTH_SUPER_ADMIN_EMAIL=
 AUTH_SUPER_ADMIN_PASSWORD=
+# none for one set of roles; a multi-tenant app names its company header, e.g. x-company-id
+AUTH_TENANT_HEADER=none
 
 # ── Public addresses (what people's browsers open) ──
 AUTH_ACTIVATION_URL=https://app.example.com/auth/activate

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

@@ -2,6 +2,9 @@
 //
 //   Forms  every UI in the app: make one, design it, publish it, open it, add it
 //          to the side rail
+//   Masters the lists the rest of the app points at — departments, statuses,
+//          countries. Ordinary forms with a flag, gathered in one place because
+//          that is what they are: reference data, not daily work
 //   Menu   the side rail's items: rename, reorder, hide
 //   Flows  forms one after another — what is filled in decides the next; run by
 //          Xeplr Workflow, and says how to connect it until it is
@@ -10,11 +13,13 @@
 // people use.
 import { useSearchParams } from 'react-router-dom'
 import Forms from './Forms.jsx'
+import Masters from './Masters.jsx'
 import MenuSettings from './MenuSettings.jsx'
 import Flows from './Flows.jsx'
 
 const TABS = [
   { id: 'forms', label: 'Forms', Page: Forms },
+  { id: 'masters', label: 'Masters', Page: Masters },
   { id: 'flows', label: 'Flows', Page: Flows },
   { id: 'menu', label: 'Menu', Page: MenuSettings }
 ]

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

@@ -9,27 +9,56 @@
 // Claude can make forms too — see "Create a new UI" in CLAUDE.md.
 import { useCallback, useEffect, useState } from 'react'
 import { useNavigate } from 'react-router-dom'
-import { listMenuItems, addMenuItem, removeMenuItem, useAccess } from '@xeplr/ui-account'
+import { listMenuItems, addMenuItem, removeMenuItem, useAccess, getUsers } from '@xeplr/ui-account'
+import { deleteForm } from '@xeplr/ui-factory'
+// THE APP'S OWN DIALOGS. window.confirm cannot say which button is the
+// dangerous one and looks like a different piece of software appearing over
+// this one; a red box pinned to the page stays there until something else
+// replaces it, long after it has been read.
+import { raiseConfirm, raiseSnackbar } from '@xeplr/ui-utils'
 import { factory } from '../api/factory.js'
 import { FORM_MENU_PREFIX } from '../menu.js'
 
-/** listScreens rows → one entry per form: { key, name, source, list, edit }. */
+/**
+ * listScreens rows → one entry per form.
+ *
+ * `description` and `createdBy` travel with it because of the thing that
+ * happens once more than a handful of people can make forms: three of them
+ * are called "Inspection", and the fields say what each HOLDS, never what it
+ * was for or whose it is. Deciding which to keep is otherwise guesswork.
+ */
 function groupForms(rows) {
   const byKey = new Map()
   rows.forEach((row) => {
     const m = /^(.*)_(list|edit)$/.exec(row.screenKey)
     const key = m ? m[1] : row.screenKey
-    const entry = byKey.get(key) || { key, name: null, source: null, list: null, edit: null }
+    const entry = byKey.get(key) || {
+      key, name: null, source: null, list: null, edit: null,
+      description: null, createdBy: null, createdDate: null
+    }
     if (m) entry[m[2]] = row
     else entry.edit = row
     if (m && m[2] === 'list') entry.name = row.name
     entry.name = entry.name || row.name
     entry.source = entry.source || row.source
+    entry.description = entry.description || row.description
+    // The form's own half is the one that speaks for it; a list screen is
+    // only consulted when there is no other answer.
+    if (m && m[2] === 'edit') { entry.createdBy = row.createdBy; entry.createdDate = row.createdDate }
+    entry.createdBy = entry.createdBy || row.createdBy
+    entry.createdDate = entry.createdDate || row.createdDate
     byKey.set(key, entry)
   })
   return [...byKey.values()].sort((a, b) => String(a.name).localeCompare(String(b.name)))
 }
 
+/** "3 Feb 2026" — enough to tell two forms apart, no more. */
+function madeOn(when) {
+  if (!when) return null
+  const d = new Date(when)
+  return isNaN(d) ? null : d.toLocaleDateString(undefined, { day: 'numeric', month: 'short', year: 'numeric' })
+}
+
 function state(screen) {
   if (!screen) return { label: '—', unpublished: false }
   if (screen.version === null) return { label: 'Not published yet', unpublished: true }
@@ -50,16 +79,19 @@ export default function Forms() {
   const navigate = useNavigate()
   const { refreshAccess } = useAccess()
   const [forms, setForms] = useState(null)
+  // WHO MADE EACH ONE. The screens table keeps the maker's id; the names live
+  // in the sign-in service, so they are fetched once here and matched up.
+  // Failing to get them is not an error worth showing — the date alone still
+  // tells two forms of the same name apart.
+  const [people, setPeople] = useState({})
   const [inMenu, setInMenu] = useState(new Set())
-  const [error, setError] = useState(null)
-  const [notice, setNotice] = useState(null)
   const [label, setLabel] = useState('')
   const [key, setKey] = useState('')
   const [keyEdited, setKeyEdited] = useState(false)
   const [busy, setBusy] = useState(null)
 
   const load = useCallback(() => {
-    factory.listScreens().then((rows) => { setForms(groupForms(rows)); setError(null) }, (e) => setError(e.message))
+    factory.listScreens().then((rows) => setForms(groupForms(rows)), (e) => raiseSnackbar(e.message, { design: 'error' }))
     listMenuItems().then(
       (items) => setInMenu(new Set(items.filter((m) => m.name.startsWith(FORM_MENU_PREFIX) && !m.isHidden).map((m) => m.name.slice(FORM_MENU_PREFIX.length)))),
       () => {}
@@ -67,6 +99,21 @@ export default function Forms() {
   }, [])
   useEffect(load, [load])
 
+  // Once. A name per row would be one request per form, and these change far
+  // more slowly than the page is opened.
+  useEffect(() => {
+    let cancelled = false
+    getUsers()
+      .then((rows) => {
+        if (cancelled) return
+        const by = {}
+        ;(rows || []).forEach((u) => { by[u.id] = u.name || u.email || u.id })
+        setPeople(by)
+      })
+      .catch(() => {})
+    return () => { cancelled = true }
+  }, [])
+
   const onLabel = (value) => {
     setLabel(value)
     if (!keyEdited) setKey(suggestKey(value))
@@ -79,28 +126,63 @@ export default function Forms() {
       const made = await factory.createEntity({ key: key.trim(), label: label.trim() })
       navigate('/configure/forms/' + made.key + '/design/form')
     } catch (err) {
-      setError(err.message)
+      raiseSnackbar(err.message, { design: 'error' })
       setBusy(null)
     }
   }
 
   // The form first — publishing it creates or changes the table — then the list.
+  /**
+   * Delete a form. Asked first, in the words of what will actually happen
+   * rather than "are you sure": the design goes, and the records do not
+   * unless there are none.
+   */
+  const remove = async (form) => {
+    const ok = await raiseConfirm(
+      'Its design goes. Its table and any records in it are kept unless the table is empty.',
+      {
+        title: 'Delete "' + (form.name || form.key) + '"?',
+        confirmLabel: 'Delete',
+        // Red, because it cannot be undone from here.
+        danger: true
+      }
+    )
+    if (!ok) return
+    setBusy(form.key)
+    try {
+      const out = await deleteForm(factory, form)
+      // Said plainly: somebody deleting a form expects all of it to go, and a
+      // table left behind is worth knowing about rather than discovering.
+      if (out && out.records > 0) {
+        raiseSnackbar('"' + (form.name || form.key) + '" is gone. Its table "' + out.table + '" was kept — it still holds ' +
+          out.records + ' record' + (out.records === 1 ? '' : 's') + '.', { design: 'info' })
+      } else if (out && out.tableDropped) {
+        raiseSnackbar('"' + (form.name || form.key) + '" and its empty table are gone.', { design: 'success' })
+      } else {
+        raiseSnackbar('"' + (form.name || form.key) + '" is gone.', { design: 'success' })
+      }
+      load()
+    } catch (err) {
+      raiseSnackbar(err.message, { design: 'error' })
+    } finally {
+      setBusy(null)
+    }
+  }
+
   const publish = async (form) => {
     setBusy(form.key)
-    setNotice(null)
     try {
       for (const screen of [form.edit, form.list]) {
         if (!screen || (screen.version !== null && !screen.hasDraft)) continue
         const row = await factory.loadDraft(screen.screenKey)
         await factory.publish(row.document)
       }
-      setNotice('Published "' + form.name + '"')
-      setError(null)
+      raiseSnackbar('Published "' + form.name + '"', { design: 'success' })
       load()
     } catch (err) {
-      setError(err.confirm
+      raiseSnackbar(err.confirm
         ? 'Publishing "' + form.name + '" would remove columns and their data — open Design form and publish there to see what, and confirm.'
-        : err.message)
+        : err.message, { design: 'error' })
     } finally {
       setBusy(null)
     }
@@ -112,10 +194,10 @@ export default function Forms() {
       if (inMenu.has(form.key)) await removeMenuItem(FORM_MENU_PREFIX + form.key)
       else await addMenuItem({ name: FORM_MENU_PREFIX + form.key, label: form.name })
       await refreshAccess()
-      setNotice(inMenu.has(form.key) ? 'Removed "' + form.name + '" from the menu' : 'Added "' + form.name + '" to the menu — rename or move it in the Menu tab')
+      raiseSnackbar(inMenu.has(form.key) ? 'Removed "' + form.name + '" from the menu' : 'Added "' + form.name + '" to the menu — rename or move it in the Menu tab', { design: 'success' })
       load()
     } catch (err) {
-      setError(err.message)
+      raiseSnackbar(err.message, { design: 'error' })
     } finally {
       setBusy(null)
     }
@@ -141,8 +223,6 @@ export default function Forms() {
         </button>
       </form>
 
-      {error && <div className="app-error">{error}</div>}
-      {notice && <div className="app-notice">{notice}</div>}
 
       {forms && forms.length === 0 && <p className="app-sub">No forms yet.</p>}
       {forms && forms.length > 0 && (
@@ -157,7 +237,19 @@ export default function Forms() {
               const canOpen = form.list && form.list.version !== null
               return (
                 <tr key={form.key}>
-                  <td><strong>{form.name || form.key}</strong><div className="app-sub">{form.key}</div></td>
+                  <td>
+                    <strong>{form.name || form.key}</strong>
+                    <div className="app-sub">{form.key}</div>
+                    {/* WHAT IT IS FOR, and whose it is — the two things that
+                        tell three forms of the same name apart. The date
+                        stands alone when the names cannot be fetched. */}
+                    {form.description && <div className="app-sub">{form.description}</div>}
+                    {(form.createdBy || form.createdDate) && (
+                      <div className="app-sub">
+                        {[people[form.createdBy], madeOn(form.createdDate)].filter(Boolean).join(' · ')}
+                      </div>
+                    )}
+                  </td>
                   <td><code>{form.source || '—'}</code></td>
                   <td className={edit.unpublished ? 'app-forms-pending' : undefined}>{edit.label}</td>
                   <td className={list.unpublished ? 'app-forms-pending' : undefined}>{list.label}</td>
@@ -173,6 +265,17 @@ export default function Forms() {
                         {busy === form.key ? 'Publishing…' : 'Publish'}
                       </button>
                     )}
+                    {/* The design always goes; the TABLE only when it is empty
+                        and nothing else describes it. Records are never lost
+                        to a click — @xeplr/factory refuses to drop a table
+                        with rows in it and says how many kept it. */}
+                    <button
+                      className="app-btn app-btn-quiet app-btn-danger"
+                      disabled={busy === form.key}
+                      onClick={() => remove(form)}
+                    >
+                      Delete
+                    </button>
                   </td>
                 </tr>
               )

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

@@ -0,0 +1,114 @@
+// CONFIGURE UI → MASTERS — the lists the rest of the app points at.
+//
+// Departments, statuses, countries, categories: small tables that other forms
+// choose from. They are ordinary forms with a flag (Design → This is a
+// master), so they have a table, a list, an edit screen and permissions like
+// anything else — a master is a fact about a form, not a kind of form.
+//
+// They are gathered HERE rather than scattered through the side rail because
+// that is what they are: reference data somebody maintains occasionally, not
+// pages people work in daily. The rail stays for the work.
+//
+// Which forms are masters is @xeplr/ui-factory's answer (`useScreenSource`),
+// not this app's — grouping two screens into a form and reading the flag is
+// the same code in every app, and a copy here could never be fixed centrally.
+import { useState } from 'react'
+import { Link } from 'react-router-dom'
+import { useScreenSource, createMaster, possibleParents, FactoryBuilder } from '@xeplr/ui-factory'
+import { factory } from '../api/factory.js'
+
+export default function Masters() {
+  const { masters, loading, reload } = useScreenSource(factory, { Builder: FactoryBuilder })
+  const [name, setName] = useState('')
+  const [parent, setParent] = useState('')
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState(null)
+
+  // MADE, NOT DESIGNED. A master is a name, an order and what it belongs to —
+  // the same three things every time — so it is created outright and the
+  // builder is for the day one needs a fourth field.
+  const create = async (e) => {
+    e.preventDefault()
+    if (!name.trim() || busy) return
+    setBusy(true)
+    try {
+      const owner = masters.find((m) => m.key === parent)
+      await createMaster(factory, {
+        name: name.trim(),
+        parent: owner ? { table: owner.source, label: owner.name } : null
+      })
+      setName('')
+      setParent('')
+      setError(null)
+      reload()
+    } catch (err) {
+      setError(err.message)
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  if (loading) return <p className="app-sub">Loading…</p>
+
+  return (
+    <div className="app-forms">
+      <p className="app-page-lead">
+        The lists the rest of the app chooses from. A master is a name, an order of your own,
+        and — when it belongs to one — the master above it.
+      </p>
+
+      {error && <div className="app-error">{error}</div>}
+
+      <form className="app-forms-new" onSubmit={create}>
+        <label className="app-forms-field">
+          <span>New master</span>
+          <input value={name} onChange={(e) => setName(e.target.value)} placeholder="Departments" />
+        </label>
+        {/* Only worth asking once there is something to belong to. */}
+        {masters.length > 0 && (
+          <label className="app-forms-field">
+            <span>Belongs to</span>
+            <select value={parent} onChange={(e) => setParent(e.target.value)}>
+              <option value="">— nothing —</option>
+              {possibleParents(masters).map((m) => (
+                <option key={m.key} value={m.key}>{m.name}</option>
+              ))}
+            </select>
+          </label>
+        )}
+        <button type="submit" className="app-btn" disabled={!name.trim() || busy}>
+          {busy ? 'Making it…' : 'Make the master'}
+        </button>
+      </form>
+
+      {masters.length === 0 && (
+        <p className="app-sub">
+          No masters yet. Departments, statuses, countries — anything other forms point at.
+        </p>
+      )}
+
+      {masters.length > 0 && (
+        <table className="app-table">
+          <thead><tr><th>Master</th><th>Shown as</th><th>Table</th><th /></tr></thead>
+          <tbody>
+            {masters.map((m) => (
+              <tr key={m.key}>
+                <td><strong>{m.name}</strong></td>
+                {/* What a picker shows for one of its records — said once on
+                    the master, not again on every dropdown pointing at it. */}
+                <td className="app-sub">{m.labelField || '—'}</td>
+                <td className="app-sub">{m.source || '—'}</td>
+                <td className="app-row-actions">
+                  {/* Its records: the list screen is what looking at a master
+                      means. Its design is where the flag was set. */}
+                  <Link to={`/forms/${m.key}`}>Open</Link>
+                  <Link to={`/configure/forms/${m.key}/design/form`}>Design</Link>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+    </div>
+  )
+}