@voxgig/build 4.4.0 → 4.12.0

package/tm/web/backend/test/unit/srv/auth/session.test.ts.frag

@@ -0,0 +1,189 @@
+import { test, describe } from 'node:test'
+import assert from 'node:assert'
+
+import { makeSeneca, as } from './auth.setup'
+
+
+// Sign-in / sign-out / session load, and the gateway wrappers that turn
+// them into cookie operations for the SPA.
+describe('auth session', () => {
+
+  async function withUser() {
+    const seneca = await makeSeneca()
+    const reg = await seneca.post('sys:user,register:user',
+      { name: 'Alice', email: 'alice@ex.com', password: 'alice-pass-01' })
+    assert.strictEqual(reg.ok, true)
+    return { seneca, user: reg.user }
+  }
+
+
+  test('signin succeeds with the right password and fails otherwise', async () => {
+    const { seneca } = await withUser()
+
+    const ok = await seneca.post('aim:auth,signin:user',
+      { email: 'alice@ex.com', password: 'alice-pass-01' })
+    assert.strictEqual(ok.ok, true)
+    assert.strictEqual(ok.user.email, 'alice@ex.com')
+
+    // aim:auth messages are gateway-reachable, so the result must never
+    // carry credentials: @seneca/user answers with the whole entity
+    // (password hash + salt) and its `fields` option does not stop it.
+    assert.strictEqual(ok.user.pass, undefined)
+    assert.strictEqual(ok.user.salt, undefined)
+    assert.deepStrictEqual(Object.keys(ok.user).sort(),
+      ['email', 'handle', 'id', 'name'])
+
+    const bad = await seneca.post('aim:auth,signin:user',
+      { email: 'alice@ex.com', password: 'wrong' })
+    assert.strictEqual(bad.ok, false)
+
+    await seneca.close()
+  })
+
+
+  test('the gateway wrapper returns a cookie token on success', async () => {
+    const { seneca } = await withUser()
+
+    const out = await seneca.post(
+      { aim: 'web', on: 'auth', signin: 'user', email: 'alice@ex.com', password: 'alice-pass-01' })
+    assert.strictEqual(out.ok, true)
+    // gateway-auth (express_cookie) sets the cookie from this field.
+    assert.ok(out.gateway$.auth.token)
+    assert.strictEqual(out.user.email, 'alice@ex.com')
+    assert.strictEqual(out.user.pass, undefined)
+
+    const bad = await seneca.post(
+      { aim: 'web', on: 'auth', signin: 'user', email: 'alice@ex.com', password: 'wrong' })
+    assert.strictEqual(bad.ok, false)
+    assert.strictEqual(bad.gateway$, undefined)
+    assert.ok(bad.why)
+
+    await seneca.close()
+  })
+
+
+  test('signout revokes the login server-side', async () => {
+    const { seneca, user } = await withUser()
+
+    const login = await seneca.post('aim:auth,signin:user',
+      { email: 'alice@ex.com', password: 'alice-pass-01' })
+    const token = login.login.token
+    assert.ok(token)
+
+    const before = await seneca.entity('sys/login').list$({ token })
+    assert.strictEqual(before[0].active, true)
+
+    const out = await seneca.post('aim:auth,signout:user',
+      { user_id: user.id, token })
+    assert.strictEqual(out.ok, true)
+
+    // The session must really be revoked: a token alone does not do it
+    // (@seneca/user answers no-user-query and leaves the row active), so
+    // the user id has to travel with it.
+    const after = await seneca.entity('sys/login').list$({ token })
+    assert.strictEqual(after[0].active, false)
+
+    await seneca.close()
+  })
+
+
+  test('the signout wrapper revokes the session and clears the cookie', async () => {
+    const { seneca, user } = await withUser()
+
+    const login = await seneca.post('aim:auth,signin:user',
+      { email: 'alice@ex.com', password: 'alice-pass-01' })
+    const token = login.login.token
+
+    // The gateway principal carries both the user and the login token.
+    const out = await seneca.post({
+      aim: 'web', on: 'auth', signout: 'user',
+      custom$: { principal: { user, token } },
+    })
+    assert.strictEqual(out.ok, true)
+    // Tells gateway-auth to clear the cookie.
+    assert.strictEqual(out.gateway$.auth.remove, true)
+
+    const after = await seneca.entity('sys/login').list$({ token })
+    assert.strictEqual(after[0].active, false)
+
+    // Signing out with no principal at all is still a clean no-op.
+    const anon = await seneca.post({ aim: 'web', on: 'auth', signout: 'user' })
+    assert.strictEqual(anon.ok, true)
+
+    await seneca.close()
+  })
+
+
+  test('load:auth reports the signed-in user, or nobody', async () => {
+    const { seneca, user } = await withUser()
+
+    const anon = await seneca.post({ aim: 'web', on: 'auth', load: 'auth' })
+    assert.strictEqual(anon.ok, true)
+    assert.strictEqual(anon.user, undefined)
+
+    const signed = await as(seneca, user, { aim: 'web', on: 'auth', load: 'auth' })
+    assert.strictEqual(signed.ok, true)
+    assert.strictEqual(signed.user.email, 'alice@ex.com')
+    assert.strictEqual(signed.user.pass, undefined)
+
+    // The service message behind it must not leak credentials either.
+    const direct = await seneca.post('aim:auth,load:auth', { user_id: user.id })
+    assert.strictEqual(direct.ok, true)
+    assert.strictEqual(direct.state, 'signedin')
+    assert.strictEqual(direct.user.pass, undefined)
+    assert.strictEqual(direct.user.salt, undefined)
+
+    const gone = await seneca.post('aim:auth,load:auth', { user_id: 'nope' })
+    assert.strictEqual(gone.ok, false)
+    assert.strictEqual(gone.state, 'signedout')
+
+    await seneca.close()
+  })
+
+
+  test('update:user changes the profile of the signed-in user only', async () => {
+    const { seneca, user } = await withUser()
+
+    const out = await as(seneca, user,
+      { aim: 'web', on: 'auth', update: 'user', data: { name: 'Alicia' } })
+    assert.strictEqual(out.ok, true)
+
+    const check = await seneca.post('sys:user,get:user', { email: 'alice@ex.com' })
+    assert.strictEqual(check.user.name, 'Alicia')
+
+    const anon = await seneca.post(
+      { aim: 'web', on: 'auth', update: 'user', data: { name: 'Mallory' } })
+    assert.strictEqual(anon.ok, false)
+    assert.strictEqual(anon.why, 'not-authenticated')
+
+    await seneca.close()
+  })
+
+
+  test('remind:pass never reveals whether the account exists', async () => {
+    const { seneca } = await withUser()
+
+    const known = await seneca.post(
+      { aim: 'web', on: 'auth', remind: 'pass', email: 'alice@ex.com' })
+    const unknown = await seneca.post(
+      { aim: 'web', on: 'auth', remind: 'pass', email: 'nobody@ex.com' })
+
+    // Same answer either way (no user enumeration), and nothing is sent.
+    assert.strictEqual(known.ok, true)
+    assert.strictEqual(unknown.ok, true)
+    assert.strictEqual(known.user, undefined)
+    assert.strictEqual(unknown.user, undefined)
+
+    await seneca.close()
+  })
+
+
+  test('get:info reports the service', async () => {
+    const seneca = await makeSeneca()
+    const out = await seneca.post('aim:auth,get:info')
+    assert.strictEqual(out.ok, true)
+    assert.strictEqual(out.srv, 'auth')
+    await seneca.close()
+  })
+})
+

package/tm/web/backend/test/unit/srv/ent/ent.setup.ts.frag

@@ -0,0 +1,53 @@
+
+import Seneca from 'seneca'
+
+import { entity } from '@voxgig/util'
+
+import Model from '../../../../model/model.json'
+
+const { base } = require('../../../../dist/env/shared/basic')
+
+
+// Build a Seneca instance with the generic entity service loaded from the
+// compiled dist/srv. In-memory entity store, no external deps.
+//
+// @seneca/owner is loaded with the SAME options as the running app (from
+// `base`): access control is enforced in the entity layer, so a test
+// harness without it would exercise a system that cannot deny anything.
+async function makeSeneca() {
+  const seneca = Seneca({ legacy: false, timeout: 2222, debug: { undead: true } })
+  seneca.context.model = Model
+  seneca.context.env = 'test'
+
+  return seneca
+    .test()
+    .use('promisify')
+    .use('entity', {
+      strict: true,
+      ent: entity(Model),
+    })
+    .use('entity-util', {
+      when: { active: true },
+    })
+    .use('owner', base.options.owner)
+    .use('reload')
+    .use('../../../../dist/srv/ent/ent-srv')
+    .ready()
+}
+
+
+// Post a message AS a given user, injecting the gateway-style principal into
+// meta.custom (mirrors what @seneca/gateway-auth attaches from the cookie).
+function as(seneca: any, user: any, msg: any) {
+  return seneca.post(Object.assign({}, msg, {
+    custom$: { principal: { user } },
+  }))
+}
+
+
+export {
+  makeSeneca,
+  as,
+  Model,
+}
+

package/tm/web/backend/test/unit/srv/ent/proxy.test.ts.frag

@@ -0,0 +1,109 @@
+import { test, describe } from 'node:test'
+import assert from 'node:assert'
+
+import { makeSeneca, as } from './ent.setup'
+
+
+// The browser proxies: aim:web,on:ent,cmd:* -> aim:ent,cmd:*
+//
+// A browser may only send aim:web, so these four actions ARE the entity
+// surface. Two things matter: they forward faithfully, and they are not a
+// way around the rules the real commands enforce.
+//
+// Forwarding is checked on the action functions directly - they are plain
+// modules, so a fake `this` records what they post. No boot, no store, and
+// nothing that depends on which entities this model happens to have.
+
+const ALICE = { id: 'u-alice', email: 'alice@ex.com' }
+
+const OPS = ['list', 'load', 'save', 'remove']
+
+function proxyAction(op: string) {
+  return require('../../../../dist/srv/ent/web_cmd_' + op + '.js')()
+}
+
+// A `this` that records posts instead of sending them.
+function recorder(result: any = { ok: true }) {
+  const posts: any[] = []
+  return {
+    posts,
+    ctx: {
+      post: async (pattern: string, msg: any) => {
+        posts.push({ pattern, msg })
+        return result
+      },
+    },
+  }
+}
+
+
+describe('entity browser proxies', () => {
+
+  test('each proxy forwards to its own entity command', async () => {
+    for (const op of OPS) {
+      const rec = recorder()
+      await proxyAction(op).call(rec.ctx, { ent: 'x/y' })
+      assert.strictEqual(rec.posts.length, 1, op)
+      assert.strictEqual(rec.posts[0].pattern, 'aim:ent,cmd:' + op, op)
+    }
+  })
+
+
+  test('arguments travel through unchanged', async () => {
+    const rec = recorder()
+
+    await proxyAction('list').call(rec.ctx, { ent: 'x/y', q: { a: 1 } })
+    assert.deepStrictEqual(rec.posts[0].msg.q, { a: 1 })
+    assert.strictEqual(rec.posts[0].msg.ent, 'x/y')
+
+    await proxyAction('load').call(rec.ctx, { ent: 'x/y', id: 'e01' })
+    assert.strictEqual(rec.posts[1].msg.id, 'e01')
+
+    await proxyAction('save').call(rec.ctx, { ent: 'x/y', item: { t: 'v' } })
+    assert.deepStrictEqual(rec.posts[2].msg.item, { t: 'v' })
+
+    await proxyAction('remove').call(rec.ctx, { ent: 'x/y', id: 'e01' })
+    assert.strictEqual(rec.posts[3].msg.id, 'e01')
+  })
+
+
+  test('the result is returned unchanged', async () => {
+    const rec = recorder({ ok: true, list: [{ id: 'e01' }] })
+    const out = await proxyAction('list').call(rec.ctx, { ent: 'x/y' })
+    assert.deepStrictEqual(out, { ok: true, list: [{ id: 'e01' }] })
+
+    const failed = recorder({ ok: false, why: 'forbidden' })
+    const bad = await proxyAction('load').call(failed.ctx, { ent: 'x/y', id: 'e01' })
+    assert.deepStrictEqual(bad, { ok: false, why: 'forbidden' })
+  })
+
+
+  test('proxies enforce the same rules, not weaker ones', async () => {
+    const seneca = await makeSeneca()
+
+    // Unauthenticated: refused, exactly like the real commands.
+    for (const cmd of OPS) {
+      const out = await seneca.post({
+        aim: 'web', on: 'ent', cmd, ent: 'sys/user', id: 'x', item: {},
+      })
+      assert.strictEqual(out.ok, false, cmd)
+      assert.strictEqual(out.why, 'not-authenticated', cmd)
+    }
+
+    // The sys zone stays unreachable through the proxy.
+    const sys = await as(seneca, ALICE,
+      { aim: 'web', on: 'ent', cmd: 'list', ent: 'sys/apikey' })
+    assert.strictEqual(sys.ok, false)
+    assert.strictEqual(sys.why, 'unknown-entity')
+
+    // sys/user remains read-only through it too.
+    const write = await as(seneca, ALICE, {
+      aim: 'web', on: 'ent', cmd: 'save', ent: 'sys/user', item: { name: 'Hacked' },
+    })
+    assert.strictEqual(write.ok, false)
+    assert.strictEqual(write.why, 'read-only')
+
+    await seneca.close()
+  })
+})
+

package/tm/web/docs/explanation/web-architecture.md.frag

@@ -0,0 +1,50 @@
+# Explanation: web app architecture
+
+*Diátaxis: explanation — why the generated app is built this way.*
+
+## One primitive: Seneca messages
+
+The frontend is web components on a browser Seneca bus. Every data flow —
+backend CRUD, auth, cross-component events, cache reactivity — is a
+pattern-matched message. `aim:*` messages travel transparently to the
+backend gateway (the same patterns the backend services answer); local
+concerns stay local. One primitive means one debugging story (the
+in-window devtools show every flow), one interception point (the store
+cache), and no parallel event system to keep consistent.
+
+## Model-driven at runtime
+
+The app fetches `/model.json` and derives its UI from it: the entity
+menu, list columns, forms, relationship pickers and drill-down (from
+`ref` fields), project scoping. Adding an entity to the model changes the
+running UI on reload — no regeneration, no per-entity components, no
+merge conflicts. This is what lets the same generated codebase serve an
+entity graph of hundreds of entities.
+
+## Access is membership, not ownership
+
+Signed-in users collaborate through projects: membership in a project
+grants access to the project's data (any entity carrying a
+`ref: 'proj/project'` field is scoped to the selected project). The
+generic backend `ent` service enforces this on every message — the
+frontend only *reflects* scoping (the project selector), it never
+enforces it.
+
+## Generated once, then yours
+
+The SPA is a starting point, not a framework artifact: after generation
+the project owns it. Customisation is layered so upgrades stay cheap —
+theme tokens (model) → CSS overrides (`custom.css`) → hooks
+(`customise.js`) → custom entity views (model-declared) → direct edits
+(last resort). Only `views.js` and `theme.css` regenerate, because they
+are pure functions of the model.
+
+## No framework, deliberately
+
+Vanilla custom elements + `innerHTML` rendering keep the generated code
+dependency-light, readable, and long-lived (no framework version
+treadmill in generated projects). The cost — manual re-render discipline —
+is contained by two conventions: explicit `reload()` calls after
+mutations, and a render token to discard stale async renders (see
+`cmp/admin.js`).
+

package/tm/web/docs/how-to/add-a-custom-entity-view.md.frag

@@ -0,0 +1,53 @@
+# How to add a custom entity view
+
+*Diátaxis: how-to guide — replace the generic admin UI for one entity
+with a hand-coded component, declared in the model.*
+
+## 1. Declare it in the model
+
+In `backend/model/ent.aontu`, mark the entity:
+
+```
+shop: product: ux: { view: 'custom' }
+```
+
+## 2. Generate the starter
+
+```bash
+cd backend && npm run model-build
+```
+
+This creates `$$fe$$/src/cmp/view/shop_product.js` (a working starter
+component — create-once, so your edits survive every future build) and
+regenerates `$$fe$$/src/views.js`, the index that imports all custom views.
+The shell now mounts `<vg-view-shop-product>` instead of the generic
+`<vg-entity-admin>` for that entity.
+
+## 3. Implement the view
+
+The component contract (same as the generic admin):
+
+- **Properties** (set by the shell before `reload()`):
+  - `canon` — the entity canon, e.g. `'shop/product'`
+  - `projectId` — current project id when the entity is project-scoped,
+    else `null`
+  - `detailId` — an entity id to open in detail, or `null`
+  - `onNavigate(canon, id)` — call to navigate elsewhere in the app
+- **Method**: `reload()` — re-fetch and re-render.
+
+Use the same building blocks the generic admin uses:
+
+```js
+import * as Model from '../../model.js'   // labels, fields, refs graph
+import * as Api from '../../api.js'       // Api.list/load/save/remove(canon, ...)
+```
+
+Data via `Api` goes through the generic `aim:ent` messages, so
+membership scoping and validation apply unchanged.
+
+## Reverting
+
+Remove the `ux` declaration and run `model-build` — `views.js` drops the
+import and the entity falls back to the generic admin. Your component
+file stays (delete it manually if unwanted).
+

package/tm/web/docs/how-to/change-the-theme.md.frag

@@ -0,0 +1,63 @@
+# How to change the theme
+
+*Diátaxis: how-to guide — the design theme is part of the model; modes
+and tokens flow from there into generated CSS.*
+
+## Change a token
+
+Edit `backend/model/theme.aontu` — each named mode (light, dark, ...) is
+a set of design tokens:
+
+```
+modes: {
+  light: {
+    primary: '#7c3aed'
+    # ...
+  }
+}
+```
+
+Then regenerate:
+
+```bash
+cd backend && npm run model-build
+```
+
+`$$fe$$/src/theme.css` is rewritten: every token becomes a CSS variable
+(`--vg-primary`, ...) scoped to its mode
+(`:root[data-theme-mode="light"]`; the default mode also on `:root`).
+Do not edit `theme.css` by hand — it regenerates from the model.
+
+## Add a mode
+
+Add a new block under `modes:` (e.g. `sepia: { ... }`) with the same
+token set, and set `mode:` if it should be the default. After
+`model-build`, the shell's user menu automatically offers the new mode
+(the toggle appears whenever more than one mode exists), and the user's
+choice persists (localStorage `vg-theme-mode`).
+
+## Override per project without touching the model
+
+`$$fe$$/src/custom.css` loads after the theme:
+
+```css
+:root { --vg-radius: 10px; }                      /* all modes */
+:root[data-theme-mode="dark"] { --vg-bg: #000; }  /* one mode */
+```
+
+## Add modes or intercept the mode list at runtime
+
+```js
+// $$fe$$/src/customise.js
+import * as Hooks from './hooks.js'
+Hooks.addFilter('theme:modes', (modes) => [...modes, 'sepia'])
+```
+
+(Provide the CSS for a runtime-added mode yourself in `custom.css`.)
+
+## Standard tokens
+
+`primary`, `primary-dark`, `bg`, `surface`, `text`, `muted`, `border`,
+`topbar-bg`, `topbar-fg`, `accent-bg`, `font`, `radius`, `shadow-card`.
+Any additional token you add becomes `--vg-<token>` too.
+

package/tm/web/docs/how-to/customise-the-web-app.md.frag

@@ -0,0 +1,68 @@
+# How to customise the web app
+
+*Diátaxis: how-to guide — change the generated app's look and behaviour
+without editing generated components.*
+
+Customisations live in two create-once files that survive regeneration:
+`$$fe$$/src/customise.js` (hook registrations) and `$$fe$$/src/custom.css`
+(style overrides).
+
+## Inject or change HTML
+
+```js
+// $$fe$$/src/customise.js
+import * as Hooks from './hooks.js'
+
+Hooks.addHtml('shell:topbar:right', () => '<span class="vg-badge">Beta</span>')
+Hooks.addHtml('admin:row:actions', ({ canon }) =>
+  'todo/item' === canon ? '<button class="vg-star" data-act="star">star</button>' : '')
+```
+
+## Transform data
+
+```js
+// Sort or filter list rows before render:
+Hooks.addFilter('admin:list:items', (items, { canon }) =>
+  'todo/item' === canon
+    ? items.slice().sort((a, b) => (a.done === b.done ? 0 : a.done ? 1 : -1))
+    : items)
+
+// Adjust the save payload:
+Hooks.addFilter('admin:save:data', (data) => ({ ...data, source: 'web' }))
+```
+
+## Run behaviour at lifecycle moments
+
+```js
+Hooks.addAction('admin:list:after', ({ root, canon, items }) => {
+  // wire events on injected elements, integrate analytics, etc.
+})
+```
+
+All hooks are synchronous and failure-isolated (a throwing hook is logged
+and skipped). The full list of points is in the
+[web app reference](../reference/web-app.md#hook-points).
+
+## Override styles
+
+Generated styles use CSS variables from the theme. Override tokens or add
+rules in `$$fe$$/src/custom.css`:
+
+```css
+:root { --vg-primary: #7c3aed; }
+.vg-badge { background: gold; color: #333; }
+```
+
+For theme-wide changes (all modes, or new modes), change the model
+instead — see [Change the theme](change-the-theme.md).
+
+## When hooks aren't enough
+
+- Replace an entity's whole view:
+  [Add a custom entity view](add-a-custom-entity-view.md).
+- Backend behaviour: override Seneca actions with priors in the backend
+  services.
+- As a last resort, edit the generated components directly — they are
+  create-once and yours; just note that framework updates then need a
+  manual merge.
+

package/tm/web/docs/how-to/use-the-api.md.frag

@@ -0,0 +1,53 @@
+# How to use the REST API
+
+*Diátaxis: how-to guide — the strict-JSON REST API generated from the
+model (`main.api` in `backend/model/api.aontu`).*
+
+## Get an API key
+
+Sign in to the web app → user menu → **Settings & security** → **API
+keys** → create a key. Copy it immediately — it is shown only once (only
+a hash is stored). Revoke keys there too; revocation is immediate.
+
+## Call the API
+
+Uniform semantic paths per entity — `<prefix>/<version>/<zone>/<name>`:
+
+```bash
+KEY=vk_...
+B=http://localhost:8080/api/v1
+
+curl -H "Authorization: Bearer $KEY" $B/proj/project            # list
+curl -H "Authorization: Bearer $KEY" "$B/proj/project?name=X"   # filtered list
+curl -H "Authorization: Bearer $KEY" $B/proj/project/<id>       # load
+curl -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
+  -d '{"name":"New project"}' $B/proj/project                   # create -> 201
+curl -X PUT -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
+  -d '{"note":"updated"}' $B/proj/project/<id>                  # partial update
+curl -X DELETE -H "Authorization: Bearer $KEY" $B/proj/project/<id>
+```
+
+Results: `{ items: [...] }` (list), `{ item: {...} }` (load/create/update),
+`{ ok: true, id }` (delete). Errors carry an HTTP status and
+`{ error: { code, message?, details? } }`.
+
+The API is **strict**: request bodies are validated against the entity's
+model definition (generated shapes) — unknown fields are rejected (400),
+required fields enforced, server-managed fields (`id`, `owner_id`,
+`t_c`, `t_m`) are read-only. Access is the same project-membership
+scoping as the web app, as the key's owning user.
+
+## The OpenAPI spec
+
+Generated from the model on every model-build:
+`backend/gen/api/openapi.json`, also served unauthenticated at
+`<prefix>/openapi.json`. Schemas come from the entity field definitions;
+operation ids are uniform (`list_<zone>_<name>`, `create_...`, ...) so an
+SDK can be generated from it (e.g. with sdkgen).
+
+## Configure
+
+`backend/model/api.aontu` — `prefix`, `version`, `active`, and per-entity
+exposure (`ent: 'zone/name': { active: false }`). The sys zone is never
+exposed. Run `npm run model-build` after changes.
+