@tabbr/module-cli 0.1.0 → 0.3.0

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.3.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"
+  }
+}

package/src/auth.js

@@ -1,144 +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 };
+'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/backend-build.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_ENTRY = 'backend/src/index.ts';
+
+/** Matches BackendModuleRuntimeService's MODULE_GLOBAL on the server - a `export function foo() {}`
+ * in the module's TS ends up reachable as the global `__module.foo` once bundled this way. */
+const GLOBAL_NAME = '__module';
+
+/**
+ * The entities the module declares (`"entities"` in tabbr.config.json), checked just enough to fail here rather than at
+ * upload with a vaguer message: Tabbr validates them again against the club (names taken, entity fields pointing at
+ * entities the club has, ...). See `ModuleEntityDefinition` in tabbr-api-server for the full shape.
+ */
+function entitiesOf(config) {
+  const entities = config.entities || [];
+  if (!Array.isArray(entities)) {
+    throw new Error('"entities" in tabbr.config.json must be an array.');
+  }
+  for (const entity of entities) {
+    if (!entity || !/^[a-z][a-zA-Z0-9]{1,39}$/.test(entity.name || '')) {
+      throw new Error(`Entity name "${entity && entity.name}" is not valid: camelCase letters and digits, starting lowercase.`);
+    }
+    if (!Array.isArray(entity.fields) || entity.fields.length === 0) {
+      throw new Error(`Entity "${entity.name}" declares no fields.`);
+    }
+    const keys = new Set();
+    for (const field of entity.fields) {
+      if (!/^[a-z][a-zA-Z0-9]{0,39}$/.test(field.key || '')) {
+        throw new Error(`Entity "${entity.name}": field key "${field.key}" is not valid.`);
+      }
+      if (keys.has(field.key)) {
+        throw new Error(`Entity "${entity.name}": field "${field.key}" is declared twice.`);
+      }
+      keys.add(field.key);
+      if (!field.type && !field.persistentType) {
+        throw new Error(`Entity "${entity.name}": field "${field.key}" has no type (e.g. "tabbr.text").`);
+      }
+      if (field.type === 'tabbr.entity' && !field.target) {
+        throw new Error(`Entity "${entity.name}": entity field "${field.key}" has no "target".`);
+      }
+    }
+  }
+  return entities;
+}
+
+/**
+ * Bundles a module workspace's backend part (if configured) into a single, dependency-free
+ * `bundle.js`, using esbuild so module authors can write normal TypeScript (types, imports,
+ * `export function`) even though nothing beyond that single file is ever loaded at runtime - the
+ * server evaluates it in a sandboxed GraalVM context with no module resolution of its own (see
+ * `BackendModuleRuntimeService`).
+ *
+ * Also writes the manifest the server reads (`manifest.json`): the backend config plus the entities the module declares
+ * - which a module can do without any backend code, so then only the manifest is produced (`bundleJs` null).
+ *
+ * Returns `null` when the workspace has neither a backend part nor entities, so `build.js` can skip
+ * it entirely for a frontend-only module.
+ */
+async function buildBackend(cwd, config) {
+  const backendConfig = config.backend;
+  const entities = entitiesOf(config);
+  const bundleJs = backendConfig ? await bundle(cwd, backendConfig) : null;
+  if (bundleJs == null && entities.length === 0) {
+    return null;
+  }
+  const settings = backendConfig || {};
+  const manifest = {
+    // localAllowedHosts (e.g. a mock on localhost) only ever go into a --local publish, never into one for a real environment.
+    allowedHosts: [...(settings.allowedHosts || []), ...(config.local ? settings.localAllowedHosts || [] : [])],
+    secretFieldNames: settings.secretFieldNames || [],
+    triggers: bundleJs == null ? [] : settings.triggers || [],
+    entities,
+    // the module gives persons roles (tabbr.access.setManagedRoles) - shown to the club when it installs the module
+    manageRoles: bundleJs != null && settings.manageRoles === true,
+  };
+
+  return { bundleJs, manifestJson: JSON.stringify(manifest, null, 2) };
+}
+
+/** 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;
+  const entryPath = path.join(cwd, entry);
+  if (!fs.existsSync(entryPath)) {
+    if (backendConfig.entry) {
+      // Explicitly configured but missing - fail loudly rather than silently skipping.
+      throw new Error(`Backend entry ${entryPath} does not exist (check "backend.entry" in tabbr.config.json).`);
+    }
+    return null;
+  }
+
+  let esbuild;
+  try {
+    // Resolved from the workspace being built, not from wherever this CLI happens to be installed -
+    // esbuild is the module author's devDependency, and the CLI may be hoisted, copied or linked.
+    esbuild = require(require.resolve('esbuild', { paths: [cwd] }));
+  } catch (err) {
+    throw new Error(
+      'esbuild is required to build this module\'s backend part. Run "npm install --save-dev esbuild" in your module workspace.'
+    );
+  }
+
+  console.log(`Building backend module ${entryPath} ...`);
+  const result = await esbuild.build({
+    entryPoints: [entryPath],
+    bundle: true,
+    write: false,
+    format: 'iife',
+    globalName: GLOBAL_NAME,
+    target: 'es2022',
+    platform: 'neutral',
+    logLevel: 'silent',
+  });
+  if (!result.outputFiles || result.outputFiles.length === 0) {
+    throw new Error(`esbuild produced no output for ${entryPath}`);
+  }
+  return result.outputFiles[0].text;
+}
+
+module.exports = { buildBackend, entitiesOf, DEFAULT_ENTRY };