@xeplr/cli 0.1.1 → 0.1.3

package/templates/api/development.env.tpl

@@ -24,14 +24,20 @@ DB_API=__NAME___api
 AUTH_DB_NAME=__NAME___auth
 
 # ── Sign-in service ──
+#
+# Sessions are kept in REDIS, which must be running. Defaults to
+# localhost:6379; set REDIS_HOST / REDIS_PORT to point elsewhere. Without it
+# the service refuses to start and says so — rather than letting every login
+# succeed and every request afterwards fail as "Invalid or expired token".
 AUTH_PORT=__AUTH_PORT__
 AUTH_JWT_SECRET=__JWT_SECRET__
 
 # Where the sign-in service is. Your API asks it to check every token.
 AUTH_URL=http://localhost:__AUTH_PORT__
 
-# Your own sign-in setup files — menu entries and anything else this app adds.
-XEPLR_AUTH_MIGRATIONS=./migrations-auth
+# Sign-in setup files: the screens' permissions (@xeplr/factory's), then this
+# app's own — menu entries and anything else it adds. Comma-separated, in order.
+XEPLR_AUTH_MIGRATIONS=./node_modules/@xeplr/factory/migrations-auth,./migrations-auth
 
 # ── The first account you sign in with ──
 # Created for you when you set up the database. Change the password here and

package/templates/api/migrations/README.md

@@ -0,0 +1,9 @@
+# migrations
+
+Hand-written `.sql` files, applied once each, in name order, every time the API
+starts (`0001_something.sql`, `0002_…`).
+
+**Tables for screens are not written here.** A screen's table (`tasks`) is
+created and changed by **Publish** in the Designer page — see `screens/`.
+
+Put here only tables no screen owns: lookup data, a table your own code writes.

package/templates/api/migrations-auth/0003_designer_menu.sql

@@ -0,0 +1,19 @@
+-- "Designer" — the drawer item for designing screens (ui/src/pages/Designer.jsx).
+--
+-- NOT public: Publish changes database tables, so only the roles that hold
+-- @xeplr/factory's design permission see the item. The API refuses everyone
+-- else anyway ("Access denied: Publish factory screen"); this keeps the menu
+-- honest about 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'), 'Designer', '', false, true, '*', now(), now()
+WHERE NOT EXISTS (SELECT 1 FROM "menus" WHERE name = 'Designer');
+
+INSERT INTO "menuRolesMapping" (id, "roleId", "menuId", "isActive", "mtId1", "recordCreatedDate", "recordModifiedDate")
+SELECT encode(gen_random_bytes(12), 'hex'), r.id, m.id, true, '*', now(), now()
+FROM "roles" r CROSS JOIN "menus" m
+WHERE r.name IN ('Super Admin', 'CompanyAdmin')
+  AND m.name = 'Designer'
+  AND NOT EXISTS (SELECT 1 FROM "menuRolesMapping" x WHERE x."roleId" = r.id AND x."menuId" = m.id);

package/templates/api/models/index.js

@@ -1,7 +1,8 @@
-// Every model this app owns. Add yours here — routes/index.js reads them from
-// this one place rather than reaching into individual files.
-var Task = require('./Task');
+// Models for tables you write by hand (see migrations/README.md) — each one a
+// class extending @xeplr/db's BaseModel, handed to genericRoute in
+// routes/index.js.
+//
+// Tables made with the Designer (screens/) need no model: @xeplr/factory saves
+// and reads them from the screen itself.
 
-module.exports = {
-  Task: Task
-};
+module.exports = {};

package/templates/api/package.json

@@ -14,12 +14,14 @@
     "migrate:auth": "dotenv -e development.env -- xeplr-auth-migrate up --connection-env AUTH_DB_CONNECTION_INFO_ENCRYPTED",
     "migrate:up": "dotenv -e development.env -- xeplr-migrate up --dir ./migrations --connectionName api --connection-env __PREFIX___CONNECTION",
     "start-auth": "dotenv -e ./development.env -- xeplr-auth-server",
-    "start-api": "NODE_ENV=development node ./bin/www"
+    "start-api": "node ./bin/www"
   },
   "dependencies": {
-    "@xeplr/auth": "^1.1.0",
+    "@xeplr/auth": "^1.1.2",
     "@xeplr/base-apis": "^2.0.0",
-    "@xeplr/db": "^1.0.5",
+    "@xeplr/db": "^1.0.6",
+    "@xeplr/factory": "^1.0.3",
+    "@xeplr/utils": "^1.0.8",
     "dotenv": "^17.4.2",
     "express": "^5.2.0"
   },

package/templates/api/routes/index.js

@@ -1,6 +1,4 @@
 var express = require('express');
-var { genericRoute } = require('@xeplr/base-apis');
-var { Task } = require('../models');
 
 var router = express.Router();
 
@@ -21,26 +19,19 @@ router.get('/whoami', function(req, res) {
   res.json({ user: req.user, roles: (req.access || {}).roles || [] });
 });
 
-// ── tasks ────────────────────────────────────────────────────────────────
+// ── your data ────────────────────────────────────────────────────────────
 //
 // MOUNTED UNDER /api, and that prefix matters. The browser asks the UI's dev
 // server for BOTH its own pages and its data, and the dev server decides by
 // path which to forward. Serve data at /tasks and the UI's own /tasks page is
 // shadowed by it — opening that page shows raw JSON instead of the app.
 //
-// Keeping every data address under /api means a page path and a data path can
-// never collide, whatever either is called later.
+// Screens made in the Designer (tasks) need nothing here — @xeplr/factory
+// serves them at /api/factory/..., mounted in app.js.
 //
-// FOUR ADDRESSES FROM ONE LINE. Hand genericRoute a model and it builds:
+// A table you write by hand gets its four addresses from one line:
 //
-//   GET  /api/tasks         list, paginated  (?page=1&limit=50)
-//   GET  /api/tasks/:id     one task
-//   POST /api/tasks/save    create and update, in one transaction
-//   POST /api/tasks/delete  soft delete by ids
-//
-// No handler is written for any of them. The model's own jsonSchema is what
-// validates the incoming values, so the rules live in one place rather than
-// being restated here.
-router.use('/api/tasks', genericRoute({ key: 'task', model: Task }));
+//   var { genericRoute } = require('@xeplr/base-apis');
+//   router.use('/api/things', genericRoute({ key: 'thing', model: require('../models').Thing }));
 
 module.exports = router;

package/templates/api/screens/index.js

@@ -0,0 +1,32 @@
+// THE SCREENS THIS APP SHIPS WITH — designed with @xeplr/ui-factory.
+//
+// Each entity is two screens: a list, and the add / edit form the list opens
+// in a popup. Their records live in a REAL table named for the entity
+// ("tasks"), one column per field.
+//
+// On startup (bin/www) every screen here that has never been published is
+// published — which creates its table. After that the DATABASE holds the
+// design: change it in the app's Designer page, where Publish changes the
+// table to match. Editing a .screen.json later changes nothing for an
+// already-published screen.
+//
+// ADD AN ENTITY:
+//
+//   npx xeplr-factory screens screens/project/project.entity.json -o screens/project
+//
+// then list its two screens and its hooks below, and add a page and a menu
+// entry for it (see the UI's src/pages/Tasks.jsx and migrations-auth/).
+
+module.exports = {
+  // Publish order is worked out for you: a table before the dropdowns that
+  // point at it, lists last.
+  documents: [
+    require('./task/task-edit.screen.json'),
+    require('./task/task-list.screen.json')
+  ],
+
+  // Your own code around save / get / delete, per screen — see task/task.hooks.js.
+  hooks: {
+    task_edit: require('./task/task.hooks')
+  }
+};

package/templates/api/screens/task/task-edit.screen.json

@@ -0,0 +1,103 @@
+{
+  "kind": "xeplr-screen",
+  "version": 1,
+  "id": "task_edit",
+  "name": "Add / edit task",
+  "units": "fraction",
+  "aspect": 1,
+  "width": 800,
+  "nodes": [
+    {
+      "id": "label",
+      "type": "label",
+      "x": 0.04,
+      "y": 0.04,
+      "w": 0.92,
+      "h": 0.07,
+      "z": 1,
+      "props": {
+        "text": "Add / edit task",
+        "variant": "heading"
+      }
+    },
+    {
+      "id": "title",
+      "type": "text",
+      "x": 0.04,
+      "y": 0.15,
+      "w": 0.4475,
+      "h": 0.08,
+      "z": 2,
+      "props": {
+        "label": "Title",
+        "required": true,
+        "validation": {
+          "maxLength": 200
+        },
+        "name": "title"
+      }
+    },
+    {
+      "id": "status",
+      "type": "dropdown",
+      "x": 0.5125,
+      "y": 0.15,
+      "w": 0.4475,
+      "h": 0.08,
+      "z": 3,
+      "props": {
+        "label": "Status",
+        "placeholder": "Select…",
+        "data": {
+          "source": "static",
+          "options": [
+            {
+              "id": "to_do",
+              "name": "To do"
+            },
+            {
+              "id": "in_progress",
+              "name": "In progress"
+            },
+            {
+              "id": "done",
+              "name": "Done"
+            }
+          ]
+        },
+        "required": true,
+        "name": "status"
+      }
+    },
+    {
+      "id": "dueDate",
+      "type": "date",
+      "x": 0.04,
+      "y": 0.27,
+      "w": 0.4475,
+      "h": 0.08,
+      "z": 4,
+      "props": {
+        "label": "Due date",
+        "name": "dueDate"
+      }
+    },
+    {
+      "id": "description",
+      "type": "textarea",
+      "x": 0.04,
+      "y": 0.39,
+      "w": 0.92,
+      "h": 0.18,
+      "z": 5,
+      "props": {
+        "label": "Description",
+        "validation": {
+          "maxLength": 1000
+        },
+        "name": "description"
+      }
+    }
+  ],
+  "source": "tasks"
+}

package/templates/api/screens/task/task-list.screen.json

@@ -0,0 +1,45 @@
+{
+  "kind": "xeplr-screen",
+  "version": 1,
+  "id": "task_list",
+  "name": "Tasks",
+  "units": "fraction",
+  "aspect": 1,
+  "width": 800,
+  "nodes": [
+    {
+      "id": "list",
+      "type": "list",
+      "x": 0.04,
+      "y": 0.04,
+      "w": 0.92,
+      "h": 0.8,
+      "z": 1,
+      "props": {
+        "title": "Tasks",
+        "pageSize": 10,
+        "actions": [
+          "new",
+          "edit",
+          "delete"
+        ],
+        "editScreen": "task_edit",
+        "columns": [
+          {
+            "field": "title",
+            "label": "Title"
+          },
+          {
+            "field": "status",
+            "label": "Status"
+          },
+          {
+            "field": "dueDate",
+            "label": "Due date"
+          }
+        ]
+      }
+    }
+  ],
+  "source": "tasks"
+}

package/templates/api/screens/task/task.entity.json

@@ -0,0 +1,10 @@
+{
+  "entity": "task",
+  "fields": [
+    { "label": "Title", "required": true, "validation": { "maxLength": 200 } },
+    { "label": "Status", "type": "dropdown", "options": ["To do", "In progress", "Done"], "required": true },
+    { "label": "Due date", "type": "date" },
+    { "label": "Description", "type": "textarea", "validation": { "maxLength": 1000 } }
+  ],
+  "listColumns": ["title", "status", "dueDate"]
+}

package/templates/api/screens/task/task.hooks.js

@@ -0,0 +1,37 @@
+// Server hooks for task records — screen "task_edit" (and "task_list", which edits in it).
+//
+// Register with @xeplr/factory:
+//   factory.init({ knex, hooks: { task_edit: require('./task.hooks') } })
+//
+// Each operation has four hooks. Delete the ones you do not need.
+//   before(ctx)       first — save: return new values to replace them (they are then checked
+//                     against the screen's rules); get: narrow ctx.query; any: ctx.reject(message, { field })
+//   after(ctx)        once it succeeded — ctx.id, ctx.result; return a value to replace the result.
+//                     If it throws, the operation still happened (and error is told).
+//   error(ctx, err)   when the operation failed
+//   override(ctx)     does the WHOLE operation instead — no rules, no before / after / error,
+//                     no generic query. What it returns is the response.
+//
+// ctx: op, screenKey, screen, table, id, isNew (save), many (get), input (what the UI sent, read-only),
+//      values (save), previous (save / delete: the row before), result, user, tenant, knex, query (get), reject
+
+module.exports = {
+  save: {
+    // before: async function(ctx) { return ctx.values },
+    // after: async function(ctx) {},
+    // error: async function(ctx, err) {},
+    // override: async function(ctx) { return savedRecord },
+  },
+  get: {
+    // before: async function(ctx) { /* ctx.query.where(...) */ },
+    // after: async function(ctx) { return ctx.result },
+    // error: async function(ctx, err) {},
+    // override: async function(ctx) { return ctx.id ? record : records },
+  },
+  delete: {
+    // before: async function(ctx) {},
+    // after: async function(ctx) {},
+    // error: async function(ctx, err) {},
+    // override: async function(ctx) { return { id: ctx.id } },
+  }
+}

package/templates/ui/package.json

@@ -9,7 +9,11 @@
     "preview": "vite preview"
   },
   "dependencies": {
+    "@tanstack/react-table": "^8.21.3",
     "@xeplr/ui-account": "^1.0.6",
+    "@xeplr/ui-canvas": "^1.0.2",
+    "@xeplr/ui-factory": "^1.0.4",
+    "@xeplr/ui-table": "^1.0.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "react-router-dom": "^7.13.2"

package/templates/ui/src/App.jsx

@@ -3,6 +3,8 @@ import { Routes, Route, Outlet, Navigate, useNavigate } from 'react-router-dom'
 import { authRoutes, authPath, NavPage, ProtectedRoute } from '@xeplr/ui-account'
 import Home from './pages/Home.jsx'
 import Tasks from './pages/Tasks.jsx'
+import Designer from './pages/Designer.jsx'
+__MT_APP_UI_IMPORTS__
 
 // The rail is ICON-ONLY when collapsed, so a drawer item without one is
 // invisible until somebody widens the rail. Same 24x24 stroke language the
@@ -15,6 +17,15 @@ const TasksIcon = (
   </svg>
 )
 
+const DesignerIcon = (
+  <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
+       strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+    <rect x="3" y="3" width="18" height="18" rx="2" />
+    <path d="M3 9h18M9 21V9" />
+  </svg>
+)
+
+__MT_SWITCH_ICON__
 const HomeIcon = (
   <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
        strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
@@ -42,7 +53,10 @@ function Shell() {
   // item with no error anywhere.
   const drawerItems = useMemo(() => [
     { name: 'Home', icon: HomeIcon, clickHandler: () => navigate('/home') },
-    { name: 'Tasks', icon: TasksIcon, clickHandler: () => navigate('/tasks') }
+    { name: 'Tasks', icon: TasksIcon, clickHandler: () => navigate('/tasks') },
+    // Shown only to roles given the "Designer" menu (migrations-auth/0003).
+    { name: 'Designer', icon: DesignerIcon, clickHandler: () => navigate('/designer') },
+__MT_DRAWER_ITEM__
   ], [navigate])
 
   return (
@@ -72,10 +86,12 @@ export default function App() {
           our own chrome. */}
       {authRoutes({}, { layout: <Shell /> })}
 
-      <Route element={<ProtectedRoute><Shell /></ProtectedRoute>}>
+__MT_SELECT_ROUTE__
+      <Route element={<ProtectedRoute>__MT_GATE_OPEN__<Shell />__MT_GATE_CLOSE__</ProtectedRoute>}>
         <Route path="/" element={<Navigate to="/home" replace />} />
         <Route path="/home" element={<Home />} />
         <Route path="/tasks" element={<Tasks />} />
+        <Route path="/designer" element={<Designer />} />
       </Route>
 
       <Route path="*" element={<Navigate to="/auth/login" replace />} />

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

@@ -0,0 +1,10 @@
+// MODEL LAYER — every call the screens and the Designer make, to the API's
+// @xeplr/factory routes (mounted at /api in api/app.js).
+//
+// authFetch attaches the signed-in user's token (and the active company, when
+// the app has tenancy) and returns the PARSED body. createFactoryApi accepts
+// it as it is.
+import { authFetch } from '@xeplr/ui-account'
+import { createFactoryApi } from '@xeplr/ui-factory'
+
+export const factory = createFactoryApi({ fetch: authFetch, base: '/api' })

package/templates/ui/src/index.css

@@ -273,3 +273,28 @@ body { margin: 0; }
   .app-page-split { display: block; }
   .app-help { position: static; margin-top: 28px; width: auto; }
 }
+
+/* ── Designer ─────────────────────────────────────────────────────────── */
+/* The builder fills the space it is given, so it needs a height: the page
+   below the top bar, less .main's padding. */
+.app-designer {
+  display: flex;
+  flex-direction: column;
+  height: calc(100vh - 110px);
+  min-height: 520px;
+  gap: 10px;
+}
+
+.app-designer-bar { display: flex; align-items: center; gap: 6px; flex-wrap: wrap; }
+
+.app-designer-title { font-weight: 600; margin-right: 10px; }
+
+.app-designer-bar .is-active { background: var(--xeplr-bg-secondary); }
+
+.app-designer-canvas {
+  flex: 1;
+  min-height: 0;
+  border: 1px solid var(--xeplr-border-primary);
+  border-radius: 8px;
+  overflow: hidden;
+}

package/templates/ui/src/main.jsx

@@ -3,12 +3,14 @@ import ReactDOM from 'react-dom/client'
 import { BrowserRouter } from 'react-router-dom'
 import { configure, AccessProvider, ThemeProvider } from '@xeplr/ui-account'
 import App from './App.jsx'
+__MT_UI_IMPORTS__
 import './index.css'
 import '@xeplr/ui-account/src/designs/theme.css'
 
 // Auth requests are same-origin in dev — vite proxies /auth/api to AUTH_URL
 // (see vite.config.js, which reads it from .env).
 configure('')
+__MT_UI_REGISTER__
 
 ReactDOM.createRoot(document.getElementById('root')).render(
   <React.StrictMode>

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

@@ -0,0 +1,74 @@
+// THE DESIGNER — change any screen: move and resize fields, add new ones,
+// change labels, rules, fonts and colours.
+//
+// Your edits are kept as a DRAFT automatically. Nobody else sees them until
+// you press Publish, which also changes the screen's database table to match:
+// a new field adds a column; removing one asks first, because its column and
+// every value in it would be deleted.
+import { useCallback, useEffect, useState } from 'react'
+import { FactoryBuilder } from '@xeplr/ui-factory'
+import { factory } from '../api/factory.js'
+
+export default function Designer() {
+  const [screens, setScreens] = useState([])
+  const [current, setCurrent] = useState(null)      // { key, document, lockedNames }
+  const [error, setError] = useState(null)
+
+  useEffect(() => {
+    factory.listScreens().then((rows) => {
+      setScreens(rows)
+      if (rows.length) open(rows[0].screenKey)
+    }, (e) => setError(e.message))
+  }, [])                                              // eslint-disable-line react-hooks/exhaustive-deps
+
+  const open = useCallback(async (key) => {
+    try {
+      // The draft if there is one, else the published version — with the field
+      // names that are already columns, which the Designer will not let you rename.
+      const row = await factory.loadDraft(key)
+      setCurrent({ key, document: row.document, lockedNames: row.lockedNames || [] })
+      setError(null)
+    } catch (e) {
+      setError(e.message)
+    }
+  }, [])
+
+  const publish = useCallback(async (doc, options) => {
+    const result = await factory.publish(doc, options)
+    // New columns are now locked names too.
+    const row = await factory.loadDraft(doc.id)
+    setCurrent((c) => (c && c.key === doc.id ? { ...c, lockedNames: row.lockedNames || [] } : c))
+    return result
+  }, [])
+
+  return (
+    <div className="app-designer">
+      <div className="app-designer-bar">
+        <span className="app-designer-title">Designer</span>
+        {screens.map((s) => (
+          <button
+            key={s.screenKey}
+            type="button"
+            className={'app-btn app-btn-quiet' + (current && current.key === s.screenKey ? ' is-active' : '')}
+            onClick={() => open(s.screenKey)}
+          >
+            {s.name || s.screenKey}
+          </button>
+        ))}
+      </div>
+      {error && <div className="app-error">{error}</div>}
+      {current && (
+        <div className="app-designer-canvas">
+          <FactoryBuilder
+            key={current.key}
+            {...factory.builderProps}
+            document={current.document}
+            lockedNames={current.lockedNames}
+            onPublish={publish}
+            screens={screens.map((s) => ({ id: s.screenKey, name: s.name || s.screenKey }))}
+          />
+        </div>
+      )}
+    </div>
+  )
+}

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

@@ -58,6 +58,10 @@ export default function Home() {
           <code>public/logo.svg</code> and <code>public/logo-wide.svg</code> — the
           sample logo, in the top bar and the side rail.
         </li>
+        <li>
+          <strong>Designer</strong>, in the side rail — change the sample task
+          screens, or see how they are made. Publish changes the table too.
+        </li>
         <li>
           <code>src/App.jsx</code> — add your own pages, and the side-rail items
           that open them.