wizz-method 2.0.0 → 2.1.1

package/tools/installer/modules/module-interface.js

@@ -0,0 +1,86 @@
+/**
+ * Versioned contract between the installer and a module's `module.yaml`
+ * (auditoria 2026-09-11, item 25 da Fase 4). Same principle as markitdown's
+ * `__plugin_interface_version__`: a plugin/module declares which shape of
+ * the host's contract it was written against, and the host refuses to load
+ * one that asks for more than it knows how to give.
+ *
+ * "Interface" here means the module.yaml format + on-disk layout the
+ * installer copies and resolves: which top-level keys it understands
+ * (`code`, `name`, `directories`, `wds_folders`, `skills`, `customize`,
+ * `_shared`, config-question objects with `prompt`/`default`/`scope`/
+ * `result`, etc.) and the assumptions `createModuleDirectories`,
+ * `copyModuleWithFiltering` and the config collector make about them. It is
+ * NOT the module's semantic version (`module_version`) — a module can bump
+ * its own version on every release while its interface_version stays at 1
+ * for years, as long as it keeps using only fields this installer already
+ * understands.
+ *
+ * `interface_version` is optional. A module.yaml with no such field is
+ * legacy: version 1, compatible with every module written before this
+ * contract existed (every upstream bmad-code-org module included). Only
+ * bump SUPPORTED_MODULE_INTERFACE_VERSION when the installer starts relying
+ * on something an old module.yaml genuinely cannot provide (a new required
+ * top-level shape, not just a new optional field it can ignore).
+ */
+
+const SUPPORTED_MODULE_INTERFACE_VERSION = 1;
+
+/**
+ * Parse `raw` as a positive integer (number or numeric string, no
+ * decimals). Returns null when `raw` isn't one.
+ * @param {*} raw
+ * @returns {number|null}
+ */
+function parsePositiveInteger(raw) {
+  let value;
+  if (typeof raw === 'number') {
+    value = raw;
+  } else if (typeof raw === 'string' && /^\d+$/.test(raw.trim())) {
+    value = Number(raw.trim());
+  } else {
+    return null;
+  }
+  return Number.isInteger(value) && value >= 1 ? value : null;
+}
+
+/**
+ * Check a parsed module.yaml against the installer's supported contract
+ * version. Throws a clear Error when the module declares a shape this
+ * installer cannot honor. Call this BEFORE writing anything for that module
+ * to disk (before `atomicModuleSwap`), so an incompatible module never
+ * partially lands in `_wizz/`.
+ * @param {Object|null|undefined} moduleYaml - Parsed module.yaml content (or
+ *   an object shaped `{ interface_version }` when only that field is known,
+ *   as with a PluginResolver ResolvedModule).
+ * @param {string} moduleName - Module code/name, used only in error text.
+ * @returns {void}
+ */
+function assertModuleInterfaceVersion(moduleYaml, moduleName) {
+  const raw = moduleYaml ? moduleYaml.interface_version : undefined;
+
+  // Missing field: legacy module, treated as interface_version 1. This is
+  // the compat path for every module.yaml that predates this contract.
+  if (raw === undefined || raw === null) {
+    return;
+  }
+
+  const version = parsePositiveInteger(raw);
+  if (version === null) {
+    throw new Error(
+      `Module '${moduleName}' declares an invalid interface_version (${JSON.stringify(raw)}). ` +
+        `interface_version must be a positive integer, such as 1.`,
+    );
+  }
+
+  if (version > SUPPORTED_MODULE_INTERFACE_VERSION) {
+    throw new Error(
+      `Module '${moduleName}' declares interface_version ${version}, but this installer only supports up to ` +
+        `interface_version ${SUPPORTED_MODULE_INTERFACE_VERSION}. Update wizz-method ` +
+        `(npm i -g wizz-method@latest) or use a version of the module compatible with ` +
+        `interface_version ${SUPPORTED_MODULE_INTERFACE_VERSION}.`,
+    );
+  }
+}
+
+module.exports = { SUPPORTED_MODULE_INTERFACE_VERSION, assertModuleInterfaceVersion };