@rpgm-tools/neo-angband-mod-sdk 1.3.0 → 1.9.0

package/src/manifest.ts

@@ -304,11 +304,16 @@ export const DEFAULT_PACK_GROUP = "content";
  * runtime grants only what a `shape: plugin` pack declares and the user
  * approves; content and tile packs request none. The vocabulary
  * ("command:add", "event:turn-start", "state:*.read", "network:<host>", ...)
- * is enforced by the capability model (P7 phase 5); the manifest only records
- * the request, so any string is accepted here.
+ * is enforced by parseCapability / CapabilitySet.fromManifest in
+ * capabilities.ts. The manifest records the request as strings; checkMod
+ * runs that same function, so an unrecognized capability is a check
+ * failure rather than a silent accept.
  */
 export type Capability = string;
 
+/** How code declared by a plugin-facet pack is executed. */
+export type PluginRuntime = "in-process" | "worker";
+
 /**
  * One graphics mode a `tiles`-facet pack contributes.
  *
@@ -479,6 +484,16 @@ export interface PackManifest {
    * exist yet.
    */
   modApi?: number;
+  /**
+   * The execution ABI selected by a code pack. API 1 keeps the historical
+   * in-process `plugin.js` entry; API 2 requires the isolated worker runtime.
+   */
+  runtime?: PluginRuntime;
+  /**
+   * The module imported by the host-owned API-2 Worker bootstrap. This is a
+   * mod-relative file, never a host module name or URL.
+   */
+  workerEntry?: string;
   /**
    * Player-toggleable flags this pack owns (see PackRule). The bundled qol /
    * bug-fixes mods use this to declare their fixes/tweaks for the in-app "Fixes
@@ -683,6 +698,32 @@ export function validateManifest(value: unknown): PackManifest {
       );
     }
   }
+  if (m["runtime"] !== undefined && m["runtime"] !== "in-process" && m["runtime"] !== "worker") {
+    throw new ManifestError(`manifest ${id}: runtime must be "in-process" or "worker"`);
+  }
+  if (m["workerEntry"] !== undefined) {
+    const entry = m["workerEntry"];
+    if (
+      typeof entry !== "string" ||
+      entry.length === 0 ||
+      entry.startsWith("/") ||
+      entry.includes("\\") ||
+      entry.split("/").some((part) => part === "" || part === "." || part === "..")
+    ) {
+      throw new ManifestError(`manifest ${id}: workerEntry must be a non-empty relative file path`);
+    }
+  }
+  if (m["modApi"] === 2) {
+    if (m["runtime"] !== "worker") {
+      throw new ManifestError(`manifest ${id}: modApi 2 requires runtime "worker"`);
+    }
+    if (typeof m["workerEntry"] !== "string") {
+      throw new ManifestError(`manifest ${id}: modApi 2 requires workerEntry`);
+    }
+  }
+  if (m["runtime"] === "worker" && m["modApi"] !== 2) {
+    throw new ManifestError(`manifest ${id}: runtime "worker" requires modApi 2`);
+  }
   if (
     m["nondeterministic"] !== undefined &&
     typeof m["nondeterministic"] !== "boolean"

package/src/standards.ts

@@ -15,10 +15,13 @@
  *     cannot describe a rule that is not enforced or omit one that is.
  *
  * WHAT IT DOES NOT DUPLICATE. Everything validateManifest already decides is
- * delegated to validateManifest. This module adds only the rules that need to see
- * something the manifest validator cannot: the FILE LIST. That is not a small
- * addition - two of the rules below are defects this project actually shipped, both
- * invisible to a validator with no files to look at:
+ * delegated to validateManifest. Capability grammar is the same: this module
+ * calls CapabilitySet.fromManifest rather than restating parseCapability's
+ * patterns. What it adds is the rules that need to see something those two
+ * cannot: the FILE LIST, and the join between a validated manifest and the
+ * capability model (validateManifest cannot import capabilities.ts without a
+ * cycle). Two of the file-list rules below are defects this project actually
+ * shipped, both invisible to a validator with no files to look at:
  *
  *   - `modApi` is documented as REQUIRED of any pack shipping plugin.js, and nothing
  *     enforced it, because validateManifest never sees whether plugin.js is there.
@@ -32,8 +35,9 @@
  * learn to ignore.
  */
 
-import { compareSemver, satisfies } from "./semver.js";
+import { CapabilitySet } from "./capabilities.js";
 import { ManifestError, hasFacet, validateManifest, type PackManifest } from "./manifest.js";
+import { compareSemver, satisfies } from "./semver.js";
 
 /** The file a mod's code lives in, when it has any. */
 export const PLUGIN_FILE = "plugin.js";
@@ -299,6 +303,38 @@ export const MOD_REQUIREMENTS: readonly Requirement[] = [
       }
     },
   },
+  {
+    id: "capabilities-recognized",
+    level: "required",
+    title: "Request only capabilities the game knows",
+    why:
+      "A capability string is the consent surface a player reads and the gate the " +
+      "runtime actually opens. An unrecognized string, or a capability on a pack " +
+      "that cannot execute, is refused when the game loads the plugin - after the " +
+      "player has already installed it. This check is CapabilitySet.fromManifest, " +
+      "the same function the loader calls, so a typo that used to pass here and " +
+      "fail there cannot.",
+    check: (mod) => {
+      const m = manifestObject(mod);
+      if (m === null) return null;
+      let manifest: PackManifest;
+      try {
+        /* validateManifest first, so this rule never re-describes the schema. A
+         * malformed capabilities field (not an array of strings) belongs to
+         * manifest-fields; this rule only speaks once there is a PackManifest
+         * to hand to the capability model. */
+        manifest = validateManifest(m);
+      } catch {
+        return null;
+      }
+      try {
+        CapabilitySet.fromManifest(manifest);
+        return null;
+      } catch (e) {
+        return e instanceof Error ? e.message : String(e);
+      }
+    },
+  },
   {
     id: "plugin-declares-modapi",
     level: "required",