@tabbr/module-cli 0.4.1 → 0.6.0

package/README.md

@@ -31,6 +31,30 @@ npx tabbr-module init       # asks for the club code, module id and a fallback t
 }
 ```
 
+### Where you develop against: tabbr.config.local.json
+
+`tabbr.config.json` describes the module and is committed. The club and API host *you* work against are yours, not
+the module's: put them in `tabbr.config.local.json` - add it to `.gitignore` - and leave `tabbr.config.json` as it is
+(e.g. on production, for the store). `init --local` writes it:
+
+```bash
+npx tabbr-module init --local   # asks for the club code and the API host (default: your local backend,
+                                # https://api.local.tabbr.be; https://api.tabbr.be for a club on production)
+```
+
+```json
+{ "club": "ABC", "apiHost": "https://api.local.tabbr.be" }
+```
+
+It may set `club`, `apiHost`, `localApiHost` and `shellUrl` (other keys are ignored, with a warning) and overrides
+`tabbr.config.json` for them in every command - except `publish --store`, which goes where `tabbr.config.json` says
+unless you pass `--local` or `--api-host`. Command-line options still win, and the CLI says which file it used.
+The one next to `tabbr.config.json` counts, else the one a folder up - one file for every module in that folder, as
+the Tabbr repository's `modules/` has. The module's dev preview reads the same one: its `src/app/app.config.ts` imports
+`tabbr.config.local.json`, which the `paths` in `tsconfig.local-config.json` resolve to that file, else to
+`tabbr.config.json` itself (copy both from one of the Tabbr repository's modules). It's never part of a store
+submission's source.
+
 ### The title and description of your module
 
 The name Tabbr shows for your module (in the settings list and its page header) is translated like the one of its
@@ -63,7 +87,8 @@ sandboxed, triggered on a cron schedule or on an entity's create/update - see
     "secretFieldNames": ["apiKey"],
     "triggers": [
       { "type": "CRON", "name": "pollFlights", "cronExpression": "*/5 * * * *", "handler": "pollFlights" },
-      { "type": "ENTITY_HOOK", "name": "onFlightSaved", "entity": "flight", "event": "onUpdate", "handler": "onFlightSaved" }
+      { "type": "ENTITY_HOOK", "name": "onFlightSaved", "entity": "flight", "event": "onUpdate", "handler": "onFlightSaved" },
+      { "type": "OGN_EVENT", "name": "onOgn", "handler": "onOgnEvent" }
     ]
   }
 }
@@ -95,6 +120,21 @@ export function pollFlights() {
   `onDelete`), with that entity bound under its own name (e.g. `flight`) in the handler's scope - before the save.
   `onCreated` / `onUpdated` run after it, once committed, in the background: for a handler that reads the database
   (e.g. "is this person in that list now"). A module's own writes don't trigger its handlers.
+- `"OGN_EVENT"` (module API 1.10, `"engines": { "tabbr": "^1.10" }`) runs for every start and landing OGN reports that
+  the club gets: on one of its airfields, or by one of the airplanes it follows wherever they fly - the club sets both
+  in Instellingen › Vliegtuigen › OGN. The handler gets an `OgnEvent` (`@tabbr/module-sdk/backend`):
+  `{ type: 'TAKEOFF' | 'LANDING', fieldCode, address, time, atClubField, followedAirplane, airplaneId }`. One handler
+  runs at a time, in the order the events came; keep it quick (OGN can report many in a busy hour), and make getting
+  the same event twice harmless. The club sees "krijgt de starts en landingen van OGN" when
+  it installs the module.
+
+  ```ts
+  export function onOgnEvent(event: OgnEvent) {
+    if (event.type === 'LANDING' && event.airplaneId) {
+      // e.g. close the flight of that airplane that is still in the air
+    }
+  }
+  ```
 - Needs `esbuild` installed in the workspace (`npm install -D esbuild`) - only used at publish
   time, bundled into one dependency-free `bundle.js` the server runs in a GraalVM sandbox, so
   regular npm packages can be imported in your TS but nothing Node-specific (no `fs`, no native
@@ -127,7 +167,7 @@ rules, the club's extra fields, hooks, audit). Add an `"entities"` array to `tab
 `publish` checks the declarations (names, keys, types) before uploading and sends them in the backend manifest - also
 for a module that has no backend code (then only the entities are published). The frontend addresses records by field
 key with the SDK's `injectModuleEntity()`, the backend with `tabbr.entities.<name>`. See `docs/module-entities.md` in the
-Tabbr repository for the field types, access rules and what the club gets; `tabbr-groups-module/` is a complete example.
+Tabbr repository for the field types, access rules and what the club gets; `modules/tabbr-groups-module/` is a complete example.
 
 ## Contracts
 
@@ -195,7 +235,7 @@ upload:
 
 `npx tabbr-module publish --local` publishes into your own local tabbr (the environment behind
 `<club>.local.tabbr.be`) instead of production: it uploads to `https://api.local.tabbr.be` (set
-`"localApiHost"` in `tabbr.config.json` to use another URL) and trusts your mkcert root CA, which Node
+`"localApiHost"` in `tabbr.config.local.json` to use another URL) and trusts your mkcert root CA, which Node
 doesn't do on its own (`NODE_EXTRA_CA_CERTS` is set automatically; if mkcert's root CA can't be found,
 set it yourself - `mkcert -CAROOT` shows where it lives). `--club` picks the club in that environment;
 login still goes through the real Keycloak, which local backends validate too.

package/bin/tabbr-module.js

@@ -9,7 +9,9 @@ const { publish, publishToStore, submitSourceToStore, storeMeta } = require('../
 const { packSource } = require('../src/source');
 const { fetchScriptTypes, fetchAllEntityTypes, fetchContractTypes, VALID_KINDS } = require('../src/fetch-types');
 const { usesOf } = require('../src/backend-build');
-const { CONFIG_FILE, DEFAULT_API_HOST, readConfig, requireClub, runInit } = require('../src/config');
+const {
+  CONFIG_FILE, LOCAL_CONFIG_FILE, LOCAL_CONFIG_KEYS, DEFAULT_API_HOST, readConfig, readLocalConfig, requireClub, runInit,
+} = require('../src/config');
 const { DEFAULT_LOCAL_API_HOST, trustLocalCertificateOrRespawn } = require('../src/local');
 const DEFAULT_KIND = 'HOOK'; // matches the server's own @RequestParam default for /meta/script
 
@@ -46,10 +48,22 @@ function printUsage() {
   console.log(`Every option below can also be set in ${CONFIG_FILE} in the workspace root (option name
 in camelCase, e.g. "club", "moduleId", "apiHost"); command-line options win.
 
+Where YOU develop against goes in ${LOCAL_CONFIG_FILE} instead: not committed (add it to
+.gitignore), next to ${CONFIG_FILE} or a folder up (then for every module in that folder; the
+one in the workspace wins). Its ${LOCAL_CONFIG_KEYS.join(', ')} override those in ${CONFIG_FILE} -
+here and in the module's dev preview; not the API host of "publish --store". E.g. { "club": "ABC",
+"apiHost": "https://api.local.tabbr.be" } works against your local backend while ${CONFIG_FILE}
+keeps production; "init --local" writes it.
+
 Usage: tabbr-module init [--club <CODE>] [--module-id <id>] [--title <text>] [--api-host <url>]
 
 Asks for the club code (and module id / title) and writes ${CONFIG_FILE}.
 
+Usage: tabbr-module init --local [--club <CODE>] [--api-host <url>]
+
+Asks for the club code and the API host (by default your own local backend, ${DEFAULT_LOCAL_API_HOST})
+and writes only ${LOCAL_CONFIG_FILE}. ${CONFIG_FILE} is left as it is.
+
 Usage: tabbr-module publish [options]
 
 Builds and publishes whichever parts of the workspace are present, in ONE upload: a frontend (an
@@ -71,7 +85,12 @@ Backend part (all in ${CONFIG_FILE} under "backend", not as CLI flags):
   secretFieldNames             Names of your module's settings keys that hold secrets (masked from
                               every settings GET response once saved)
   triggers                     [{type: "CRON", name, cronExpression, handler} |
-                               {type: "ENTITY_HOOK", name, entity, event, handler}]
+                               {type: "ENTITY_HOOK", name, entity, event, handler, serializeOn?} |
+                               {type: "PUBLIC", name, handler, params}  (module API 1.5:
+                               GET /api/<club>/public/module/<moduleId>/data/<name>, no login) |
+                               {type: "OGN_EVENT", name, handler}  (module API 1.10: the club's OGN starts/landings)]
+  publicActions                [{name, handler, rateLimit?: "10/h", verifiedEmail?: true}] - functions anyone may
+                               call without logging in: POST /api/<club>/public/custommodule/<id>/action/<name>
 
 Optional:
   --icon <name>              Menu icon name
@@ -316,13 +335,31 @@ async function main() {
     await runInit(flags.cwd, flags);
     return;
   }
-  const args = { apiHost: DEFAULT_API_HOST, ...readConfig(flags.cwd), ...flags };
+  const local = readLocalConfig(flags.cwd);
+  const localValues = { ...(local ? local.values : {}) };
+  // A store submission goes where tabbr.config.json says (production), not to a local file's API host: --local or
+  // --api-host for another one.
+  const storeHostKept = command === 'publish' && flags.store && localValues.apiHost !== undefined;
+  if (storeHostKept) delete localValues.apiHost;
+  const args = { apiHost: DEFAULT_API_HOST, ...readConfig(flags.cwd), ...localValues, ...flags };
   if (args.local && !flags.apiHost) {
     // --local targets your own local backend (https://api.local.tabbr.be, the same one
-    // <club>.local.tabbr.be talks to); "localApiHost" in tabbr.config.json overrides it.
+    // <club>.local.tabbr.be talks to); "localApiHost" in tabbr.config.local.json or tabbr.config.json overrides it.
     args.apiHost = args.localApiHost || DEFAULT_LOCAL_API_HOST;
   }
   trustLocalCertificateOrRespawn(args.apiHost);
+  // after a respawn for the local certificate: said once
+  if (local) {
+    const where = path.relative(flags.cwd, local.file);
+    const set = Object.entries(localValues).map(([key, value]) => `${key} ${value}`).join(', ');
+    console.log(`Using ${where}${set ? `: ${set}` : ''}`);
+    if (storeHostKept) {
+      console.log(`  not its apiHost: the module store at ${args.apiHost}${args.local || flags.apiHost ? '' : ' (--local for your local backend\'s)'}`);
+    }
+    if (local.ignored.length) {
+      console.warn(`  ignored there: ${local.ignored.join(', ')} - only ${LOCAL_CONFIG_KEYS.join(', ')} can be set in ${LOCAL_CONFIG_FILE}`);
+    }
+  }
   if (command === 'publish') {
     await runPublish(args);
   } else if (command === 'build') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tabbr/module-cli",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Set up, build and publish a Native Federation club module to a tabbr club.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "SystemWorks BV",

package/src/backend-build.js

@@ -46,6 +46,41 @@ function entitiesOf(config) {
   return entities;
 }
 
+/**
+ * The audiences the module declares (`"audiences"` in tabbr.config.json, module API 1.8): `{ key, name, description,
+ * criteria }` - made among the club's audiences when the module is installed. Checked just enough to fail here: keys,
+ * names, and every `{audience:<key>}` in the entities' rules declared. Tabbr checks them again (criteria about the
+ * logged-in user, audiences in a circle).
+ */
+function audiencesOf(config, entities) {
+  const audiences = config.audiences || [];
+  if (!Array.isArray(audiences)) {
+    throw new Error('"audiences" in tabbr.config.json must be an array: [{ "key": "uploaders", "name": "Fotografen", "criteria": [...] }].');
+  }
+  const keys = new Set();
+  for (const audience of audiences) {
+    if (!audience || !/^[a-z][a-zA-Z0-9]{0,39}$/.test(audience.key || '')) {
+      throw new Error(`Audience key "${audience && audience.key}" is not valid: camelCase letters and digits, starting lowercase.`);
+    }
+    if (keys.has(audience.key)) {
+      throw new Error(`Audience "${audience.key}" is declared twice.`);
+    }
+    keys.add(audience.key);
+    if (typeof audience.name !== 'string' || !audience.name.trim() || audience.name.length > 80) {
+      throw new Error(`Audience "${audience.key}" needs a name (at most 80 characters).`);
+    }
+    if (audience.criteria != null && !Array.isArray(audience.criteria)) {
+      throw new Error(`Audience "${audience.key}": "criteria" must be an array of lines ({ "andFilterValues": [...] }).`);
+    }
+  }
+  for (const match of JSON.stringify(entities).matchAll(/\{audience:([^}]*)\}/g)) {
+    if (!keys.has(match[1])) {
+      throw new Error(`A rule refers to {audience:${match[1]}}, which "audiences" in tabbr.config.json doesn't declare.`);
+    }
+  }
+  return audiences;
+}
+
 const CONTRACT_NAME = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
 
 /**
@@ -118,18 +153,19 @@ function providesOf(cwd, config) {
  * and the contracts it uses and provides - which a module can do without any backend code, so then only the manifest
  * is produced (`bundleJs` null). `files`: more files for the build's `backend/` (the TypeScript of what it provides).
  *
- * Returns `null` when the workspace has no backend part, no entities and uses or provides no contracts, so `build.js`
+ * Returns `null` when the workspace has no backend part, no entities, no audiences and uses or provides no contracts, so `build.js`
  * can skip it entirely for such a frontend-only module.
  */
 async function buildBackend(cwd, config) {
   const backendConfig = config.backend;
   const entities = entitiesOf(config);
+  const audiences = audiencesOf(config, entities);
   const uses = usesOf(config);
   const optionalUses = usesOf(config, 'optionalUses');
   const provides = providesOf(cwd, config);
   const bundleJs = backendConfig ? await bundle(cwd, backendConfig) : null;
-  if (bundleJs == null && entities.length === 0 && Object.keys(uses).length === 0 && Object.keys(optionalUses).length === 0
-    && Object.keys(provides.versions).length === 0) {
+  if (bundleJs == null && entities.length === 0 && audiences.length === 0 && Object.keys(uses).length === 0
+    && Object.keys(optionalUses).length === 0 && Object.keys(provides.versions).length === 0) {
     return null;
   }
   const settings = backendConfig || {};
@@ -138,19 +174,34 @@ async function buildBackend(cwd, config) {
     allowedHosts: [...(settings.allowedHosts || []), ...(config.local ? settings.localAllowedHosts || [] : [])],
     secretFieldNames: settings.secretFieldNames || [],
     triggers: bundleJs == null ? [] : settings.triggers || [],
+    // functions anyone may call without logging in (e.g. submitting a public form) - shown to the club when it installs
+    publicActions: bundleJs == null ? [] : settings.publicActions || [],
     entities,
     // the module gives persons roles (tabbr.access.setManagedRoles) - shown to the club when it installs the module
     manageRoles: bundleJs != null && settings.manageRoles === true,
+    // the built-in entities (besides its own) it may change - permissions.entities.write; the server refuses any other write
+    writeEntities: bundleJs != null ? writeEntitiesOf(config) : [],
     // the contracts it uses - for its frontend part as well, so the manifest is written for a frontend-only module too
     uses,
     optionalUses,
     // the contracts it provides, with their version; their TypeScript goes along as backend/contracts/<name>.d.ts
     provides: provides.versions,
+    // its own audiences (module API 1.8), made among the club's when it is installed
+    audiences,
   };
 
   return { bundleJs, manifestJson: JSON.stringify(manifest, null, 2), files: provides.files };
 }
 
+/** `permissions.entities.write`: names of entities the module may change besides its own (e.g. "person"). */
+function writeEntitiesOf(config) {
+  const write = config.permissions?.entities?.write ?? [];
+  if (!Array.isArray(write) || write.some((name) => typeof name !== 'string' || !/^[a-z][a-zA-Z0-9]{1,39}$/.test(name))) {
+    throw new Error('"permissions.entities.write" must be a list of entity names, e.g. ["person"].');
+  }
+  return [...new Set(write)];
+}
+
 /** The backend entry bundled into one script, or null when there is no entry file (and none was configured explicitly). */
 async function bundle(cwd, backendConfig) {
   const entry = backendConfig.entry || DEFAULT_ENTRY;
@@ -191,4 +242,4 @@ async function bundle(cwd, backendConfig) {
   return result.outputFiles[0].text;
 }
 
-module.exports = { buildBackend, entitiesOf, usesOf, providesOf, DEFAULT_ENTRY };
+module.exports = { buildBackend, entitiesOf, audiencesOf, usesOf, providesOf, DEFAULT_ENTRY };

package/src/config.js

@@ -3,10 +3,23 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline/promises');
+const { execFileSync } = require('child_process');
+const { DEFAULT_LOCAL_API_HOST } = require('./local');
 
 const CONFIG_FILE = 'tabbr.config.json';
+const LOCAL_CONFIG_FILE = 'tabbr.config.local.json';
+/** What a tabbr.config.local.json may set: where this checkout talks to - never what the module is. */
+const LOCAL_CONFIG_KEYS = ['club', 'apiHost', 'localApiHost', 'shellUrl'];
 const DEFAULT_API_HOST = 'https://api.tabbr.be';
 
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch (err) {
+    throw new Error(`${file} is not valid JSON: ${err.message}`);
+  }
+}
+
 /**
  * Reads the workspace's tabbr.config.json - the one place a module project records which club it
  * targets, its module id and so on. Both this CLI and the module's own dev-preview harness read it,
@@ -14,18 +27,31 @@ const DEFAULT_API_HOST = 'https://api.tabbr.be';
  */
 function readConfig(cwd) {
   const file = path.join(cwd, CONFIG_FILE);
-  if (!fs.existsSync(file)) return {};
-  try {
-    return JSON.parse(fs.readFileSync(file, 'utf-8'));
-  } catch (err) {
-    throw new Error(`${file} is not valid JSON: ${err.message}`);
-  }
+  return fs.existsSync(file) ? readJson(file) : {};
+}
+
+/**
+ * The developer's own tabbr.config.local.json (not committed): the club and API host this checkout
+ * talks to, over those in tabbr.config.json - so a module whose tabbr.config.json targets
+ * production can be developed against a local backend without editing it. The one in the
+ * workspace, else the one a folder up (which then covers every module in that folder); the module's
+ * dev preview finds the same one (tsconfig.local-config.json). Only LOCAL_CONFIG_KEYS count, the
+ * other keys are returned as `ignored`. Returns null when there is none.
+ */
+function readLocalConfig(cwd) {
+  const file = [path.join(cwd, LOCAL_CONFIG_FILE), path.join(cwd, '..', LOCAL_CONFIG_FILE)].find(f => fs.existsSync(f));
+  if (!file) return null;
+  const all = readJson(file);
+  const values = Object.fromEntries(LOCAL_CONFIG_KEYS.filter(key => all[key] !== undefined).map(key => [key, all[key]]));
+  const ignored = Object.keys(all).filter(key => !LOCAL_CONFIG_KEYS.includes(key));
+  return { file, values, ignored };
 }
 
 /** Uppercase club code, or throws with instructions when none is configured. */
 function requireClub(club) {
   if (!club) {
-    throw new Error(`No club configured. Run "npx tabbr-module init" (or set "club" in ${CONFIG_FILE}).`);
+    throw new Error(`No club configured. Set "club" in ${LOCAL_CONFIG_FILE} (yours, not committed) or ${CONFIG_FILE}, ` +
+      'or run "npx tabbr-module init".');
   }
   return club.toUpperCase();
 }
@@ -34,19 +60,39 @@ function slug(text) {
   return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
 }
 
-/**
- * Asks for the club code (and offers defaults for the rest) and writes tabbr.config.json, keeping
- * any values already in it as the defaults.
- */
-async function runInit(cwd, overrides) {
-  const file = path.join(cwd, CONFIG_FILE);
-  const current = readConfig(cwd);
+/** False only when the workspace is in a git repository that would track `file`. */
+function gitIgnores(cwd, file) {
+  try {
+    execFileSync('git', ['check-ignore', '-q', file], { cwd, stdio: 'ignore' });
+    return true;
+  } catch (err) {
+    return err.status !== 1; // 1: not ignored; anything else: no git, or not a repository
+  }
+}
+
+function asker() {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   const ask = async (question, fallback) => {
     if (!process.stdin.isTTY) return fallback;
     const answer = (await rl.question(fallback ? `${question} [${fallback}]: ` : `${question}: `)).trim();
     return answer || fallback;
   };
+  return { ask, close: () => rl.close() };
+}
+
+/**
+ * Asks for the club code (and offers defaults for the rest) and writes tabbr.config.json, keeping
+ * any values already in it as the defaults. With --local: only where you develop against, in
+ * tabbr.config.local.json - see runInitLocal.
+ */
+async function runInit(cwd, overrides) {
+  if (overrides.local) {
+    await runInitLocal(cwd, overrides);
+    return;
+  }
+  const file = path.join(cwd, CONFIG_FILE);
+  const current = readConfig(cwd);
+  const { ask, close } = asker();
 
   try {
     const club = (overrides.club || await ask('Club code (the part before .tabbr.be, e.g. abc)', current.club))?.toUpperCase();
@@ -68,8 +114,35 @@ async function runInit(cwd, overrides) {
     fs.writeFileSync(file, JSON.stringify(config, null, 2) + '\n');
     console.log(`\nWrote ${file}. Next: "npm start" to preview, "npm run publish-module" to publish.`);
   } finally {
-    rl.close();
+    close();
+  }
+}
+
+/**
+ * `init --local`: asks for the club code and the API host - by default your own local backend
+ * (https://api.local.tabbr.be) - and writes them in the workspace's tabbr.config.local.json, and
+ * nothing else: tabbr.config.json, the module's manifest, stays as it is (e.g. on production, for
+ * the store).
+ */
+async function runInitLocal(cwd, overrides) {
+  const file = path.join(cwd, LOCAL_CONFIG_FILE);
+  const current = fs.existsSync(file) ? readJson(file) : {};
+  const { ask, close } = asker();
+  try {
+    const club = (overrides.club || await ask('Club code (e.g. abc)', current.club || readConfig(cwd).club))?.toUpperCase();
+    if (!club) throw new Error('A club code is required.');
+    const apiHost = overrides.apiHost
+      || await ask(`API host (${DEFAULT_API_HOST} for a club on production)`, current.apiHost || DEFAULT_LOCAL_API_HOST);
+    const local = { ...current, club, apiHost };
+    fs.writeFileSync(file, JSON.stringify(local, null, 2) + '\n');
+    console.log(`\nWrote ${file}: club ${club}, apiHost ${apiHost}. Next: "npm start" to preview, ` +
+      '"npm run publish-module" to publish there.');
+    if (!gitIgnores(cwd, file)) console.warn(`It's yours, not the module's: add ${LOCAL_CONFIG_FILE} to .gitignore.`);
+  } finally {
+    close();
   }
 }
 
-module.exports = { CONFIG_FILE, DEFAULT_API_HOST, readConfig, requireClub, runInit };
+module.exports = {
+  CONFIG_FILE, LOCAL_CONFIG_FILE, LOCAL_CONFIG_KEYS, DEFAULT_API_HOST, readConfig, readLocalConfig, requireClub, runInit,
+};

package/src/source.js

@@ -5,8 +5,12 @@ const path = require('path');
 const { execFileSync } = require('child_process');
 const archiver = require('archiver');
 
-/** Never part of a module's source: installed packages, build output, caches, editor state. */
-const SKIP = new Set(['node_modules', 'dist', '.angular', 'out-tsc', '.git', '.yalc', '.idea', '.vscode', 'coverage']);
+/**
+ * Never part of a module's source: installed packages, build output, caches, editor state - and the developer's own
+ * tabbr.config.local.json (where they develop against), also when it isn't in .gitignore.
+ */
+const SKIP = new Set(['node_modules', 'dist', '.angular', 'out-tsc', '.git', '.yalc', '.idea', '.vscode', 'coverage',
+  'tabbr.config.local.json']);
 
 /**
  * The workspace's source files, as the module store builds them: the files git tracks (plus new ones git doesn't ignore)