@tabbr/module-cli 0.3.0 → 0.4.0

package/README.md

@@ -129,6 +129,23 @@ for a module that has no backend code (then only the entities are published). Th
 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.
 
+## Contracts
+
+What a module uses of Tabbr (or, later, of another module) is a **contract** - never its code. Declare the ones you use
+with a version range, and the module API level that has contracts:
+
+```json
+{
+  "engines": { "tabbr": "^1.1" },
+  "uses": { "sys.access": "^1" }
+}
+```
+
+`publish` puts `uses` in the manifest (also for a module without backend code); Tabbr only installs the module where
+the club has those contracts, and its server-side part gets them as `tabbr.uses['sys.access']`. The frontend gets a
+contract with the SDK's `MODULE_CONTRACTS` (`await inject(MODULE_CONTRACTS).get('sys.access')`). Their types come from
+`fetch-types --contracts` (below). See `docs/module-contracts.md` in the Tabbr repository.
+
 ## Usage: publish
 
 ```
@@ -239,6 +256,15 @@ Fetched files reflect one specific club's live, possibly-custom field configurat
 custom entities, ...) and are regenerable on demand - add `src/types/tabbr/` (or wherever `--out`
 points) to your workspace's `.gitignore` rather than committing them.
 
+```
+npx tabbr-module fetch-types --contracts [--cwd .] [--api-host https://api.tabbr.be]
+```
+
+**With `--contracts`**: fetches `GET /api/contracts/{name}/types` for every contract in `uses` into
+`contracts/<name>.d.ts`. Unlike the entity types these don't depend on a club - **commit them**: the store builds your
+module with them. Add `contracts/*.d.ts` to your tsconfig(s); it types `MODULE_CONTRACTS.get(name)` and
+`tabbr.uses[name]`, and its own types can be imported from `@tabbr/contracts/<name>`.
+
 ## Prerequisite: Keycloak redirect URI
 
 Login opens your browser to Keycloak and catches the redirect on a temporary local HTTP server

package/bin/tabbr-module.js

@@ -7,7 +7,8 @@ const { getAccessToken } = require('../src/auth');
 const { buildAndZip } = require('../src/build');
 const { publish, publishToStore, submitSourceToStore, storeMeta } = require('../src/publish');
 const { packSource } = require('../src/source');
-const { fetchScriptTypes, fetchAllEntityTypes, VALID_KINDS } = require('../src/fetch-types');
+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 { DEFAULT_LOCAL_API_HOST, trustLocalCertificateOrRespawn } = require('../src/local');
 const DEFAULT_KIND = 'HOOK'; // matches the server's own @RequestParam default for /meta/script
@@ -30,6 +31,7 @@ function parseArgs(argv) {
       case '--entity': args.entity = next(); break;
       case '--kind': args.kind = next(); break;
       case '--out': args.out = next(); break;
+      case '--contracts': args.contracts = true; break;
       case '--store': args.store = true; break;
       case '--prebuilt': args.prebuilt = true; break;
       case '--changelog': args.changelog = next(); break;
@@ -102,6 +104,13 @@ Usage: tabbr-module build --out <module.zip> [--cwd <path>]
 Builds the module (frontend and/or backend part, as publish does) into a zip without
 publishing it - what the store's builder runs.
 
+Usage: tabbr-module fetch-types --contracts [--cwd <path>] [--api-host <url>]
+
+Fetches the contracts the module uses ("uses" in ${CONFIG_FILE}, e.g. { "sys.access": "^1" }) into
+contracts/<name>.d.ts - commit them: the store builds your module with them. Include contracts/ in your
+tsconfig(s); then MODULE_CONTRACTS.get('<name>') (frontend) and tabbr.uses['<name>'] (backend) are typed,
+and the contract's own types can be imported from '@tabbr/contracts/<name>'. No --club needed.
+
 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
@@ -251,7 +260,28 @@ ${dts}
   console.log(`Wrote ${outPath}`);
 }
 
+/** One file per contract the module uses: contracts/<name>.d.ts. */
+async function runFetchContractTypes(args) {
+  const names = Object.keys(usesOf(args));
+  if (names.length === 0) {
+    throw new Error(`No contracts to fetch: add "uses" to ${CONFIG_FILE}, e.g. "uses": { "sys.access": "^1" }.`);
+  }
+  const accessToken = await getAccessToken();
+  const dir = path.join(args.cwd, 'contracts');
+  fs.mkdirSync(dir, { recursive: true });
+  for (const name of names) {
+    const dts = await fetchContractTypes({ apiHost: args.apiHost, name, accessToken });
+    const outPath = path.join(dir, `${name}.d.ts`);
+    fs.writeFileSync(outPath, dts);
+    console.log(`Wrote ${outPath} (${args.uses[name]})`);
+  }
+}
+
 async function runFetchTypes(args) {
+  if (args.contracts) {
+    await runFetchContractTypes(args);
+    return;
+  }
   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');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tabbr/module-cli",
-  "version": "0.3.0",
+  "version": "0.4.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,27 @@ function entitiesOf(config) {
   return entities;
 }
 
+/**
+ * The contracts the module uses (`"uses"` in tabbr.config.json, e.g. `{ "sys.access": "^1" }`): their names and version
+ * ranges, checked just enough to fail here - Tabbr checks them again (a contract it doesn't have, a range it can't
+ * satisfy) when the module is published or installed.
+ */
+function usesOf(config) {
+  const uses = config.uses || {};
+  if (typeof uses !== 'object' || Array.isArray(uses)) {
+    throw new Error('"uses" in tabbr.config.json must be an object: { "<contract>": "<version range>" }, e.g. { "sys.access": "^1" }.');
+  }
+  for (const [name, range] of Object.entries(uses)) {
+    if (!/^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/.test(name)) {
+      throw new Error(`"uses": "${name}" is not a contract name (e.g. "sys.access").`);
+    }
+    if (typeof range !== 'string' || !range.trim()) {
+      throw new Error(`"uses": "${name}" needs a version range, e.g. "^1".`);
+    }
+  }
+  return uses;
+}
+
 /**
  * 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,
@@ -54,16 +75,18 @@ function entitiesOf(config) {
  * `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).
+ * and the contracts it uses - 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.
+ * Returns `null` when the workspace has no backend part, no entities and uses 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 uses = usesOf(config);
   const bundleJs = backendConfig ? await bundle(cwd, backendConfig) : null;
-  if (bundleJs == null && entities.length === 0) {
+  if (bundleJs == null && entities.length === 0 && Object.keys(uses).length === 0) {
     return null;
   }
   const settings = backendConfig || {};
@@ -75,6 +98,8 @@ async function buildBackend(cwd, config) {
     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 contracts it uses - for its frontend part as well, so the manifest is written for a frontend-only module too
+    uses,
   };
 
   return { bundleJs, manifestJson: JSON.stringify(manifest, null, 2) };
@@ -120,4 +145,4 @@ async function bundle(cwd, backendConfig) {
   return result.outputFiles[0].text;
 }
 
-module.exports = { buildBackend, entitiesOf, DEFAULT_ENTRY };
+module.exports = { buildBackend, entitiesOf, usesOf, DEFAULT_ENTRY };

package/src/fetch-types.js

@@ -46,4 +46,19 @@ async function fetchAllEntityTypes({ apiHost, club, accessToken }) {
   return response.text();
 }
 
-module.exports = { fetchScriptTypes, fetchAllEntityTypes, VALID_KINDS };
+/**
+ * A contract a module uses (`"uses"` in tabbr.config.json), as Tabbr serves it: its types as the module
+ * `@tabbr/contracts/<name>`, plus its entries in `TabbrUiContracts` (what `MODULE_CONTRACTS.get(name)` returns) and
+ * `TabbrContracts` (`tabbr.uses[name]` server-side). See docs/module-contracts.md (tabbr repo).
+ */
+async function fetchContractTypes({ apiHost, name, accessToken }) {
+  const url = `${apiHost}/api/contracts/${encodeURIComponent(name)}/types`;
+  console.log(`Fetching the contract ${name} from ${url} ...`);
+  const response = await fetch(url, { headers: { Authorization: `Bearer ${accessToken}` } });
+  if (!response.ok) {
+    throw new Error(`Fetching the contract ${name} failed: ${response.status} ${await response.text()}`);
+  }
+  return response.text();
+}
+
+module.exports = { fetchScriptTypes, fetchAllEntityTypes, fetchContractTypes, VALID_KINDS };