@tabbr/module-cli 0.1.0 → 0.2.0

package/LICENSE

@@ -1,34 +1,34 @@
-Tabbr Module CLI License
-
-Copyright (c) 2026 SystemWorks BV. All rights reserved.
-
-1. Grant. Subject to the terms below, SystemWorks BV ("Licensor") grants you a
-   free, non-exclusive, non-transferable, revocable license to use, copy and
-   modify the Tabbr Module CLI (the "Software") solely to develop, test and
-   run modules that are deployed on and used with the Tabbr platform operated
-   by Licensor.
-
-2. Restrictions. You may not:
-   a. use the Software, or any part or derivative of it, for any purpose other
-      than the one in section 1, including with any platform, product or
-      service other than Tabbr;
-   b. distribute, sublicense, sell or publish the Software or derivatives of it,
-      except as part of a module distributed solely for use on the Tabbr
-      platform;
-   c. remove or alter this license or any copyright notice.
-
-3. Ownership. The Software is licensed, not sold. Licensor retains all rights,
-   title and interest in the Software. Modules you write remain yours, but this
-   license does not grant any right to the Tabbr platform itself, which is
-   governed by its own terms of use.
-
-4. Termination. This license ends automatically if you breach it, or when your
-   access to the Tabbr platform ends. On termination you must stop using the
-   Software.
-
-5. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
-   TO THE EXTENT PERMITTED BY LAW, LICENSOR IS NOT LIABLE FOR ANY DAMAGES
-   ARISING FROM THE USE OF THE SOFTWARE.
-
-6. Governing law. This license is governed by Belgian law. The courts of Ghent
-   (Gent), Belgium have exclusive jurisdiction.
+Tabbr Module CLI License
+
+Copyright (c) 2026 SystemWorks BV. All rights reserved.
+
+1. Grant. Subject to the terms below, SystemWorks BV ("Licensor") grants you a
+   free, non-exclusive, non-transferable, revocable license to use, copy and
+   modify the Tabbr Module CLI (the "Software") solely to develop, test and
+   run modules that are deployed on and used with the Tabbr platform operated
+   by Licensor.
+
+2. Restrictions. You may not:
+   a. use the Software, or any part or derivative of it, for any purpose other
+      than the one in section 1, including with any platform, product or
+      service other than Tabbr;
+   b. distribute, sublicense, sell or publish the Software or derivatives of it,
+      except as part of a module distributed solely for use on the Tabbr
+      platform;
+   c. remove or alter this license or any copyright notice.
+
+3. Ownership. The Software is licensed, not sold. Licensor retains all rights,
+   title and interest in the Software. Modules you write remain yours, but this
+   license does not grant any right to the Tabbr platform itself, which is
+   governed by its own terms of use.
+
+4. Termination. This license ends automatically if you breach it, or when your
+   access to the Tabbr platform ends. On termination you must stop using the
+   Software.
+
+5. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
+   TO THE EXTENT PERMITTED BY LAW, LICENSOR IS NOT LIABLE FOR ANY DAMAGES
+   ARISING FROM THE USE OF THE SOFTWARE.
+
+6. Governing law. This license is governed by Belgian law. The courts of Ghent
+   (Gent), Belgium have exclusive jurisdiction.

package/README.md

@@ -1,113 +1,193 @@
-# @tabbr/module-cli
-
-Builds a Native Federation club-module workspace and publishes it to a tabbr club. Also fetches
-a club's own generated TypeScript typings into your module workspace.
-
-The quickest start is the starter project,
-[systemworks-bv/tabbr-module-starter](https://github.com/systemworks-bv/tabbr-module-starter),
-which has this CLI and npm scripts for it set up already.
-
-```bash
-npm install -D @tabbr/module-cli
-```
-
-## Configuration: tabbr.config.json
-
-Every option can be passed on the command line, but normally lives in `tabbr.config.json` in the
-workspace root (option names in camelCase; command-line options win). `init` writes it for you:
-
-```bash
-npx tabbr-module init       # asks for the club code, module id and title
-```
-
-```json
-{
-  "club": "ABC",
-  "apiHost": "https://api.tabbr.be",
-  "moduleId": "club.abc.my-module",
-  "title": "My module",
-  "exposedModule": "./Module",
-  "exportName": "Module"
-}
-```
-
-## Usage: publish
-
-```
-npx tabbr-module publish [--club ABC] [--module-id club.abc.hello] \
-  [--exposed-module ./Module] [--export-name Module] \
-  [--icon waving_hand] [--title "Hello"] [--cwd .] [--api-host https://api.tabbr.be]
-```
-
-You need the ADMIN role in the club you publish to.
-
-`--cwd` defaults to the current directory; run the command from your module workspace's root
-(where its `angular.json`/`federation.config.js` live), or pass `--cwd` to point at it.
-
-### What it does
-
-1. Runs `ng build` in the target workspace.
-2. Locates the build output (via `angular.json`'s `build-original` target) and verifies
-   `remoteEntry.json` exists at its root.
-3. Zips the output.
-4. Logs you in via a browser redirect to Keycloak (PKCE, no password ever touches this CLI) and
-   caches the resulting token at `~/.tabbr/credentials.json` for reuse on later runs.
-5. Uploads the zip to `POST /api/custommodule` with the club in the `X-club` header, which hosts
-   the files and registers the module against that club. You need the ADMIN role in that club.
-
-## Usage: fetch-types
-
-```
-npx tabbr-module fetch-types [--club ABC] \
-  [--out src/types/tabbr/entities.d.ts] [--cwd .] [--api-host https://api.tabbr.be]
-```
-
-**Default (no `--entity`)**: fetches `GET /api/club/{club}/entities/types` - every entity this
-club has (custom fields included), as plain TypeScript data interfaces in ONE combined file
-(`src/types/tabbr/entities.d.ts` by default). No script-sandbox globals, so safe to have all of
-them in scope together - meant for typing your own component code (e.g. an `httpResource`'s
-response), not the script editor. This is the easy way to get everything at once.
-
-```
-npx tabbr-module fetch-types [--club ABC] --entity flight \
-  [--kind HOOK|CALCULATION|DEFAULT_CALCULATION|RELEVANT_CONDITION] \
-  [--out src/types/tabbr/flight.hook.d.ts] [--cwd .] [--api-host https://api.tabbr.be]
-```
-
-**With `--entity`**: fetches `GET /api/{entity}/meta/script?kind={kind}` instead - the same
-generated ambient `.d.ts` tabbr-ui's own script editor (Monaco) feeds itself for that entity's
-hook/calculation scripts. It types the script sandbox, not your REST responses, and declares
-script-only globals (`current`, `onCreate`, ...) that don't exist in a browser context - see the
-comment header the command writes atop the output file for the full explanation, and for why
-files fetched for different entities/kinds should generally not sit in the same TypeScript
-project as each other (or as the combined `entities.d.ts` above).
-
-Fetched files reflect one specific club's live, possibly-custom field configuration (field names,
-custom entities, ...) and are regenerable on demand - add `src/types/tabbr/` (or wherever `--out`
-points) to your workspace's `.gitignore` rather than committing them.
-
-## Prerequisite: Keycloak redirect URI
-
-Login opens your browser to Keycloak and catches the redirect on a temporary local HTTP server
-(an ephemeral `http://localhost:<port>/callback`). This requires `http://localhost:*` (or your
-chosen fixed port) to be added to the `tabbr` Keycloak client's **Valid Redirect URIs** in the
-Keycloak admin console - a one-time setup step, not something this CLI can configure itself.
-
-## Non-goals (v1)
-
-No `login`/`logout`/`whoami` subcommands, no multi-club profiles - `publish` covers the
-end-to-end flow on its own.
-
-## Releasing
-
-Commit your CLI changes first, then from this package:
-
-```bash
-npm run release -- patch --dry-run   # preview
-npm run release -- patch             # or minor / major / an explicit 0.3.0
-```
-
-Same flow as the SDK (see `tabbr-module-sdk/README.md`): the script bumps the version, commits,
-tags `cli-v<version>` and pushes; the tag triggers `.github/workflows/publish-module-cli.yml`,
-which publishes via npm Trusted Publishing (owner `systemworks-bv`, repository `gliderdesk`,
-workflow `publish-module-cli.yml`).
+# @tabbr/module-cli
+
+Builds a Native Federation club-module workspace and publishes it to a tabbr club. Also fetches
+a club's own generated TypeScript typings into your module workspace.
+
+The quickest start is the starter project,
+[systemworks-bv/tabbr-module-starter](https://github.com/systemworks-bv/tabbr-module-starter),
+which has this CLI and npm scripts for it set up already.
+
+```bash
+npm install -D @tabbr/module-cli
+```
+
+## Configuration: tabbr.config.json
+
+Every option can be passed on the command line, but normally lives in `tabbr.config.json` in the
+workspace root (option names in camelCase; command-line options win). `init` writes it for you:
+
+```bash
+npx tabbr-module init       # asks for the club code, module id and a fallback title
+```
+
+```json
+{
+  "club": "ABC",
+  "apiHost": "https://api.tabbr.be",
+  "moduleId": "club.abc.my-module",
+  "title": "My module",
+  "exposedModule": "./Module",
+  "exportName": "Module"
+}
+```
+
+### 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
+own modules: put `module.title` and `module.description` in your translation bundles (nested under your module id,
+e.g. `'module.title': 'My module'`) and list the bundles on your module class so the shell can read them:
+
+```ts
+export class Module extends SimpleModuleBase {
+  static readonly i18nBundles = I18N_BUNDLES;   // the same map you give provideModuleI18n()
+  // ...
+}
+```
+
+`title` in `tabbr.config.json` is then only the **fallback**: what is shown while there is no translation (a module
+without bundles, a language it lacks). `description` falls back to the module id.
+
+## Backend modules
+
+A module can also have a **backend** part: TypeScript that runs server-side (not in the browser),
+sandboxed, triggered on a cron schedule or on an entity's create/update - see
+`BackendModuleRuntimeService` in `tabbr-api-server`. Add a `"backend"` block to
+`tabbr.config.json`:
+
+```json
+{
+  "backend": {
+    "entry": "backend/src/index.ts",
+    "allowedHosts": ["admin.gliding.app"],
+    "localAllowedHosts": ["localhost"],
+    "secretFieldNames": ["apiKey"],
+    "triggers": [
+      { "type": "CRON", "name": "pollFlights", "cronExpression": "*/5 * * * *", "handler": "pollFlights" },
+      { "type": "ENTITY_HOOK", "name": "onFlightSaved", "entity": "flight", "event": "onUpdate", "handler": "onFlightSaved" }
+    ]
+  }
+}
+```
+
+`entry` (default `backend/src/index.ts`) is a normal TypeScript file exporting plain functions:
+
+```ts
+export function pollFlights() {
+  const result = http.fetchJson('https://admin.gliding.app/club/abc/api/flights.json', {
+    headers: { 'X-API-KEY': tabbr.settings.get('apiKey') },
+  });
+  // ...
+  tabbr.settings.set('lastPullAt', new Date().toISOString());
+}
+```
+
+- `http.fetchJson(url, options?)` - network access, restricted to `allowedHosts`. `localAllowedHosts` is added to that list
+  only by a `publish --local` (e.g. `localhost` for a mock of the external service you develop against) - never by a normal publish.
+- `tabbr.settings.get(key)` / `.set(key, value)` - this module's own per-club settings, including
+  its own secrets (never sent back to any settings GET response once saved - `secretFieldNames`).
+- `triggers[].type: "CRON"` runs on the given cron expression (server-local time), with no
+  triggering entity. `"ENTITY_HOOK"` runs on the named `entity`'s `event` (`onCreate`/`onUpdate`/
+  `onDelete`), with that entity bound under its own name (e.g. `flight`) in the handler's scope.
+- 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
+  addons) works at runtime.
+
+A "resync now" button (or similar) can fire a `CRON` trigger manually:
+`POST /api/custommodule/{moduleId}/trigger/{triggerName}` (ADMIN).
+
+## Usage: publish
+
+```
+npx tabbr-module publish [--club ABC] [--module-id club.abc.hello] \
+  [--exposed-module ./Module] [--export-name Module] \
+  [--icon waving_hand] [--title "Hello"]  # --title: fallback text, see above [--cwd .] [--api-host https://api.tabbr.be]
+```
+
+You need the ADMIN role in the club you publish to.
+
+`--cwd` defaults to the current directory; run the command from your module workspace's root
+(where its `angular.json`/`federation.config.js` live), or pass `--cwd` to point at it.
+
+### What it does
+
+Builds and publishes whichever parts are present - frontend, backend, or both - in one zip, one
+upload:
+
+1. If `angular.json` exists: runs `ng build`, locates the output (via `angular.json`'s
+   `build-original` target) and verifies `remoteEntry.json` exists at its root.
+2. If `"backend"` is set in `tabbr.config.json`: bundles the backend entry with `esbuild` into a
+   single `bundle.js`, and writes `manifest.json` alongside it from the `backend` config.
+3. Zips it all together - frontend files flat at the zip root (as before), backend files under a
+   `backend/` prefix.
+4. Logs you in via a browser redirect to Keycloak (PKCE, no password ever touches this CLI) and
+   caches the resulting token at `~/.tabbr/credentials.json` for reuse on later runs.
+5. Uploads the zip to `POST /api/custommodule` with the club in the `X-club` header, which hosts
+   the frontend files publicly, stores the backend files privately, and registers the module
+   against that club. You need the ADMIN role in that club.
+
+### Publishing to a local environment
+
+`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
+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.
+
+## Usage: fetch-types
+
+```
+npx tabbr-module fetch-types [--club ABC] \
+  [--out src/types/tabbr/entities.d.ts] [--cwd .] [--api-host https://api.tabbr.be]
+```
+
+**Default (no `--entity`)**: fetches `GET /api/club/{club}/entities/types` - every entity this
+club has (custom fields included), as plain TypeScript data interfaces in ONE combined file
+(`src/types/tabbr/entities.d.ts` by default). No script-sandbox globals, so safe to have all of
+them in scope together - meant for typing your own component code (e.g. an `httpResource`'s
+response), not the script editor. This is the easy way to get everything at once.
+
+```
+npx tabbr-module fetch-types [--club ABC] --entity flight \
+  [--kind HOOK|CALCULATION|DEFAULT_CALCULATION|RELEVANT_CONDITION] \
+  [--out src/types/tabbr/flight.hook.d.ts] [--cwd .] [--api-host https://api.tabbr.be]
+```
+
+**With `--entity`**: fetches `GET /api/{entity}/meta/script?kind={kind}` instead - the same
+generated ambient `.d.ts` tabbr-ui's own script editor (Monaco) feeds itself for that entity's
+hook/calculation scripts. It types the script sandbox, not your REST responses, and declares
+script-only globals (`current`, `onCreate`, ...) that don't exist in a browser context - see the
+comment header the command writes atop the output file for the full explanation, and for why
+files fetched for different entities/kinds should generally not sit in the same TypeScript
+project as each other (or as the combined `entities.d.ts` above).
+
+Fetched files reflect one specific club's live, possibly-custom field configuration (field names,
+custom entities, ...) and are regenerable on demand - add `src/types/tabbr/` (or wherever `--out`
+points) to your workspace's `.gitignore` rather than committing them.
+
+## Prerequisite: Keycloak redirect URI
+
+Login opens your browser to Keycloak and catches the redirect on a temporary local HTTP server
+(an ephemeral `http://localhost:<port>/callback`). This requires `http://localhost:*` (or your
+chosen fixed port) to be added to the `tabbr` Keycloak client's **Valid Redirect URIs** in the
+Keycloak admin console - a one-time setup step, not something this CLI can configure itself.
+
+## Non-goals (v1)
+
+No `login`/`logout`/`whoami` subcommands, no multi-club profiles - `publish` covers the
+end-to-end flow on its own.
+
+## Releasing
+
+Commit your CLI changes first, then from this package:
+
+```bash
+npm run release -- patch --dry-run   # preview
+npm run release -- patch             # or minor / major / an explicit 0.3.0
+```
+
+Same flow as the SDK (see `tabbr-module-sdk/README.md`): the script bumps the version, commits,
+tags `cli-v<version>` and pushes; the tag triggers `.github/workflows/publish-module-cli.yml`,
+which publishes via npm Trusted Publishing (owner `systemworks-bv`, repository `gliderdesk`,
+workflow `publish-module-cli.yml`).

package/bin/tabbr-module.js

@@ -8,6 +8,7 @@ const { buildAndZip } = require('../src/build');
 const { publish } = require('../src/publish');
 const { fetchScriptTypes, fetchAllEntityTypes, VALID_KINDS } = require('../src/fetch-types');
 const { CONFIG_FILE, DEFAULT_API_HOST, readConfig, 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
 
 function parseArgs(argv) {
@@ -24,6 +25,7 @@ function parseArgs(argv) {
       case '--title': args.title = next(); break;
       case '--cwd': args.cwd = path.resolve(next()); break;
       case '--api-host': args.apiHost = next(); break;
+      case '--local': args.local = true; break;
       case '--entity': args.entity = next(); break;
       case '--kind': args.kind = next(); break;
       case '--out': args.out = next(); break;
@@ -44,17 +46,36 @@ Asks for the club code (and module id / title) and writes ${CONFIG_FILE}.
 
 Usage: tabbr-module publish [options]
 
+Builds and publishes whichever parts of the workspace are present, in ONE upload: a frontend (an
+Angular project with a Native Federation "exposes" entry) and/or a backend (a "backend" block in
+${CONFIG_FILE} pointing at TypeScript run server-side - see README.md). At least one must be
+present.
+
 Required (command line or ${CONFIG_FILE}):
   --club <CODE>              Club code to publish to, e.g. ABC; you need the ADMIN role there
   --module-id <id>           Module id, unique within the club, e.g. club.abc.hello
+
+Required for a module with a frontend part:
   --exposed-module <./Foo>   Key in your federation.config.js "exposes" map
   --export-name <Foo>        Named (or default) export implementing PlatformModuleImplementation
 
+Backend part (all in ${CONFIG_FILE} under "backend", not as CLI flags):
+  entry                      TS entry point, default "backend/src/index.ts"
+  allowedHosts                External hosts your module's http.fetchJson() may reach
+  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}]
+
 Optional:
   --icon <name>              Menu icon name
-  --title <text>             Display title
-  --cwd <path>                Angular workspace to build (default: current directory)
+  --title <text>             Fallback title (module.title in your i18n bundle is what is shown)
+  --cwd <path>                Workspace to build (default: current directory)
   --api-host <url>           Tabbr API host (default: ${DEFAULT_API_HOST})
+  --local                    Publish to your own local backend (https://api.local.tabbr.be, i.e. the
+                              environment behind <club>.local.tabbr.be) instead of production;
+                              "localApiHost" in ${CONFIG_FILE} overrides the URL. Trusts your mkcert
+                              root CA automatically.
 
 Requires the tabbr Keycloak client's Valid Redirect URIs to include http://localhost:*
 (a Keycloak admin-console setting - see README.md).
@@ -95,11 +116,12 @@ async function runPublish(args) {
   args.club = requireClub(args.club);
   requireFlags(args, {
     moduleId: '--module-id',
-    exposedModule: '--exposed-module',
-    exportName: '--export-name',
   });
+  // exposedModule/exportName are only required for a module with a frontend part (an Angular
+  // project at --cwd); buildAndZip/the server reject a module with neither a frontend nor a
+  // backend part, so an all-blank publish still fails, just with a clearer error.
 
-  const zipBuffer = await buildAndZip(args.cwd);
+  const zipBuffer = await buildAndZip(args.cwd, args);
   const accessToken = await getAccessToken();
   const result = await publish({
     apiHost: args.apiHost,
@@ -208,6 +230,12 @@ async function main() {
     return;
   }
   const args = { apiHost: DEFAULT_API_HOST, ...readConfig(flags.cwd), ...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.
+    args.apiHost = args.localApiHost || DEFAULT_LOCAL_API_HOST;
+  }
+  trustLocalCertificateOrRespawn(args.apiHost);
   if (command === 'publish') {
     await runPublish(args);
   } else {
@@ -217,5 +245,12 @@ async function main() {
 
 main().catch(err => {
   console.error(err.message || err);
+  const code = String(err && err.cause && err.cause.code || '');
+  if (/CERT|SELF_SIGNED|UNABLE_TO_(GET|VERIFY)/.test(code)) {
+    console.error(
+      '\nThe server\'s TLS certificate is not trusted by Node. For a local environment (*.local.tabbr.be) run ' +
+      '"mkcert -install" and set NODE_EXTRA_CA_CERTS to the path of mkcert\'s rootCA.pem ("mkcert -CAROOT").'
+    );
+  }
   process.exit(1);
 });

package/package.json

@@ -1,33 +1,34 @@
-{
-  "name": "@tabbr/module-cli",
-  "version": "0.1.0",
-  "description": "Set up, build and publish a Native Federation club module to a tabbr club.",
-  "license": "SEE LICENSE IN LICENSE",
-  "author": "SystemWorks BV",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/systemworks-bv/gliderdesk.git",
-    "directory": "tabbr-module-cli"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "bin": {
-    "tabbr-module": "bin/tabbr-module.js"
-  },
-  "files": [
-    "bin",
-    "src"
-  ],
-  "scripts": {
-    "release": "node scripts/release.mjs"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "archiver": "^7.0.1",
-    "open": "^10.1.0"
-  }
-}
+{
+  "name": "@tabbr/module-cli",
+  "version": "0.2.0",
+  "description": "Set up, build and publish a Native Federation club module to a tabbr club.",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "SystemWorks BV",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/systemworks-bv/gliderdesk.git",
+    "directory": "tabbr-module-cli"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "tabbr-module": "bin/tabbr-module.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "release": "node scripts/release.mjs",
+    "publish:local": "yalc publish --push"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "archiver": "^7.0.1",
+    "open": "^10.1.0"
+  }
+}