@voxgig/build 4.4.0 → 4.12.0

package/tm/web/docs/reference/web-app.md.frag

@@ -0,0 +1,98 @@
+# Reference: the web app
+
+*Diátaxis: reference — the generated SPA's structure, messages, hook
+points, and theme contract.*
+
+## Files ($$fe$$/src/)
+
+| File | Role | Regenerated? |
+|---|---|---|
+| `main.js` | Entry: imports css, bus, components, views, customise | no |
+| `bus.js` | The browser Seneca bus (transport to the backend gateway) | no |
+| `model.js` | Runtime model: fetches `/model.json`; entities, refs graph, labels, project scoping, custom-view tags | no |
+| `api.js` | Client for `aim:ent` CRUD + `aim:auth` | no |
+| `hooks.js` | Customisation hook registry | no |
+| `theme.js` | Theme mode controller (persisted; applies `data-theme-mode`) | no |
+| `style.css` | App styles (consume `--vg-*` variables) | no |
+| `theme.css` | CSS variables per theme mode | **yes — from the model** |
+| `views.js` | Index importing custom entity views | **yes — from the model** |
+| `customise.js` / `custom.css` | Project customisations | no (yours) |
+| `cmp/app.js` | Router: signed-out → public, signed-in → shell | no |
+| `cmp/public.js` | Public site + login mount | no |
+| `cmp/auth.js` | Login / forgot-password form | no |
+| `cmp/shell.js` | App shell: topbar, project selector, user menu, entity nav | no |
+| `cmp/admin.js` | Generic entity admin (list/detail/form, relationship drill) | no |
+| `cmp/settings.js` | Profile + change password | no |
+| `cmp/view/*.js` | Custom entity views (one per `ux:{view:'custom'}` entity) | no (starters) |
+
+## Backend messages used
+
+**The browser may only send `aim:web` messages.** The gateway allow-list
+names that one namespace, and every message the SPA sends is declared in
+the model as an `aim:web` PROXY that forwards to the real service message
+(`web_*` action files). Service namespaces (`aim:auth`, `aim:ent`,
+`aim:api`, ...) are internal: posting one from a browser is rejected with
+`not-allowed`. API-key clients have the same shape - the REST router
+posts `aim:api`, which is likewise not browser-reachable.
+
+| Browser message | Proxies to | Purpose |
+|---|---|---|
+| `aim:web,on:ent,cmd:list,ent:<canon>` (+`q`) | `aim:ent,cmd:list` | List (membership/project-scoped) |
+| `aim:web,on:ent,cmd:load,ent:<canon>` (+`id`) | `aim:ent,cmd:load` | Load one |
+| `aim:web,on:ent,cmd:save,ent:<canon>` (+`item`) | `aim:ent,cmd:save` | Create/update |
+| `aim:web,on:ent,cmd:remove,ent:<canon>` (+`id`) | `aim:ent,cmd:remove` | Delete |
+| `aim:web,on:auth,load:auth` | `aim:auth,load:auth` | Current principal |
+| `aim:web,on:auth,signin:user` / `signout:user` | `aim:auth,*` | Session (sets/clears the cookie) |
+| `aim:web,on:auth,change:pass` / `update:user` | `aim:auth,*` | Settings & security |
+| `aim:web,on:auth,remind:pass` | `aim:auth,remind:pass` | Password reminder (server stub) |
+| `aim:web,on:auth,create:apikey` / `list:apikey` / `revoke:apikey` | `aim:auth,*` | API keys |
+
+To expose a new operation to the browser, declare an `aim:web` proxy for
+it in the model and implement the `web_*` action - never widen the
+allow-list.
+
+## Hook points
+
+Register in `customise.js`; kinds: `html` (inject markup), `filter`
+(transform a value), `action` (side effect). All synchronous,
+failure-isolated.
+
+| Point | Kind | Context / value |
+|---|---|---|
+| `shell:topbar:right` | html | `{ user }` |
+| `shell:sidebar:top` | html | `{ user }` |
+| `shell:nav:items` | filter | entity list for the nav menu |
+| `admin:list:toolbar` | html | list toolbar region |
+| `admin:list:items` | filter | rows before render |
+| `admin:list:columns` | filter | column defs |
+| `admin:row:actions` | html | per-row action cell |
+| `admin:list:after` | action | `{ root, canon, items }` |
+| `admin:form:fields` | filter | form field defs |
+| `admin:form:extra` | html | extra form markup |
+| `admin:form:after` | action | after form render |
+| `admin:save:data` | filter | payload before save |
+| `admin:save:after` | action | after successful save |
+| `public:sections` | html | extra public-site sections |
+| `auth:form:footer` | html | login form footer |
+| `settings:sections` | html | extra settings sections |
+| `theme:modes` | filter | available theme mode list |
+
+## Theme contract
+
+- Model: `main.theme` = `{ mode, modes: { <name>: { <token>: <value> } } }`
+  (source: `backend/model/theme.aontu`).
+- Generated CSS: each token → `--vg-<token>` under
+  `:root[data-theme-mode="<name>"]`; default mode also on `:root`.
+- Runtime: `theme.js` sets `data-theme-mode` on `<html>`; choice persists
+  in localStorage `vg-theme-mode`; shell user menu toggles when more than
+  one mode exists.
+- Standard tokens: `primary`, `primary-dark`, `bg`, `surface`, `text`,
+  `muted`, `border`, `topbar-bg`, `topbar-fg`, `accent-bg`, `font`,
+  `radius`, `shadow-card`.
+
+## Custom entity view contract
+
+Tag `vg-view-<zone>-<name>`; properties `canon`, `projectId`, `detailId`,
+`onNavigate(canon, id)`; method `reload()`. Declared by
+`ux: { view: 'custom' }` on the model entity.
+

package/tm/web/web/AGENTS.md.frag

@@ -0,0 +1,52 @@
+# Agent guide: $$name$$ web app
+
+The model-driven SPA for $$name$$: vanilla web components on a browser
+Seneca message bus (no framework). Generated once by @voxgig/build EnvWeb;
+now developer-owned. Backend guide: ../AGENTS.md. Concept docs:
+../docs/ (see reference/web-app.md and explanation/web-architecture.md).
+
+## Commands (run in web/)
+
+```bash
+npm install
+npm run dev        # vite dev server (backend must be running: npm run web in backend/)
+npm run e2e        # playwright e2e (headless; starts its own backend)
+```
+
+E2e tests run headless Chromium with workers=1 against a shared backend —
+keep new specs independent of execution order but tolerant of shared seed
+data.
+
+## Architecture in one paragraph
+
+`main.js` imports theme/css, the bus, all components, `views.js`
+(generated index of custom views), and `customise.js` (project hooks).
+All data flows are Seneca messages on `bus.js`. **Only `aim:web`
+messages leave the browser** - that is the sole namespace the gateway
+accepts, and each one is a declared proxy to a real service message;
+`cmp:*` and events stay local. The transport pin is `aim:web` too, so a
+stray service-message post fails locally instead of travelling. The UI is
+model-driven at runtime — `model.js` fetches `/model.json` and derives
+the entity menu, forms, and relationship navigation; `api.js` wraps the
+`aim:web,on:ent,cmd:*` CRUD proxies and the `aim:web,on:auth,*` proxies.
+
+## Editing rules
+
+- Everything here is create-once EXCEPT `src/views.js` and
+  `src/theme.css` — those are REGENERATED from the model
+  (`npm run model-build` in backend/); never hand-edit them. Theme tokens
+  live in `backend/model/theme.aontu`; per-project overrides in
+  `src/custom.css`.
+- Prefer customisation over editing generated components: hooks in
+  `src/customise.js` (see `src/hooks.js` for points), CSS variables in
+  `src/custom.css`, or a custom entity view (`ux:{view:'custom'}` in the
+  model). Edit components directly only when those layers can't express
+  the change.
+- Components re-render by setting `innerHTML`; async renders must guard
+  against stale overwrites (see the render-token pattern in
+  `cmp/admin.js`: capture a token at method start, bail before writing if
+  superseded).
+- `bus.sub` has no auto-unsubscribe: long-lived subscriptions in
+  components must guard callbacks with `this.isConnected`.
+- Escape all user data with the local `esc()` helpers when building HTML.
+

package/tm/web/web/e2e/smoke.spec.js.frag

@@ -1,21 +1,23 @@
 import { test, expect } from '@playwright/test'
 
-// Generic smoke test: the SPA boots, a seeded user can sign in, and the
-// model-driven entity admin renders with at least one entity. Add
-// project-specific CRUD flows alongside this file.
+// Generic smoke test: the public site loads, a seeded user can sign in, and
+// the model-driven app shell renders with an entity menu. Add project-specific
+// flows (CRUD, relationship drill, settings) in your own spec files.
 
-test('sign in and load the entity admin', async ({ page }) => {
+test('public site, sign in, and the app shell', async ({ page }) => {
   await page.goto('/')
 
+  // Public content site with a login form.
   await expect(page.locator('vg-auth h2')).toHaveText('Sign in')
 
-  await page.fill('input[name=email]', '$$seedEmail$$')
-  await page.fill('input[name=password]', '$$seedPassword$$')
+  await page.fill('vg-auth input[name=email]', '$$seedEmail$$')
+  await page.fill('vg-auth input[name=password]', '$$seedPassword$$')
   await page.click('vg-auth button[type=submit]')
 
-  await expect(page.locator('.vg-auth-bar b')).toHaveText('$$seedEmail$$')
-  await expect(page.locator('vg-entity-admin nav a')).not.toHaveCount(0)
-
-  // The first entity's list loads (count line rendered).
-  await expect(page.locator('#vg-count')).toBeVisible()
+  // The enterprise shell: top bar with the signed-in user, and a
+  // model-driven entity menu with at least one entity.
+  await expect(page.locator('.vg-shell')).toBeVisible()
+  await expect(page.locator('.vg-user-btn')).toContainText('$$seedEmail$$')
+  await expect(page.locator('.vg-navlink')).not.toHaveCount(0)
 })
+

package/tm/web/web/index.html.frag

@@ -13,3 +13,4 @@
     <script type="module" src="/src/main.js"></script>
   </body>
 </html>
+

package/tm/web/web/package.json.frag

@@ -17,3 +17,4 @@
     "vite": "^7.3.4"
   }
 }
+

package/tm/web/web/playwright.config.js.frag

@@ -30,7 +30,7 @@ export default defineConfig({
     },
   ],
   webServer: {
-    command: `npm run build && cd ../backend && PORT=${PORT} node dist/env/web/web.js`,
+    command: `npm run build && cd ../backend && PORT=${PORT} REPL=false node dist/env/web/web.js`,
     url: `http://localhost:${PORT}/`,
     timeout: 60000,
     reuseExistingServer: false,
@@ -38,3 +38,4 @@ export default defineConfig({
     stderr: 'pipe',
   },
 })
+

package/tm/web/web/src/api.js.frag

@@ -0,0 +1,92 @@
+// Thin client over the Seneca bus.
+//
+// EVERY message the browser sends is an aim:web message: that is the only
+// namespace the backend gateway accepts (see backend/src/env/web/web.ts),
+// and each one is a declared proxy that forwards to the real service
+// message. Entity CRUD still lands on the ONE generic backend service, so
+// the same four calls serve every entity in the model.
+
+import { bus } from './bus.js'
+
+// ---- generic entity CRUD ------------------------------------------------
+
+async function list(ent, q) {
+  const r = await bus.post({ aim: 'web', on: 'ent', cmd: 'list', ent, q: q || {} })
+  return (r && r.ok && r.list) || []
+}
+
+async function load(ent, id) {
+  const r = await bus.post({ aim: 'web', on: 'ent', cmd: 'load', ent, id })
+  return r && r.ok ? r.item : null
+}
+
+async function save(ent, item) {
+  return bus.post({ aim: 'web', on: 'ent', cmd: 'save', ent, item })
+}
+
+async function remove(ent, id) {
+  return bus.post({ aim: 'web', on: 'ent', cmd: 'remove', ent, id })
+}
+
+// Users, for reference pickers (read-only, public fields).
+async function users() {
+  return list('sys/user')
+}
+
+// ---- auth / settings ----------------------------------------------------
+
+async function loadAuth() {
+  return bus.post('aim:web,on:auth,load:auth')
+}
+
+async function signin(email, password) {
+  return bus.post('aim:web,on:auth,signin:user', { email, password })
+}
+
+async function signout() {
+  return bus.post('aim:web,on:auth,signout:user')
+}
+
+async function changePass(password) {
+  return bus.post({ aim: 'web', on: 'auth', change: 'pass', password })
+}
+
+async function updateUser(data) {
+  return bus.post({ aim: 'web', on: 'auth', update: 'user', data })
+}
+
+async function remindPass(email) {
+  return bus.post({ aim: 'web', on: 'auth', remind: 'pass', email })
+}
+
+// ---- API access keys (REST API auth; Settings & security) ---------------
+
+async function createApikey(name) {
+  return bus.post({ aim: 'web', on: 'auth', create: 'apikey', name })
+}
+
+async function listApikeys() {
+  return bus.post({ aim: 'web', on: 'auth', list: 'apikey' })
+}
+
+async function revokeApikey(id) {
+  return bus.post({ aim: 'web', on: 'auth', revoke: 'apikey', id })
+}
+
+export {
+  list,
+  load,
+  save,
+  remove,
+  users,
+  loadAuth,
+  signin,
+  signout,
+  changePass,
+  updateUser,
+  remindPass,
+  createApikey,
+  listApikeys,
+  revokeApikey,
+}
+

package/tm/web/web/src/bus.js.frag

@@ -1,7 +1,7 @@
 // The browser-side Seneca service bus. All component state and all
 // backend communication flow through messages on this bus:
 //
-//   aim:*             -> the backend gateway (/seneca) via the
+//   aim:web,*         -> the backend gateway (/seneca) via the
 //                        seneca-browser fetch transport (cookie auth)
 //   cmp:*             -> local component plugins (state)
 //
@@ -23,22 +23,27 @@ const bus = Seneca({
   },
 })
   .test()
-  .client({ type: 'browser', pin: 'aim:*' })
+  .client({ type: 'browser', pin: 'aim:web' })
 
 
-// Transparent state cache (Redux-like): caches aim:* query results and
+// Transparent state cache (Redux-like): caches aim:web query results and
 // invalidates on writes, so repeated reads are served without a round-trip.
-// Registered AFTER .client() so the aim:* pin actions exist to be wrapped.
+// Registered AFTER .client() so the aim:web pin actions exist to be wrapped.
 if ('undefined' !== typeof SenecaBrowserStore) {
-  bus.use(SenecaBrowserStore, { pin: 'aim:*' })
+  bus.use(SenecaBrowserStore, {
+    pin: 'aim:web',
+    // Defaults plus 'revoke': aim:web,on:auth,revoke:apikey must
+    // invalidate the cached list:apikey reads.
+    write: ['save', 'remove', 'update', 'delete', 'create', 'done', 'set', 'add', 'revoke'],
+  })
 }
 
 // In-window devtools: a resizable/hideable pop-up showing live Seneca
 // message flows, config, and (via the store plugin above) the cache tree.
-// aim:* messages are the remote (backend) calls. Loaded as a global script
+// aim:web messages are the remote (backend) calls. Loaded as a global script
 // in index.html; guarded so a missing bundle never breaks the app.
 if ('undefined' !== typeof SenecaBrowserDebug) {
-  bus.use(SenecaBrowserDebug, { remotePins: 'aim:*' })
+  bus.use(SenecaBrowserDebug, { remotePins: 'aim:web' })
 }
 
 
@@ -75,4 +80,5 @@ export {
   bus,
   onEvent,
   emit,
-}
+}
+