@tabbr/module-cli 0.1.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,113 @@
+# @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`).

package/bin/tabbr-module.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getAccessToken } = require('../src/auth');
+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_KIND = 'HOOK'; // matches the server's own @RequestParam default for /meta/script
+
+function parseArgs(argv) {
+  const args = { cwd: process.cwd(), kind: DEFAULT_KIND };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = () => argv[++i];
+    switch (arg) {
+      case '--club': args.club = next(); break;
+      case '--module-id': args.moduleId = next(); break;
+      case '--exposed-module': args.exposedModule = next(); break;
+      case '--export-name': args.exportName = next(); break;
+      case '--icon': args.icon = next(); break;
+      case '--title': args.title = next(); break;
+      case '--cwd': args.cwd = path.resolve(next()); break;
+      case '--api-host': args.apiHost = next(); break;
+      case '--entity': args.entity = next(); break;
+      case '--kind': args.kind = next(); break;
+      case '--out': args.out = next(); break;
+      default:
+        throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+  return args;
+}
+
+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.
+
+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 publish [options]
+
+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
+  --exposed-module <./Foo>   Key in your federation.config.js "exposes" map
+  --export-name <Foo>        Named (or default) export implementing PlatformModuleImplementation
+
+Optional:
+  --icon <name>              Menu icon name
+  --title <text>             Display title
+  --cwd <path>                Angular workspace to build (default: current directory)
+  --api-host <url>           Tabbr API host (default: ${DEFAULT_API_HOST})
+
+Requires the tabbr Keycloak client's Valid Redirect URIs to include http://localhost:*
+(a Keycloak admin-console setting - see README.md).
+
+Usage: tabbr-module fetch-types [--club <CODE>] [--entity <name>] [options]
+
+With --entity: fetches the ambient .d.ts for that ONE entity's script sandbox - the same typings
+tabbr-ui's in-app script editor (Monaco) uses for hook/calculation/default-value/relevancy-condition
+scripts on that entity, globals (current/onCreate/...) included.
+
+Without --entity (default): fetches EVERY entity the club has as plain data interfaces in ONE
+combined file - no script globals, meant for general club-data typing in your own component code
+(not the script editor). See --out's default below.
+
+Required (command line or ${CONFIG_FILE}):
+  --club <CODE>              Club code whose entity metadata to fetch, e.g. ABC
+
+Optional:
+  --entity <name>              Entity's REST path segment, e.g. flight, member (default: every entity, combined)
+  --kind <KIND>               Only with --entity: one of ${VALID_KINDS.join(', ')} (default: ${DEFAULT_KIND})
+  --out <path>                Output file (default: src/types/tabbr/<entity>.<kind>.d.ts with --entity,
+                               src/types/tabbr/entities.d.ts without)
+  --cwd <path>                Workspace root, used to resolve the default --out (default: current directory)
+  --api-host <url>           Tabbr API host (default: ${DEFAULT_API_HOST})`);
+}
+
+function requireFlags(args, requiredFlags) {
+  for (const [key, flag] of Object.entries(requiredFlags)) {
+    if (!args[key]) {
+      console.error(`Missing required option: ${flag}\n`);
+      printUsage();
+      process.exit(1);
+    }
+  }
+}
+
+async function runPublish(args) {
+  args.club = requireClub(args.club);
+  requireFlags(args, {
+    moduleId: '--module-id',
+    exposedModule: '--exposed-module',
+    exportName: '--export-name',
+  });
+
+  const zipBuffer = await buildAndZip(args.cwd);
+  const accessToken = await getAccessToken();
+  const result = await publish({
+    apiHost: args.apiHost,
+    club: args.club,
+    moduleId: args.moduleId,
+    exposedModule: args.exposedModule,
+    exportName: args.exportName,
+    icon: args.icon,
+    title: args.title,
+    zipBuffer,
+    accessToken,
+  });
+
+  console.log('Published successfully. Registered modules for this club:');
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function fetchAndWriteOne({ apiHost, club, entity, kind, cwd, out, accessToken }) {
+  const dts = await fetchScriptTypes({ apiHost, club, entity, kind, accessToken });
+
+  const outPath = out
+    ? path.resolve(cwd, out)
+    : path.join(cwd, 'src', 'types', 'tabbr', `${entity}.${kind.toLowerCase()}.d.ts`);
+
+  const header = `// GENERATED by \`tabbr-module fetch-types\` - do not hand-edit, re-run to refresh.
+// Club: ${club.toUpperCase()} | Entity: ${entity} | Kind: ${kind} | Fetched: ${new Date().toISOString()}
+//
+// This is the SAME ambient .d.ts tabbr-ui's own script editor (Monaco, for club-configured
+// hook/calculation/default-value/relevancy-condition scripts) feeds itself via
+// GET /api/${entity}/meta/script?kind=${kind} - see ScriptTypeGenerator
+// (tabbr-api-server) and ScriptEditorMonacoService (tabbr-ui). It types the SCRIPT SANDBOX for
+// this club's actual entity/field configuration (including any custom/dynamic fields this club
+// has added), not necessarily the JSON shape returned by this club's REST API. It also declares
+// script-only globals (e.g. \`current\`/\`original\`, \`onCreate\`/\`onUpdate\`/\`onDelete\` for HOOK;
+// \`addErrorMessage\` etc. from the base script lib) that don't exist in a browser/component
+// context - harmless to leave declared, just ignore them.
+//
+// If you fetch types for more than one entity/kind, keep the resulting files in DIFFERENT
+// TypeScript projects (or otherwise out of the same tsconfig's "include") if you're not sure
+// they're compatible: globals like \`current\` are declared with a DIFFERENT type per kind/entity,
+// and TypeScript errors on incompatible duplicate ambient declarations if two such files are both
+// in scope at once. This is also why \`fetch-types\` with no --entity writes one file per entity
+// rather than one combined file.
+
+${dts}
+`;
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, header);
+  return outPath;
+}
+
+async function runFetchAllEntityTypes(args) {
+  const dts = await fetchAllEntityTypes({ apiHost: args.apiHost, club: args.club, accessToken: args.accessToken });
+
+  const outPath = args.out
+    ? path.resolve(args.cwd, args.out)
+    : path.join(args.cwd, 'src', 'types', 'tabbr', 'entities.d.ts');
+
+  const header = `// GENERATED by \`tabbr-module fetch-types\` - do not hand-edit, re-run to refresh.
+// Club: ${args.club.toUpperCase()} | Fetched: ${new Date().toISOString()}
+//
+// Every entity this club has (custom fields included), as plain data interfaces - see
+// ScriptTypeGenerator#generateAllEntityTypes (tabbr-api-server) and
+// GET /api/club/${args.club.toUpperCase()}/entities/types. Not the script-sandbox context
+// \`--entity <name>\` fetches (no current/onCreate/... globals here) - safe to use in your own
+// component code, e.g. to type an httpResource's response.
+
+${dts}
+`;
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, header);
+  console.log(`Wrote ${outPath}`);
+}
+
+async function runFetchTypes(args) {
+  args.club = requireClub(args.club);
+  if (args.kind !== DEFAULT_KIND && !args.entity) {
+    console.error('--kind only applies to a single --entity fetch (the combined file has no script sandbox, so no kind).\n');
+    printUsage();
+    process.exit(1);
+  }
+
+  const accessToken = await getAccessToken();
+
+  if (args.entity) {
+    const outPath = await fetchAndWriteOne({ ...args, accessToken });
+    console.log(`Wrote ${outPath}`);
+  } else {
+    await runFetchAllEntityTypes({ ...args, accessToken });
+  }
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+
+  if (command !== 'init' && command !== 'publish' && command !== 'fetch-types') {
+    printUsage();
+    process.exit(command ? 1 : 0);
+  }
+
+  const flags = parseArgs(rest);
+  if (command === 'init') {
+    await runInit(flags.cwd, flags);
+    return;
+  }
+  const args = { apiHost: DEFAULT_API_HOST, ...readConfig(flags.cwd), ...flags };
+  if (command === 'publish') {
+    await runPublish(args);
+  } else {
+    await runFetchTypes(args);
+  }
+}
+
+main().catch(err => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "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"
+  }
+}

package/src/auth.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const http = require('http');
+const os = require('os');
+const path = require('path');
+
+// Same Keycloak client the tabbr-ui shell and the SDK's dev bridge use - see
+// tabbr-ui/src/environments/environment.ts and tabbr-module-sdk/src/dev-bridge.
+const KEYCLOAK_URL = 'https://auth.tabbr.net';
+const KEYCLOAK_REALM = 'tabbr';
+const KEYCLOAK_CLIENT_ID = 'tabbr';
+
+const CREDENTIALS_PATH = path.join(os.homedir(), '.tabbr', 'credentials.json');
+
+function base64url(buffer) {
+  return buffer.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function readCachedCredentials() {
+  try {
+    return JSON.parse(fs.readFileSync(CREDENTIALS_PATH, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeCachedCredentials(creds) {
+  fs.mkdirSync(path.dirname(CREDENTIALS_PATH), { recursive: true });
+  fs.writeFileSync(CREDENTIALS_PATH, JSON.stringify(creds, null, 2), { mode: 0o600 });
+}
+
+async function exchangeToken(params) {
+  const response = await fetch(`${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(params).toString(),
+  });
+  if (!response.ok) {
+    throw new Error(`Token request failed: ${response.status} ${await response.text()}`);
+  }
+  return response.json();
+}
+
+function toCachedCredentials(tokenResponse) {
+  return {
+    accessToken: tokenResponse.access_token,
+    refreshToken: tokenResponse.refresh_token,
+    // A little slack so a token that's about to expire doesn't get used anyway.
+    expiresAt: Date.now() + (tokenResponse.expires_in - 30) * 1000,
+  };
+}
+
+async function refreshAccessToken(cached) {
+  const tokenResponse = await exchangeToken({
+    grant_type: 'refresh_token',
+    refresh_token: cached.refreshToken,
+    client_id: KEYCLOAK_CLIENT_ID,
+  });
+  return toCachedCredentials(tokenResponse);
+}
+
+/** Full-page-redirect + PKCE login via a temporary local HTTP server catching the callback. */
+async function interactiveLogin() {
+  const verifier = base64url(crypto.randomBytes(32));
+  const challenge = base64url(crypto.createHash('sha256').update(verifier).digest());
+
+  // Set once the server actually has a port (inside listen's callback) and reused below -
+  // server.address() returns null once server.close() has been called, so the request handler
+  // must not try to recompute it from the (by-then-closing) server itself.
+  let redirectUri;
+
+  const { code } = await new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, 'http://localhost');
+      if (url.pathname !== '/callback') {
+        res.writeHead(404).end();
+        return;
+      }
+      const code = url.searchParams.get('code');
+      const error = url.searchParams.get('error');
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(error
+        ? `<h1>Login failed</h1><p>${error}</p><p>You can close this tab.</p>`
+        : '<h1>Logged in</h1><p>You can close this tab and return to the terminal.</p>');
+      server.close();
+      if (error) {
+        reject(new Error(`Keycloak login failed: ${error}`));
+      } else {
+        resolve({ code });
+      }
+    });
+    server.listen(0, 'localhost', () => {
+      const port = server.address().port;
+      redirectUri = `http://localhost:${port}/callback`;
+      const authUrl = new URL(`${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/auth`);
+      authUrl.searchParams.set('client_id', KEYCLOAK_CLIENT_ID);
+      authUrl.searchParams.set('response_type', 'code');
+      authUrl.searchParams.set('scope', 'openid');
+      authUrl.searchParams.set('redirect_uri', redirectUri);
+      authUrl.searchParams.set('code_challenge', challenge);
+      authUrl.searchParams.set('code_challenge_method', 'S256');
+
+      console.log('Opening your browser to log in via Keycloak...');
+      console.log(`If it doesn't open automatically, visit:\n${authUrl.toString()}\n`);
+      import('open').then(({ default: open }) => open(authUrl.toString())).catch(() => {
+        // Non-fatal: the URL is already printed above for manual use.
+      });
+    });
+    server.on('error', reject);
+  });
+
+  const tokenResponse = await exchangeToken({
+    grant_type: 'authorization_code',
+    code,
+    redirect_uri: redirectUri,
+    client_id: KEYCLOAK_CLIENT_ID,
+    code_verifier: verifier,
+  });
+  return toCachedCredentials(tokenResponse);
+}
+
+/** Returns a valid access token, reusing/refreshing the cache before falling back to a fresh login. */
+async function getAccessToken() {
+  const cached = readCachedCredentials();
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.accessToken;
+  }
+  if (cached && cached.refreshToken) {
+    try {
+      const refreshed = await refreshAccessToken(cached);
+      writeCachedCredentials(refreshed);
+      return refreshed.accessToken;
+    } catch {
+      // Refresh token expired/revoked - fall through to interactive login.
+    }
+  }
+  const creds = await interactiveLogin();
+  writeCachedCredentials(creds);
+  return creds.accessToken;
+}
+
+module.exports = { getAccessToken, CREDENTIALS_PATH };

package/src/build.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const archiver = require('archiver');
+
+/** Reads angular.json and resolves the browser output directory for the workspace's one project. */
+function resolveOutputDir(cwd) {
+  const angularJsonPath = path.join(cwd, 'angular.json');
+  if (!fs.existsSync(angularJsonPath)) {
+    throw new Error(`No angular.json found in ${cwd} - run this from an Angular workspace root (or pass --cwd).`);
+  }
+  const angularJson = JSON.parse(fs.readFileSync(angularJsonPath, 'utf-8'));
+  const projectName = Object.keys(angularJson.projects)[0];
+  const project = angularJson.projects[projectName];
+  // native-federation's build target wraps the real Angular application builder under
+  // "build-original" (see tabbr-ui/angular.json and tabbr-custom-module-poc/angular.json) -
+  // that's where the actual outputPath lives.
+  const buildTarget = project.architect['build-original'] || project.architect['build'];
+  const outputPath = buildTarget.options.outputPath;
+  const base = typeof outputPath === 'string' ? outputPath : outputPath.base;
+  // Angular's application builder always nests the actual browser bundle under a "browser/"
+  // subfolder of outputPath - confirmed empirically against this exact builder this session.
+  return path.join(cwd, base, 'browser');
+}
+
+/**
+ * Runs `ng build` in `cwd` by invoking the workspace's own locally-installed Angular CLI entry
+ * point directly with the current Node binary.
+ *
+ * Deliberately NOT `execFileSync('npx', ['ng', 'build'], { shell: true })`, which was the previous
+ * implementation and had three problems at once:
+ *   - Node's DEP0190 deprecation warning (passing an args array together with `shell: true`).
+ *   - Passing args through a shell at all means they're re-parsed by the shell, so anything less
+ *     trusted than a hardcoded literal would need manual escaping.
+ *   - On Windows `npx` is `npx.cmd`, and since the CVE-2024-27980 fix Node refuses to spawn
+ *     `.cmd`/`.bat` WITHOUT `shell: true` - so dropping the shell alone wasn't an option there.
+ * Going straight to `node node_modules/@angular/cli/bin/ng.js` sidesteps all three: no shell, no
+ * args re-parsing, no platform-specific launcher script, and it's faster (skips npx resolution).
+ *
+ * Explicitly `--configuration production`, not a bare `ng build`: a module workspace's
+ * angular.json typically sets `defaultConfiguration: "development"` on the native-federation
+ * build target (so a plain `ng build`/`ng serve` during local development doesn't need the flag
+ * spelled out every time) - which a bare `ng build` here would silently inherit, publishing an
+ * unoptimized dev build (unminified, `dev: true`, native-federation's build-notifications
+ * live-reload hook baked in) to the club instead of the production one. The live-reload hook in
+ * particular then 404s at runtime (it points at a dev server that doesn't exist once statically
+ * published) and the unshared-per-pass token identities a dev build produces differently from
+ * prod have caused real `NG0201: No provider found for ...` failures in published modules.
+ */
+function runNgBuild(cwd) {
+  const ngJs = path.join(cwd, 'node_modules', '@angular', 'cli', 'bin', 'ng.js');
+  if (!fs.existsSync(ngJs)) {
+    throw new Error(
+      `No local Angular CLI found at ${ngJs} - run "npm install" in ${cwd} first.`
+    );
+  }
+  console.log(`Building in ${cwd} ...`);
+  execFileSync(process.execPath, [ngJs, 'build', '--configuration', 'production'], { cwd, stdio: 'inherit' });
+}
+
+/** Zips outputDir's contents flat (remoteEntry.json at the zip root) into a Buffer. */
+function zipDirectory(outputDir) {
+  return new Promise((resolve, reject) => {
+    const archive = archiver('zip', { zlib: { level: 9 } });
+    const chunks = [];
+    archive.on('data', chunk => chunks.push(chunk));
+    archive.on('end', () => resolve(Buffer.concat(chunks)));
+    archive.on('error', reject);
+    archive.directory(outputDir, false);
+    archive.finalize();
+  });
+}
+
+/** Builds the workspace at `cwd`, verifies remoteEntry.json exists, and returns a zip Buffer. */
+async function buildAndZip(cwd) {
+  runNgBuild(cwd);
+  const outputDir = resolveOutputDir(cwd);
+  const remoteEntryPath = path.join(outputDir, 'remoteEntry.json');
+  if (!fs.existsSync(remoteEntryPath)) {
+    throw new Error(
+      `Build output at ${outputDir} has no remoteEntry.json. ` +
+      `Is this workspace's federation.config.js missing an "exposes" entry?`
+    );
+  }
+  console.log(`Zipping ${outputDir} ...`);
+  return zipDirectory(outputDir);
+}
+
+module.exports = { buildAndZip, resolveOutputDir };

package/src/config.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline/promises');
+
+const CONFIG_FILE = 'tabbr.config.json';
+const DEFAULT_API_HOST = 'https://api.tabbr.be';
+
+/**
+ * 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,
+ * so they can't drift apart. Returns {} when there is no such file.
+ */
+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}`);
+  }
+}
+
+/** 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}).`);
+  }
+  return club.toUpperCase();
+}
+
+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);
+  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;
+  };
+
+  try {
+    const club = (overrides.club || await ask('Club code (the part before .tabbr.be, e.g. abc)', current.club))?.toUpperCase();
+    if (!club) throw new Error('A club code is required.');
+    const name = slug(path.basename(cwd)) || 'my-module';
+    const moduleId = overrides.moduleId
+      || await ask('Module id (unique within the club)', current.moduleId || `club.${club.toLowerCase()}.${name}`);
+    const title = overrides.title || await ask('Menu title', current.title || 'My module');
+
+    const config = {
+      ...current,
+      club,
+      apiHost: overrides.apiHost || current.apiHost || DEFAULT_API_HOST,
+      moduleId,
+      title,
+      exposedModule: current.exposedModule || './Module',
+      exportName: current.exportName || 'Module',
+    };
+    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();
+  }
+}
+
+module.exports = { CONFIG_FILE, DEFAULT_API_HOST, readConfig, requireClub, runInit };

package/src/fetch-types.js

@@ -0,0 +1,49 @@
+'use strict';
+
+// Mirrors ScriptTypeGenerator.ScriptKind (tabbr-api-server) - keep in sync if that enum changes.
+const VALID_KINDS = ['HOOK', 'CALCULATION', 'DEFAULT_CALCULATION', 'RELEVANT_CONDITION'];
+
+/**
+ * Fetches the ambient .d.ts tabbr-ui's own script editor (Monaco, for club-configured hook/
+ * calculation/default-value/relevancy-condition scripts) feeds itself, for a given club/entity/
+ * kind - see ScriptTypeGenerator (tabbr-api-server) and ScriptEditorMonacoService (tabbr-ui).
+ */
+async function fetchScriptTypes({ apiHost, club, entity, kind, accessToken }) {
+  if (!VALID_KINDS.includes(kind)) {
+    throw new Error(`Invalid --kind "${kind}". Must be one of: ${VALID_KINDS.join(', ')}`);
+  }
+
+  const url = `${apiHost}/api/${entity}/meta/script?kind=${kind}`;
+  console.log(`Fetching script types for entity "${entity}" (kind ${kind}) from ${url} ...`);
+  const response = await fetch(url, {
+    // X-club is required: CurrentClubFilter (tabbr-api-server) resolves the "current club" for
+    // this request from this header, not from any path variable - same pattern as publish.js.
+    headers: { Authorization: `Bearer ${accessToken}`, 'X-club': club.toUpperCase() },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Fetching script types failed: ${response.status} ${await response.text()}`);
+  }
+  return response.text();
+}
+
+/**
+ * Every entity this club has, as plain TypeScript data interfaces in ONE combined file - no
+ * script-sandbox globals, so (unlike fetchScriptTypes) safe to fetch for every entity at once and
+ * write to a single .d.ts. See ScriptTypeGenerator#generateAllEntityTypes (tabbr-api-server) for
+ * why. For general club-data typing in module component code, not the script editor.
+ */
+async function fetchAllEntityTypes({ apiHost, club, accessToken }) {
+  const url = `${apiHost}/api/club/${club.toUpperCase()}/entities/types`;
+  console.log(`Fetching all entity types for club ${club.toUpperCase()} from ${url} ...`);
+  const response = await fetch(url, {
+    headers: { Authorization: `Bearer ${accessToken}`, 'X-club': club.toUpperCase() },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Fetching entity types failed: ${response.status} ${await response.text()}`);
+  }
+  return response.text();
+}
+
+module.exports = { fetchScriptTypes, fetchAllEntityTypes, VALID_KINDS };

package/src/publish.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/** Uploads the zipped module build to the tabbr backend and returns the parsed JSON response. */
+async function publish({ apiHost, club, moduleId, exposedModule, exportName, icon, title, zipBuffer, accessToken }) {
+  const form = new FormData();
+  form.append('file', new Blob([zipBuffer], { type: 'application/zip' }), 'module.zip');
+  form.append('moduleId', moduleId);
+  form.append('exposedModule', exposedModule);
+  form.append('exportName', exportName);
+  if (icon) form.append('icon', icon);
+  if (title) form.append('title', title);
+
+  const url = `${apiHost}/api/custommodule`;
+  console.log(`Publishing ${moduleId} to club ${club.toUpperCase()} at ${url} ...`);
+  const response = await fetch(url, {
+    method: 'POST',
+    // X-club selects the club: the server publishes into the club CurrentClubFilter
+    // (tabbr-api-server) resolves from this header, the same club its ADMIN check runs against.
+    headers: { Authorization: `Bearer ${accessToken}`, 'X-club': club.toUpperCase() },
+    body: form,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Publish failed: ${response.status} ${await response.text()}`);
+  }
+  return response.json();
+}
+
+module.exports = { publish };