@s2script/sdk 0.27.1 → 0.28.0

package/README.md

@@ -115,6 +115,57 @@ what lets a workspace hold a large first-party or in-house plugin suite that mus
 public registry — build it, drop the `.s2sp`s into your own server, never `s2s deploy` it. (`s2s
 deploy <dir>` on a single private plugin outside a workspace refuses the same way.)
 
+### Bundles
+
+A workspace whose plugins only make sense together (a game mode split into several plugins) can
+publish as one **bundle**: the registry lists it as a single entry, installs it with one command,
+and records which member versions each release pinned. Make the workspace root the bundle:
+
+```json
+{
+  "name": "@edge/jailbreak",
+  "version": "1.0.0",
+  "workspaces": ["plugins/*"],
+  "s2script": {
+    "kind": "bundle",
+    "workspace": { "plugins": ["plugins/*"] },
+    "bundle": { "optional": ["@edge/jailbreak-gangperks"] }
+  }
+}
+```
+
+- **Members** are the workspace's non-private plugins, and must share the bundle's scope. A bundle
+  has no code of its own, so the root has no `main` and must not be `private`.
+- **`s2s deploy`** at the root publishes the members first, each claiming the bundle, then the
+  bundle itself, pinning every member to the version just built. The plan shows it as the last row.
+  A bundle version already published with different member versions is refused before anything
+  uploads — bump it.
+- **`s2s version`** bumps the bundle whenever a member is released, by the largest member bump.
+- **`s2s install @edge/jailbreak`** installs the required members (and whatever they depend on);
+  `--with @edge/jailbreak-gangperks` adds an optional one. `s2s add` refuses a bundle: depend on a
+  member's interface instead.
+- A plugin already published **before** it joined a bundle must be republished at a new version
+  from the bundle's workspace, so that its registry entry carries the claim.
+
+The membership claim travels in the registry upload only — the `.s2sp` manifest the runtime loads
+is unchanged, and the runtime has no notion of bundles.
+
+## Publishing
+
+`s2s deploy` builds the package and publishes it to the registry. Its page on s2script.com
+is filled in from what you already keep beside your code:
+
+- **README:** `README.md` next to `package.json` (found the way npm finds one, up to 100,000
+  characters). Each deploy that carries one replaces the page's README.
+- **Source link:** package.json's standard `repository` field, in any npm form.
+  `{ "url": …, "directory": … }` links straight into a monorepo directory.
+- **Config:** the `s2script.config` block, shown as a table of options with their defaults.
+  Options marked `"sensitive": true` keep their default off the page.
+
+The README and `repository` travel with the deploy, not inside the `.s2sp`: the runtime never sees
+them. A deploy without them leaves what the page already shows, so a README or link set on the
+site stays until a deploy replaces it.
+
 ## Docs
 
 **[s2script.com/docs](https://s2script.com/docs)** — getting started, guides, and the full API

package/dist/cli.js

@@ -600,7 +600,7 @@ var require_inc = __commonJS({
   "../../node_modules/semver/functions/inc.js"(exports, module) {
     "use strict";
     var SemVer = require_semver();
-    var inc = (version, release, options, identifier, identifierBase) => {
+    var inc2 = (version, release, options, identifier, identifierBase) => {
       if (typeof options === "string") {
         identifierBase = identifier;
         identifier = options;
@@ -615,7 +615,7 @@ var require_inc = __commonJS({
         return null;
       }
     };
-    module.exports = inc;
+    module.exports = inc2;
   }
 });
 
@@ -1989,7 +1989,7 @@ var require_semver2 = __commonJS({
     var parse = require_parse();
     var valid2 = require_valid();
     var clean = require_clean();
-    var inc = require_inc();
+    var inc2 = require_inc();
     var diff = require_diff();
     var major2 = require_major();
     var minor = require_minor();
@@ -2028,7 +2028,7 @@ var require_semver2 = __commonJS({
       parse,
       valid: valid2,
       clean,
-      inc,
+      inc: inc2,
       diff,
       major: major2,
       minor,
@@ -6143,11 +6143,110 @@ function formatRangeViolations(violations) {
 ` + lines.join("\n");
 }
 
+// src/workspace/bundle.ts
+var MAX_BUNDLE_MEMBERS = 64;
+function isBundleWorkspace(ws) {
+  return ws.pkg.s2script?.kind === "bundle";
+}
+function scopeOf(name) {
+  if (!name.startsWith("@")) return null;
+  const slash = name.indexOf("/");
+  return slash > 1 ? name.slice(1, slash) : null;
+}
+function bundleProblems(ws) {
+  if (!isBundleWorkspace(ws)) return [];
+  const pkg = ws.pkg;
+  const problems = [];
+  const where2 = "package.json (workspace root)";
+  if (typeof pkg.name !== "string" || pkg.name === "") {
+    problems.push(`${where2}: a bundle needs a "name" \u2014 it is the bundle's registry name`);
+  }
+  if (typeof pkg.version !== "string" || pkg.version === "") {
+    problems.push(`${where2}: a bundle needs a "version"`);
+  }
+  if (pkg.private === true) {
+    problems.push(
+      `${where2}: s2script.kind is "bundle" but the root is "private": true \u2014 a private root is never published; remove "private" or drop the bundle kind`
+    );
+  }
+  if (pkg.main !== void 0 || pkg.s2script?.main !== void 0) {
+    problems.push(`${where2}: a bundle has no code of its own \u2014 remove "main"`);
+  }
+  const members = ws.plugins.filter((p) => !p.private);
+  if (members.length === 0) {
+    problems.push(`${where2}: a bundle needs at least one non-private plugin in s2script.workspace.plugins`);
+  }
+  if (members.length > MAX_BUNDLE_MEMBERS) {
+    problems.push(`${where2}: a bundle may have at most ${MAX_BUNDLE_MEMBERS} members (found ${members.length})`);
+  }
+  const bundleScope = typeof pkg.name === "string" ? scopeOf(pkg.name) : null;
+  for (const m of members) {
+    if (scopeOf(m.name) !== bundleScope) {
+      problems.push(
+        `${m.relDir}: ${m.name} cannot be a member of ${String(pkg.name)} \u2014 a bundle and its members must share a scope (the registry only accepts members with the same publisher)`
+      );
+    }
+  }
+  const raw = pkg.s2script?.bundle;
+  let optional = [];
+  if (raw !== void 0) {
+    const block2 = raw;
+    if (!block2 || typeof block2 !== "object" || Array.isArray(block2)) {
+      problems.push(`${where2}: s2script.bundle must be an object`);
+    } else if (block2.optional !== void 0) {
+      if (!Array.isArray(block2.optional) || block2.optional.some((o) => typeof o !== "string")) {
+        problems.push(`${where2}: s2script.bundle.optional must be an array of member names`);
+      } else {
+        optional = block2.optional;
+      }
+    }
+  }
+  const memberNames = new Set(members.map((m) => m.name));
+  for (const name of optional) {
+    if (!memberNames.has(name)) {
+      problems.push(
+        `${where2}: s2script.bundle.optional names ${JSON.stringify(name)}, which is not a non-private plugin of this workspace`
+      );
+    }
+  }
+  if (members.length > 0 && members.every((m) => optional.includes(m.name))) {
+    problems.push(`${where2}: every member is optional \u2014 a bundle needs at least one required member`);
+  }
+  return problems;
+}
+function readBundle(ws) {
+  if (!isBundleWorkspace(ws)) return null;
+  const optional = ws.pkg.s2script.bundle?.optional ?? [];
+  return {
+    name: ws.pkg.name,
+    version: ws.pkg.version,
+    members: ws.plugins.filter((p) => !p.private),
+    optional: new Set(optional)
+  };
+}
+function bundleMembers(bundle) {
+  const out = {};
+  for (const m of bundle.members) {
+    out[m.name] = bundle.optional.has(m.name) ? { version: m.version, optional: true } : { version: m.version };
+  }
+  return out;
+}
+function bundleManifest(bundle) {
+  return { id: bundle.name, version: bundle.version, kind: "bundle", members: bundleMembers(bundle) };
+}
+function sameMembers(a2, b) {
+  const ka = Object.keys(a2).sort();
+  const kb = Object.keys(b).sort();
+  if (ka.length !== kb.length || ka.some((k, i2) => k !== kb[i2])) return false;
+  return ka.every((k) => a2[k].version === b[k].version && !!a2[k].optional === !!b[k].optional);
+}
+
 // src/workspace/preflight.ts
 function preflightProblems(ws) {
   const problems = [...indexInterfaces(ws.plugins).problems];
   const violations = checkSiblingRanges(ws.plugins);
   if (violations.length > 0) problems.push(formatRangeViolations(violations));
+  problems.push(...bundleProblems(ws));
   return problems;
 }
 function preflightWorkspace(ws) {
@@ -7736,7 +7835,7 @@ async function runWorkspace(argv2, root, interactive, filters, stampVersion) {
 import { resolve as resolve15 } from "node:path";
 
 // src/registry/deploy.ts
-import { readFileSync as readFileSync13 } from "node:fs";
+import { readdirSync as readdirSync4, readFileSync as readFileSync13 } from "node:fs";
 import { resolve as resolve14 } from "node:path";
 
 // src/types-pack.ts
@@ -7969,6 +8068,9 @@ var RegistryClient = class {
     if (opts.types && opts.types.length) {
       entries["types.tgz"] = new Uint8Array(opts.types);
     }
+    if (opts.readme && opts.readme.trim()) {
+      entries["README.md"] = new TextEncoder().encode(opts.readme);
+    }
     const body = zipSync(entries, { level: 0 });
     const res = await this.request("deploy", `${this.baseUrl}/api/v1/deploy`, {
       method: "POST",
@@ -8005,10 +8107,12 @@ var RegistryClient = class {
     const res = await this.request("meta", u4);
     return this.json(res, "meta");
   }
-  async plan(name, range = "*") {
+  /** `withMembers`: optional members of a bundle root to install too (ignored for a plugin root). */
+  async plan(name, range = "*", withMembers) {
     const u4 = new URL(`${this.baseUrl}/api/v1/plan`);
     u4.searchParams.set("name", name);
     u4.searchParams.set("range", range);
+    if (withMembers && withMembers.length > 0) u4.searchParams.set("with", withMembers.join(","));
     const res = await this.request("plan", u4);
     return this.json(res, "plan");
   }
@@ -8029,6 +8133,23 @@ function assertDeployable(pkg, label) {
     );
   }
 }
+var MAX_README_CHARS = 1e5;
+function readPackageReadme(pluginDir) {
+  const names = readdirSync4(pluginDir).filter((n3) => /^readme(\.(md|markdown))?$/i.test(n3));
+  if (names.length === 0) return null;
+  const name = names.find((n3) => n3 === "README.md") ?? names.sort()[0];
+  const text3 = readFileSync13(resolve14(pluginDir, name), "utf8").trim();
+  if (!text3) return null;
+  if (text3.length > MAX_README_CHARS) {
+    throw new Error(
+      `${name} is ${text3.length.toLocaleString("en-US")} characters; the registry accepts at most ${MAX_README_CHARS.toLocaleString("en-US")}. Shorten it, or link to longer docs from it.`
+    );
+  }
+  return text3;
+}
+function withRegistryFields(manifest, pkg) {
+  return pkg.repository === void 0 ? manifest : { ...manifest, repository: pkg.repository };
+}
 function assembleDeployArchive(pluginDir, pkg, outPath) {
   const absDir = resolve14(pluginDir);
   if (packageKind(pkg) === "library") {
@@ -8038,7 +8159,13 @@ function assembleDeployArchive(pluginDir, pkg, outPath) {
       throw new Error(`built archive missing manifest.json: ${outPath}`);
     }
     const manifest2 = JSON.parse(Buffer.from(manifestEntry2).toString("utf8"));
-    return { manifest: manifest2, s2sp: null, lib, types: null };
+    return {
+      manifest: withRegistryFields(manifest2, pkg),
+      s2sp: null,
+      lib,
+      types: null,
+      readme: readPackageReadme(absDir)
+    };
   }
   const gate = assertPublishesTypes(pkg, absDir);
   if (!gate.ok) throw new Error(`publish gate failed: ${gate.error}`);
@@ -8057,7 +8184,13 @@ function assembleDeployArchive(pluginDir, pkg, outPath) {
       publishes: hasPublishes(manifest.publishes) ? manifest.publishes : void 0
     });
   }
-  return { manifest, s2sp, lib: null, types };
+  return {
+    manifest: withRegistryFields(manifest, pkg),
+    s2sp,
+    lib: null,
+    types,
+    readme: readPackageReadme(absDir)
+  };
 }
 async function deployPlugin(opts) {
   const absDir = resolve14(opts.dir);
@@ -8070,13 +8203,13 @@ async function deployPlugin(opts) {
     );
   }
   const outPath = packageKind(pkg) === "library" ? await buildLibrary(absDir, opts.packagesDir) : await buildPlugin(absDir, opts.packagesDir);
-  const { manifest, s2sp, lib, types } = assembleDeployArchive(absDir, pkg, outPath);
+  const archive = assembleDeployArchive(absDir, pkg, outPath);
   const client = new RegistryClient({
     baseUrl: opts.registryUrl || creds.registryUrl || defaultRegistryUrl(),
     token: creds.token,
     fetch: opts.fetch
   });
-  return client.deploy({ manifest, s2sp, lib, types });
+  return client.deploy(archive);
 }
 
 // src/workspace/deploy-all.ts
@@ -8134,7 +8267,7 @@ function formatPlan(plan) {
 function isDuplicateVersionRejection(e) {
   return e instanceof RegistryError && e.status === 409;
 }
-async function uploadPlan(plan, built, client) {
+async function uploadPlan(plan, built, client, opts = {}) {
   const results = [];
   for (const entry of plan) {
     if (entry.reason !== "PUBLISH") {
@@ -8149,6 +8282,7 @@ async function uploadPlan(plan, built, client) {
     }
     try {
       const archive = assembleDeployArchive(b.plugin.dir, b.plugin.pkg, b.outPath);
+      if (opts.bundle !== void 0) archive.manifest = { ...archive.manifest, bundle: opts.bundle };
       const res = await client.deploy(archive);
       results.push({ plugin: entry.plugin, status: "published", detail: res.reviewState });
     } catch (e) {
@@ -8165,6 +8299,51 @@ async function uploadPlan(plan, built, client) {
   }
   return results;
 }
+async function publishedMembers(client, name, version) {
+  let meta;
+  try {
+    meta = await client.meta(name);
+  } catch {
+    return null;
+  }
+  const versions = meta.versions ?? [];
+  const hit = versions.find((v) => v.version === version);
+  return hit ? hit.members ?? {} : null;
+}
+async function planBundle(bundle, client) {
+  const manifest = bundleManifest(bundle);
+  const published = await publishedMembers(client, bundle.name, bundle.version);
+  if (published === null) return { bundle, reason: "PUBLISH", manifest };
+  if (!sameMembers(published, bundleMembers(bundle))) {
+    throw new Error(
+      `bundle ${bundle.name}@${bundle.version} is already published with different members \u2014 bump the bundle's version (\`s2s version\` does this when a member changes) and deploy again`
+    );
+  }
+  return { bundle, reason: "skip (already published)", manifest };
+}
+function formatBundlePlan(entry) {
+  const count = entry.bundle.members.length;
+  return `    ${entry.bundle.name} ${entry.bundle.version}   ${entry.reason} (bundle of ${count} plugin${count === 1 ? "" : "s"})`;
+}
+async function uploadBundle(entry, memberResults, client) {
+  if (entry.reason !== "PUBLISH") return { bundle: entry.bundle, status: "skipped", detail: entry.reason };
+  if (memberResults.some((r2) => r2.status === "failed")) {
+    return { bundle: entry.bundle, status: "skipped", detail: "a member failed to publish" };
+  }
+  try {
+    const res = await client.deploy({ manifest: entry.manifest });
+    return { bundle: entry.bundle, status: "published", detail: res.reviewState };
+  } catch (e) {
+    if (isDuplicateVersionRejection(e)) {
+      return {
+        bundle: entry.bundle,
+        status: "skipped",
+        detail: "skip (already published; its members were not verified)"
+      };
+    }
+    return { bundle: entry.bundle, status: "failed", detail: e instanceof Error ? e.message : String(e) };
+  }
+}
 
 // src/commands/deploy.ts
 async function run2(argv2) {
@@ -8259,18 +8438,23 @@ async function runWorkspaceDeploy(opts) {
   }
   const { ordered, built, unpublishableLibraries } = builtPluginsFromOutcomes(ws, build3.outcomes);
   const plan = await computePlan(ordered, (name, version) => isAlreadyPublished(client, name, version));
+  const bundle = readBundle(ws);
+  const bundleEntry = bundle ? await planBundle(bundle, client) : null;
   label("plan:");
   console.log(formatPlan(plan));
+  if (bundleEntry) console.log(formatBundlePlan(bundleEntry));
   if (unpublishableLibraries.length > 0) {
     console.log(formatUnpublishableLibraries(unpublishableLibraries));
   }
-  const toPublish = publishCount(plan);
+  const bundlePublishes = bundleEntry?.reason === "PUBLISH" ? 1 : 0;
+  const toPublish = publishCount(plan) + bundlePublishes;
+  const noun = (n3) => `${n3} package${n3 === 1 ? "" : "s"}`;
   if (toPublish === 0) {
     label("nothing to publish");
     return;
   }
   if (dryRun) {
-    label(`dry run \u2014 ${toPublish} plugin${toPublish === 1 ? "" : "s"} would publish, uploading nothing`);
+    label(`dry run \u2014 ${noun(toPublish)} would publish, uploading nothing`);
     return;
   }
   if (!creds?.token) {
@@ -8285,7 +8469,7 @@ async function runWorkspaceDeploy(opts) {
       );
     }
     const proceed = await confirm2({
-      message: `Publish ${toPublish} plugin${toPublish === 1 ? "" : "s"} to ${client.baseUrl}?`,
+      message: `Publish ${noun(toPublish)} to ${client.baseUrl}?`,
       initialValue: false
     });
     if (!proceed) {
@@ -8293,7 +8477,7 @@ async function runWorkspaceDeploy(opts) {
       process.exit(130);
     }
   }
-  const results = await uploadPlan(plan, built, client);
+  const results = await uploadPlan(plan, built, client, { bundle: bundle?.name });
   let failures = 0;
   for (const r2 of results) {
     if (r2.status === "failed") failures++;
@@ -8304,8 +8488,18 @@ async function runWorkspaceDeploy(opts) {
       console.log(line);
     }
   }
+  if (bundleEntry) {
+    const r2 = await uploadBundle(bundleEntry, results, client);
+    if (r2.status === "failed") failures++;
+    const line = `${r2.bundle.name}@${r2.bundle.version} (bundle): ${r2.status}${r2.detail ? ` (${r2.detail})` : ""}`;
+    if (interactive) {
+      (r2.status === "failed" ? log2.error : r2.status === "published" ? log2.success : log2.info)(line);
+    } else {
+      console.log(line);
+    }
+  }
   if (failures > 0) {
-    throw new Error(`${failures} plugin${failures === 1 ? "" : "s"} failed to publish`);
+    throw new Error(`${noun(failures)} failed to publish`);
   }
 }
 
@@ -8314,7 +8508,7 @@ import { resolve as resolve16 } from "node:path";
 
 // src/version/version.ts
 import { existsSync as existsSync11 } from "node:fs";
-import { join as join17 } from "node:path";
+import { join as join18 } from "node:path";
 
 // src/version/changesets.ts
 var import_semver = __toESM(require_semver2(), 1);
@@ -8527,10 +8721,44 @@ function rewriteSiblingRanges(ws, releases, config) {
   return { rewrites, skips, touchedFiles };
 }
 
+// src/version/bundle-bump.ts
+var import_semver3 = __toESM(require_semver2(), 1);
+import { writeFileSync as writeFileSync7 } from "node:fs";
+import { join as join17 } from "node:path";
+var LEVEL = { none: 0, patch: 1, minor: 2, major: 3 };
+function plannedBundleBump(ws, releases) {
+  const bundle = readBundle(ws);
+  if (!bundle) return null;
+  const members = new Set(bundle.members.map((m) => m.name));
+  const memberReleases = releases.filter((r2) => members.has(r2.name) && r2.type !== "none");
+  if (memberReleases.length === 0) return null;
+  const type = memberReleases.reduce((t2, r2) => LEVEL[r2.type] > LEVEL[t2] ? r2.type : t2, "none");
+  const to = (0, import_semver3.inc)(bundle.version, type);
+  if (to === null) {
+    throw new Error(`s2s version: the bundle's version ${JSON.stringify(bundle.version)} is not valid semver`);
+  }
+  return {
+    name: bundle.name,
+    from: bundle.version,
+    to,
+    type,
+    because: memberReleases.map((r2) => `${r2.name}@${r2.newVersion}`)
+  };
+}
+function bumpBundle(ws, releases) {
+  const bump = plannedBundleBump(ws, releases);
+  if (!bump) return { bump: null, touchedFiles: [] };
+  const path = join17(ws.root, "package.json");
+  const { json, indent, eol } = readJsonFile(path);
+  json.version = bump.to;
+  writeFileSync7(path, JSON.stringify(json, null, indent) + eol);
+  return { bump, touchedFiles: [path] };
+}
+
 // src/version/version.ts
 async function versionWorkspace(root, opts = {}) {
   const ws = loadWorkspace(root);
-  const configPath = join17(ws.root, ".changeset", "config.json");
+  const configPath = join18(ws.root, ".changeset", "config.json");
   if (!existsSync11(configPath)) {
     throw new Error(
       `s2s version: ${configPath} does not exist \u2014 this workspace is not set up for changesets. Run \`npx changeset init\` at ${ws.root}.`
@@ -8545,13 +8773,15 @@ async function versionWorkspace(root, opts = {}) {
   const plan = cs.assembleReleasePlan(changesets, mirror, config, preState);
   const touchedFiles = await cs.applyReleasePlan(plan, real, config);
   const ranges = rewriteSiblingRanges(ws, plan.releases, config);
+  const bundle = bumpBundle(ws, plan.releases);
   return {
     root: ws.root,
     changesetCount: changesets.length,
     releases: plan.releases,
     rewrites: ranges.rewrites,
     skips: ranges.skips,
-    touchedFiles: [...touchedFiles, ...ranges.touchedFiles],
+    bundleBump: bundle.bump,
+    touchedFiles: [...touchedFiles, ...ranges.touchedFiles, ...bundle.touchedFiles],
     changesetsVersions: cs.versions
   };
 }
@@ -8587,6 +8817,10 @@ async function run3(argv2) {
     for (const r2 of result.releases) {
       lines.push(`${r2.name} ${r2.oldVersion} -> ${r2.newVersion} (${r2.type})`);
     }
+    if (result.bundleBump) {
+      const b = result.bundleBump;
+      lines.push(`${b.name} ${b.from} -> ${b.to} (${b.type}, bundle \u2014 follows ${b.because.join(", ")})`);
+    }
     for (const rw of result.rewrites) {
       lines.push(`${rw.consumer} pluginDependencies[${rw.iface}] ${rw.from} -> ${rw.to}`);
     }
@@ -8611,16 +8845,16 @@ import { resolve as resolve18 } from "node:path";
 // src/registry/add.ts
 import {
   mkdirSync as mkdirSync6,
-  writeFileSync as writeFileSync9,
+  writeFileSync as writeFileSync10,
   readFileSync as readFileSync17,
   existsSync as existsSync13
 } from "node:fs";
-import { join as join20, resolve as resolve17 } from "node:path";
+import { join as join21, resolve as resolve17 } from "node:path";
 import { gunzipSync } from "node:zlib";
 
 // src/registry/npmrc.ts
-import { existsSync as existsSync12, readFileSync as readFileSync16, writeFileSync as writeFileSync7 } from "node:fs";
-import { join as join18 } from "node:path";
+import { existsSync as existsSync12, readFileSync as readFileSync16, writeFileSync as writeFileSync8 } from "node:fs";
+import { join as join19 } from "node:path";
 function npmCompatRegistryUrl(registryUrl) {
   return `${registryUrl.replace(/\/$/, "")}/npm/`;
 }
@@ -8636,7 +8870,7 @@ function ensureScopeNpmrc(projectDir, packageName, registryUrl) {
   const compat = npmCompatRegistryUrl(registryUrl);
   const key = `@${scope}:registry`;
   const line = `${key}=${compat}`;
-  const npmrcPath = join18(projectDir, ".npmrc");
+  const npmrcPath = join19(projectDir, ".npmrc");
   let existing = existsSync12(npmrcPath) ? readFileSync16(npmrcPath, "utf8") : "";
   const lines = existing.split(/\r?\n/);
   const idx = lines.findIndex((l2) => l2.trimStart().startsWith(`${key}=`) || l2.trimStart().startsWith(`${key} =`));
@@ -8647,13 +8881,13 @@ function ensureScopeNpmrc(projectDir, packageName, registryUrl) {
     lines.push(line);
   }
   const out = lines.filter((l2, i2, a2) => !(l2 === "" && a2[i2 - 1] === "")).join("\n");
-  writeFileSync7(npmrcPath, out.endsWith("\n") ? out : out + "\n");
+  writeFileSync8(npmrcPath, out.endsWith("\n") ? out : out + "\n");
   return line;
 }
 
 // src/registry/lib-extract.ts
-import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync8 } from "node:fs";
-import { join as join19 } from "node:path";
+import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync9 } from "node:fs";
+import { join as join20 } from "node:path";
 var WANTED = /* @__PURE__ */ new Set(["index.js", "index.d.ts"]);
 function extractLibArchive(s2lib, outDir, meta) {
   const entries = unzipSync(new Uint8Array(s2lib));
@@ -8662,7 +8896,7 @@ function extractLibArchive(s2lib, outDir, meta) {
   mkdirSync5(outDir, { recursive: true });
   for (const [name, bytes] of Object.entries(entries)) {
     if (!WANTED.has(name)) continue;
-    writeFileSync8(join19(outDir, name), Buffer.from(bytes));
+    writeFileSync9(join20(outDir, name), Buffer.from(bytes));
   }
   let apiVersion = "1.x";
   try {
@@ -8670,8 +8904,8 @@ function extractLibArchive(s2lib, outDir, meta) {
     if (typeof m.apiVersion === "string") apiVersion = m.apiVersion;
   } catch {
   }
-  writeFileSync8(
-    join19(outDir, "package.json"),
+  writeFileSync9(
+    join20(outDir, "package.json"),
     JSON.stringify(
       { name: meta.name, version: meta.version, main: "index.js", types: "index.d.ts", s2script: { kind: "library", apiVersion } },
       null,
@@ -8708,13 +8942,13 @@ function extractTypesTarball(tgz, outDir) {
     if (!name || name.endsWith("/")) continue;
     const base = name.replace(/^package\//, "");
     if (base === "package.json") {
-      writeFileSync9(join20(outDir, "package.json"), content);
+      writeFileSync10(join21(outDir, "package.json"), content);
     } else if (base === "api.d.ts" || base === "index.d.ts") {
-      writeFileSync9(join20(outDir, "index.d.ts"), content);
+      writeFileSync10(join21(outDir, "index.d.ts"), content);
       wroteContract = true;
     }
   }
-  if (!wroteContract && !existsSync13(join20(outDir, "index.d.ts"))) {
+  if (!wroteContract && !existsSync13(join21(outDir, "index.d.ts"))) {
     throw new Error("types tarball missing package/api.d.ts (or index.d.ts)");
   }
 }
@@ -8732,16 +8966,21 @@ async function addPackage(opts) {
     fetch: opts.fetch
   });
   const resolved = await client.resolve(name, range);
+  if (resolved.kind === "bundle") {
+    throw new Error(
+      `${name} is a bundle \u2014 it groups plugins for install and has nothing to add to a plugin. Install it on a server with \`s2s install ${name}\`, or \`s2s add\` the member plugin whose interface you use.`
+    );
+  }
   if (resolved.kind === "library") {
     const s2lib = await client.downloadLib(name, resolved.version);
-    const libDir = join20(absDir, ".s2script", "libs", ...name.split("/"));
+    const libDir = join21(absDir, ".s2script", "libs", ...name.split("/"));
     extractLibArchive(s2lib, libDir, { name, version: resolved.version });
-    const pkgPath2 = join20(absDir, "package.json");
+    const pkgPath2 = join21(absDir, "package.json");
     const pkg2 = JSON.parse(readFileSync17(pkgPath2, "utf8"));
     pkg2.s2script = pkg2.s2script ?? {};
     pkg2.s2script.libraries = pkg2.s2script.libraries ?? {};
     pkg2.s2script.libraries[name] = rangeForResolved(range, resolved.version);
-    writeFileSync9(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
+    writeFileSync10(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
     return {
       kind: "library",
       name: resolved.name,
@@ -8758,14 +8997,14 @@ async function addPackage(opts) {
     throw new Error(`${name}@${resolved.version} has no types artifact (runtime-only package?)`);
   }
   const tgz = await client.downloadTypes(name, resolved.version);
-  const typesDir = join20(absDir, ".s2script", "types", ...name.split("/"));
+  const typesDir = join21(absDir, ".s2script", "types", ...name.split("/"));
   extractTypesTarball(tgz, typesDir);
-  const pkgPath = join20(absDir, "package.json");
+  const pkgPath = join21(absDir, "package.json");
   const pkg = JSON.parse(readFileSync17(pkgPath, "utf8"));
   pkg.s2script = pkg.s2script ?? {};
   pkg.s2script.pluginDependencies = pkg.s2script.pluginDependencies ?? {};
   pkg.s2script.pluginDependencies[name] = rangeForResolved(range, resolved.version);
-  writeFileSync9(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+  writeFileSync10(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
   const registryUrl = opts.registryUrl || creds?.registryUrl || defaultRegistryUrl();
   const npmrcLine = ensureScopeNpmrc(absDir, name, registryUrl);
   return {
@@ -8847,8 +9086,8 @@ import { existsSync as existsSync15 } from "node:fs";
 
 // src/registry/install.ts
 import { createHash as createHash4 } from "node:crypto";
-import { mkdirSync as mkdirSync7, readFileSync as readFileSync18, writeFileSync as writeFileSync10, renameSync, existsSync as existsSync14 } from "node:fs";
-import { basename as basename2, join as join21, resolve as resolve19, sep as sep3 } from "node:path";
+import { mkdirSync as mkdirSync7, readFileSync as readFileSync18, writeFileSync as writeFileSync11, renameSync, existsSync as existsSync14 } from "node:fs";
+import { basename as basename2, join as join22, resolve as resolve19, sep as sep3 } from "node:path";
 function parseManifest(input) {
   if (!input || typeof input !== "object" || Array.isArray(input)) {
     throw new Error("manifest must be a JSON object");
@@ -8858,11 +9097,26 @@ function parseManifest(input) {
     throw new Error('manifest must have a "plugins" object (name -> version range)');
   }
   const out = {};
-  for (const [name, range] of Object.entries(plugins)) {
-    if (typeof range !== "string") throw new Error(`range for ${name} must be a string`);
-    out[name] = range;
+  const withMembers = {};
+  for (const [name, entry] of Object.entries(plugins)) {
+    if (typeof entry === "string") {
+      out[name] = entry;
+      continue;
+    }
+    const obj2 = entry;
+    if (!obj2 || typeof obj2 !== "object" || Array.isArray(obj2)) {
+      throw new Error(`entry for ${name} must be a range string or { "range", "with" }`);
+    }
+    if (obj2.range !== void 0 && typeof obj2.range !== "string") {
+      throw new Error(`range for ${name} must be a string`);
+    }
+    if (obj2.with !== void 0 && (!Array.isArray(obj2.with) || obj2.with.some((w) => typeof w !== "string"))) {
+      throw new Error(`"with" for ${name} must be an array of optional member names`);
+    }
+    out[name] = obj2.range ?? "*";
+    if (Array.isArray(obj2.with) && obj2.with.length > 0) withMembers[name] = obj2.with;
   }
-  return { plugins: out };
+  return Object.keys(withMembers).length > 0 ? { plugins: out, with: withMembers } : { plugins: out };
 }
 function parseSpec2(spec) {
   const at = spec.lastIndexOf("@");
@@ -8889,12 +9143,12 @@ function safeFilename(e) {
   }
   return base;
 }
-async function resolveMerged(client, specs) {
+async function resolveMerged(client, specs, withMembers = {}) {
   const chosen = /* @__PURE__ */ new Map();
   const warnings = [];
   const errors = [];
   for (const [name, range] of Object.entries(specs)) {
-    const plan = await client.plan(name, range);
+    const plan = await client.plan(name, range, withMembers[name]);
     if (plan.errors.length) {
       errors.push(...plan.errors);
       continue;
@@ -8920,7 +9174,7 @@ async function resolveMerged(client, specs) {
 async function installPlan(opts) {
   const log3 = opts.log ?? (() => {
   });
-  const { install, warnings, errors } = await resolveMerged(opts.client, opts.specs);
+  const { install, warnings, errors } = await resolveMerged(opts.client, opts.specs, opts.with);
   if (errors.length) throw new Error(`cannot resolve plugins:
   - ${errors.join("\n  - ")}`);
   if (opts.reviewedOnly) {
@@ -8937,7 +9191,7 @@ async function installPlan(opts) {
       throw new Error(`refusing ${e.name}@${e.version}: registry did not provide a sha256 to verify against`);
     }
     const filename = safeFilename(e);
-    const dest = resolve19(join21(opts.dir, filename));
+    const dest = resolve19(join22(opts.dir, filename));
     if (dest !== dirResolved && !dest.startsWith(dirResolved + sep3)) {
       throw new Error(`refusing ${e.name}@${e.version}: destination "${dest}" escapes plugins dir "${dirResolved}"`);
     }
@@ -8966,7 +9220,7 @@ async function installPlan(opts) {
       throw new Error(`sha256 mismatch for ${e.name}@${e.version}: expected ${e.sha256}, got ${got}`);
     }
     const tmp = `${dest}.${process.pid}.tmp`;
-    writeFileSync10(tmp, bytes);
+    writeFileSync11(tmp, bytes);
     renameSync(tmp, dest);
     written.push(filename);
     log3(`installed ${e.name}@${e.version} -> ${filename}`);
@@ -8980,8 +9234,25 @@ function loadManifestFile(path) {
 
 // src/commands/install.ts
 var AUTODETECT = "addons/s2script/plugins";
+function collectWith(argv2) {
+  const out = [];
+  for (let i2 = 0; i2 < argv2.length; i2++) {
+    const arg = argv2[i2];
+    if (arg.startsWith("--with=")) {
+      if (arg.length > "--with=".length) out.push(arg.slice("--with=".length));
+      continue;
+    }
+    if (arg !== "--with") continue;
+    const value = argv2[i2 + 1];
+    if (value === void 0 || value.startsWith("-")) {
+      throw new Error("--with requires an optional member name (e.g. --with @edge/jailbreak-gangperks)");
+    }
+    out.push(value);
+  }
+  return out;
+}
 async function run5(argv2) {
-  const args = positionals(argv2, ["--dir", "--file", "--registry"]);
+  const args = positionals(argv2, ["--dir", "--file", "--registry", "--with"]);
   const file = parseFlag(argv2, "--file") ?? "s2script-plugins.json";
   const registry = parseFlag(argv2, "--registry") || loadCredentials()?.registryUrl || defaultRegistryUrl();
   const dryRun = hasFlag(argv2, "--dry-run");
@@ -8999,8 +9270,18 @@ async function run5(argv2) {
   }
   const client = new RegistryClient({ baseUrl: registry });
   try {
+    const withArgs = collectWith(argv2);
     const manifest = loadManifestFile(resolve20(file));
     const specs = mergeSpecs(manifest, args);
+    const withMembers = { ...manifest.with ?? {} };
+    if (withArgs.length > 0) {
+      if (args.length !== 1) {
+        throw new Error(
+          `--with applies to exactly one bundle named on the command line (got ${args.length}) \u2014 for several bundles, use { "range", "with" } entries in ${file}`
+        );
+      }
+      withMembers[parseSpec2(args[0]).name] = withArgs;
+    }
     if (Object.keys(specs).length === 0) {
       console.error(
         `Nothing to install. Add plugins to ${file} or pass names: s2s install rtv@^1.0.0`
@@ -9010,6 +9291,7 @@ async function run5(argv2) {
     const res = await installPlan({
       client,
       specs,
+      with: withMembers,
       dir,
       dryRun,
       reviewedOnly,
@@ -9034,21 +9316,21 @@ import { resolve as resolve23 } from "node:path";
 // src/create/create.ts
 import {
   mkdirSync as mkdirSync8,
-  writeFileSync as writeFileSync11,
+  writeFileSync as writeFileSync12,
   existsSync as existsSync16,
-  readdirSync as readdirSync4,
+  readdirSync as readdirSync5,
   readFileSync as readFileSync19,
   symlinkSync
 } from "node:fs";
-import { dirname as dirname6, isAbsolute, join as join22, relative as relative2, resolve as resolve21, basename as basename3 } from "node:path";
+import { dirname as dirname6, isAbsolute, join as join23, relative as relative2, resolve as resolve21, basename as basename3 } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function readCliVersion() {
   const here = dirname6(fileURLToPath2(import.meta.url));
   const candidates = [
-    join22(here, "..", "package.json"),
+    join23(here, "..", "package.json"),
     // dist/cli.js → packages/sdk/package.json
-    join22(here, "..", "..", "package.json")
+    join23(here, "..", "..", "package.json")
     // src/create → packages/sdk/package.json
   ];
   for (const p of candidates) {
@@ -9064,9 +9346,9 @@ function readCliVersion() {
 function findLocalPackagesDir() {
   const here = dirname6(fileURLToPath2(import.meta.url));
   const candidates = [
-    join22(here, "..", ".."),
+    join23(here, "..", ".."),
     // dist/cli.js → packages
-    join22(here, "..", "..", "..")
+    join23(here, "..", "..", "..")
     // src/create → packages
   ];
   for (const c2 of candidates) {
@@ -9083,7 +9365,7 @@ function defaultNameFromPath(dir, kind = "plugin") {
 }
 function assertEmptyTarget(targetPath) {
   if (!existsSync16(targetPath)) return;
-  const kids = readdirSync4(targetPath);
+  const kids = readdirSync5(targetPath);
   const meaningful = kids.filter((k) => k !== ".git");
   if (meaningful.length) {
     throw new Error(`target directory is not empty: ${targetPath}`);
@@ -9131,8 +9413,8 @@ function registryDevDeps(game, sdkVersion, resolve25 = resolvePublishedVersion)
 function fileDevDeps(packagesDir, game) {
   const deps = {};
   for (const n3 of createPackageNames(game)) {
-    const abs = join22(packagesDir, n3);
-    if (!existsSync16(join22(abs, "package.json"))) return void 0;
+    const abs = join23(packagesDir, n3);
+    if (!existsSync16(join23(abs, "package.json"))) return void 0;
     deps[`@s2script/${n3}`] = `file:${abs}`;
   }
   return deps;
@@ -9197,7 +9479,7 @@ function tsconfigJson() {
   ) + "\n";
 }
 function workspaceTsconfigJson(targetPath, workspaceRoot) {
-  const rel = relative2(targetPath, join22(workspaceRoot, "tsconfig.base.json")).replace(/\\/g, "/");
+  const rel = relative2(targetPath, join23(workspaceRoot, "tsconfig.base.json")).replace(/\\/g, "/");
   return JSON.stringify(
     {
       extends: rel.startsWith(".") ? rel : `./${rel}`,
@@ -9273,9 +9555,9 @@ dist/
 `;
 }
 function linkLocalPackagesForNoInstall(targetPath, localPackagesDir) {
-  const nm = join22(targetPath, "node_modules");
+  const nm = join23(targetPath, "node_modules");
   mkdirSync8(nm, { recursive: true });
-  const dest = join22(nm, "@s2script");
+  const dest = join23(nm, "@s2script");
   if (!existsSync16(dest)) symlinkSync(localPackagesDir, dest);
 }
 function runInstall(dir, pm) {
@@ -9305,7 +9587,7 @@ async function createPlugin(opts = {}) {
     );
   }
   let slug = workspaceRoot !== void 0 && opts.path !== void 0 ? assertBareSlug(opts.path) : opts.path;
-  let targetPath = workspaceRoot === void 0 ? resolve21(opts.path ?? ".") : slug === void 0 ? void 0 : join22(workspaceRoot, "plugins", slug);
+  let targetPath = workspaceRoot === void 0 ? resolve21(opts.path ?? ".") : slug === void 0 ? void 0 : join23(workspaceRoot, "plugins", slug);
   if (targetPath !== void 0) assertEmptyTarget(targetPath);
   if (interactive) {
     intro2("Create an s2script plugin");
@@ -9315,7 +9597,7 @@ async function createPlugin(opts = {}) {
         slug = assertBareSlug(
           await text2({ message: "Plugin name (directory under plugins/)", placeholder: "myplugin" })
         );
-        targetPath = join22(workspaceRoot, "plugins", slug);
+        targetPath = join23(workspaceRoot, "plugins", slug);
         assertEmptyTarget(targetPath);
       }
     }
@@ -9378,37 +9660,37 @@ async function createPlugin(opts = {}) {
   install = workspaceRoot !== void 0 ? "none" : install ?? (opts.noInstall ? "none" : "npm");
   const finalTargetPath = targetPath;
   const localPackagesDir = workspaceRoot === void 0 ? findLocalPackagesDir() : void 0;
-  mkdirSync8(join22(finalTargetPath, "src"), { recursive: true });
+  mkdirSync8(join23(finalTargetPath, "src"), { recursive: true });
   if (workspaceRoot !== void 0) {
-    writeFileSync11(join22(finalTargetPath, "package.json"), minimalPackageJsonContent(name));
-    writeFileSync11(
-      join22(finalTargetPath, "tsconfig.json"),
+    writeFileSync12(join23(finalTargetPath, "package.json"), minimalPackageJsonContent(name));
+    writeFileSync12(
+      join23(finalTargetPath, "tsconfig.json"),
       workspaceTsconfigJson(finalTargetPath, workspaceRoot)
     );
   } else if (kind === "library") {
     const version = readCliVersion();
-    writeFileSync11(
-      join22(finalTargetPath, "package.json"),
+    writeFileSync12(
+      join23(finalTargetPath, "package.json"),
       libraryPackageJsonContent(name, game, version, localPackagesDir)
     );
-    writeFileSync11(join22(finalTargetPath, "tsconfig.json"), tsconfigJson());
-    writeFileSync11(join22(finalTargetPath, "eslint.config.mjs"), eslintConfig());
+    writeFileSync12(join23(finalTargetPath, "tsconfig.json"), tsconfigJson());
+    writeFileSync12(join23(finalTargetPath, "eslint.config.mjs"), eslintConfig());
   } else {
     const version = readCliVersion();
-    writeFileSync11(
-      join22(finalTargetPath, "package.json"),
+    writeFileSync12(
+      join23(finalTargetPath, "package.json"),
       packageJsonContent(name, game, version, localPackagesDir)
     );
-    writeFileSync11(join22(finalTargetPath, "tsconfig.json"), tsconfigJson());
-    writeFileSync11(join22(finalTargetPath, "eslint.config.mjs"), eslintConfig());
+    writeFileSync12(join23(finalTargetPath, "tsconfig.json"), tsconfigJson());
+    writeFileSync12(join23(finalTargetPath, "eslint.config.mjs"), eslintConfig());
   }
   if (kind === "library") {
-    writeFileSync11(join22(finalTargetPath, "src", "index.ts"), LIBRARY_ENTRY);
-    writeFileSync11(join22(finalTargetPath, "src", "index.d.ts"), LIBRARY_TYPES);
+    writeFileSync12(join23(finalTargetPath, "src", "index.ts"), LIBRARY_ENTRY);
+    writeFileSync12(join23(finalTargetPath, "src", "index.d.ts"), LIBRARY_TYPES);
   } else {
-    writeFileSync11(join22(finalTargetPath, "src", "plugin.ts"), pluginSource(game));
+    writeFileSync12(join23(finalTargetPath, "src", "plugin.ts"), pluginSource(game));
   }
-  writeFileSync11(join22(finalTargetPath, ".gitignore"), gitignore());
+  writeFileSync12(join23(finalTargetPath, ".gitignore"), gitignore());
   let installed = false;
   if (workspaceRoot === void 0) {
     if (install !== "none") {
@@ -9435,8 +9717,8 @@ async function createPlugin(opts = {}) {
 }
 
 // src/create/workspace.ts
-import { mkdirSync as mkdirSync9, writeFileSync as writeFileSync12 } from "node:fs";
-import { join as join23, resolve as resolve22 } from "node:path";
+import { mkdirSync as mkdirSync9, writeFileSync as writeFileSync13 } from "node:fs";
+import { join as join24, resolve as resolve22 } from "node:path";
 var ROOT_DEFAULT_GAME = "cs2";
 var CHANGESETS_CLI_RANGE = "^2.29.5";
 function defaultWorkspaceName(dir) {
@@ -9520,14 +9802,14 @@ async function createWorkspace(opts = {}) {
   name = name ?? defaultWorkspaceName(targetPath);
   const version = readCliVersion();
   const localPackagesDir = findLocalPackagesDir();
-  mkdirSync9(join23(targetPath, "plugins"), { recursive: true });
-  mkdirSync9(join23(targetPath, "packages"), { recursive: true });
-  mkdirSync9(join23(targetPath, ".changeset"), { recursive: true });
-  writeFileSync12(join23(targetPath, "package.json"), rootPackageJsonContent(name, version, localPackagesDir));
-  writeFileSync12(join23(targetPath, "tsconfig.base.json"), tsconfigBaseJson());
-  writeFileSync12(join23(targetPath, "eslint.config.mjs"), eslintConfig());
-  writeFileSync12(join23(targetPath, ".changeset", "config.json"), changesetConfigJson());
-  writeFileSync12(join23(targetPath, ".gitignore"), gitignore());
+  mkdirSync9(join24(targetPath, "plugins"), { recursive: true });
+  mkdirSync9(join24(targetPath, "packages"), { recursive: true });
+  mkdirSync9(join24(targetPath, ".changeset"), { recursive: true });
+  writeFileSync13(join24(targetPath, "package.json"), rootPackageJsonContent(name, version, localPackagesDir));
+  writeFileSync13(join24(targetPath, "tsconfig.base.json"), tsconfigBaseJson());
+  writeFileSync13(join24(targetPath, "eslint.config.mjs"), eslintConfig());
+  writeFileSync13(join24(targetPath, ".changeset", "config.json"), changesetConfigJson());
+  writeFileSync13(join24(targetPath, ".gitignore"), gitignore());
   return { dir: targetPath, name };
 }
 
@@ -9763,8 +10045,8 @@ async function run7(argv2) {
 }
 
 // src/config/gen.ts
-import { readFileSync as readFileSync20, writeFileSync as writeFileSync13, mkdirSync as mkdirSync10 } from "node:fs";
-import { join as join24 } from "node:path";
+import { readFileSync as readFileSync20, writeFileSync as writeFileSync14, mkdirSync as mkdirSync10 } from "node:fs";
+import { join as join25 } from "node:path";
 
 // src/config/config-path.ts
 function configFileName(id) {
@@ -9811,8 +10093,8 @@ function genConfigFromManifest(manifest, outDir) {
   const id = typeof manifest.id === "string" ? manifest.id : "";
   if (!id) throw new Error("config gen: manifest declares config but has no id");
   mkdirSync10(outDir, { recursive: true });
-  const path = join24(outDir, configFileName(id));
-  writeFileSync13(path, generateDefaultJsonc(config));
+  const path = join25(outDir, configFileName(id));
+  writeFileSync14(path, generateDefaultJsonc(config));
   return path;
 }
 function genConfigForS2sp(s2spPath, outDir) {
@@ -9863,12 +10145,12 @@ async function run8(argv2) {
 }
 
 // src/commands/codegen.ts
-import { dirname as dirname7, join as join29 } from "node:path";
+import { dirname as dirname7, join as join30 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/schemagen/gen.ts
-import { readFileSync as readFileSync21, writeFileSync as writeFileSync14 } from "node:fs";
-import { join as join25 } from "node:path";
+import { readFileSync as readFileSync21, writeFileSync as writeFileSync15 } from "node:fs";
+import { join as join26 } from "node:path";
 
 // src/schemagen/model.ts
 function enumMemberNames(enumName, members) {
@@ -10351,16 +10633,16 @@ var EMBED_PATH = "games/cs2/codegen-embedded.json";
 var JS_OUT = "games/cs2/js/schema.generated.js";
 var DTS_OUT = "packages/cs2/schema.generated.d.ts";
 function runGenSchema(repoRoot2, opts) {
-  const catalog = JSON.parse(readFileSync21(join25(repoRoot2, CATALOG_PATH), "utf8"));
-  const list = JSON.parse(readFileSync21(join25(repoRoot2, LIST_PATH), "utf8"));
+  const catalog = JSON.parse(readFileSync21(join26(repoRoot2, CATALOG_PATH), "utf8"));
+  const list = JSON.parse(readFileSync21(join26(repoRoot2, LIST_PATH), "utf8"));
   let embed = [];
   try {
-    embed = JSON.parse(readFileSync21(join25(repoRoot2, EMBED_PATH), "utf8"));
+    embed = JSON.parse(readFileSync21(join26(repoRoot2, EMBED_PATH), "utf8"));
   } catch {
   }
   let enumCatalog = {};
   try {
-    enumCatalog = JSON.parse(readFileSync21(join25(repoRoot2, ENUMS_PATH), "utf8"));
+    enumCatalog = JSON.parse(readFileSync21(join26(repoRoot2, ENUMS_PATH), "utf8"));
   } catch {
   }
   const model = buildModel(catalog, list, embed, enumCatalog);
@@ -10371,7 +10653,7 @@ function runGenSchema(repoRoot2, opts) {
   const drift = [];
   const files = [[JS_OUT, js], [DTS_OUT, dts]];
   for (const [rel, content] of files) {
-    const abs = join25(repoRoot2, rel);
+    const abs = join26(repoRoot2, rel);
     if (opts.check) {
       let cur = "";
       try {
@@ -10380,7 +10662,7 @@ function runGenSchema(repoRoot2, opts) {
       }
       if (cur !== content) drift.push(rel);
     } else {
-      writeFileSync14(abs, content);
+      writeFileSync15(abs, content);
     }
   }
   if (model.collisions.length) console.error(`gen-schema: ${model.collisions.length} name collision(s) \u2192 raw fallback:
@@ -10390,8 +10672,8 @@ function runGenSchema(repoRoot2, opts) {
 }
 
 // src/eventgen/gen.ts
-import { readFileSync as readFileSync22, writeFileSync as writeFileSync15 } from "node:fs";
-import { join as join26 } from "node:path";
+import { readFileSync as readFileSync22, writeFileSync as writeFileSync16 } from "node:fs";
+import { join as join27 } from "node:path";
 
 // src/eventgen/model.ts
 var TYPE_TO_GETTER = {
@@ -10476,11 +10758,11 @@ function emitEventDts(model) {
 var CATALOG_PATH2 = "games/cs2/gamedata/event-catalog.json";
 var DTS_OUT2 = "packages/cs2/events.generated.d.ts";
 function runGenEvents(repoRoot2, opts) {
-  const catalog = JSON.parse(readFileSync22(join26(repoRoot2, CATALOG_PATH2), "utf8"));
+  const catalog = JSON.parse(readFileSync22(join27(repoRoot2, CATALOG_PATH2), "utf8"));
   const model = buildEventModel(catalog);
   const dts = emitEventDts(model);
   const drift = [];
-  const abs = join26(repoRoot2, DTS_OUT2);
+  const abs = join27(repoRoot2, DTS_OUT2);
   if (opts.check) {
     let cur = "";
     try {
@@ -10489,14 +10771,14 @@ function runGenEvents(repoRoot2, opts) {
     }
     if (cur !== dts) drift.push(DTS_OUT2);
   } else {
-    writeFileSync15(abs, dts);
+    writeFileSync16(abs, dts);
   }
   return { events: model.length, drift };
 }
 
 // src/navgen/gen.ts
-import { readFileSync as readFileSync23, writeFileSync as writeFileSync16 } from "node:fs";
-import { join as join27 } from "node:path";
+import { readFileSync as readFileSync23, writeFileSync as writeFileSync17 } from "node:fs";
+import { join as join28 } from "node:path";
 
 // src/navgen/model.ts
 var SUPPORTED_NAV_KINDS = /* @__PURE__ */ new Set([
@@ -10717,8 +10999,8 @@ var CATALOG_PATH3 = "games/cs2/gamedata/schema-catalog.json";
 var JS_OUT2 = "games/cs2/js/nav.generated.js";
 var DTS_OUT3 = "packages/cs2/nav.generated.d.ts";
 function runGenNav(repoRoot2, opts) {
-  const config = JSON.parse(readFileSync23(join27(repoRoot2, TARGETS_PATH), "utf8"));
-  const catalog = JSON.parse(readFileSync23(join27(repoRoot2, CATALOG_PATH3), "utf8"));
+  const config = JSON.parse(readFileSync23(join28(repoRoot2, TARGETS_PATH), "utf8"));
+  const catalog = JSON.parse(readFileSync23(join28(repoRoot2, CATALOG_PATH3), "utf8"));
   const model = buildNavModel(config, catalog);
   const js = emitNavJs(model);
   const dts = emitNavDts(model);
@@ -10726,7 +11008,7 @@ function runGenNav(repoRoot2, opts) {
   const drift = [];
   const files = [[JS_OUT2, js], [DTS_OUT3, dts]];
   for (const [rel, content] of files) {
-    const abs = join27(repoRoot2, rel);
+    const abs = join28(repoRoot2, rel);
     if (opts.check) {
       let cur = "";
       try {
@@ -10735,25 +11017,25 @@ function runGenNav(repoRoot2, opts) {
       }
       if (cur !== content) drift.push(rel);
     } else {
-      writeFileSync16(abs, content);
+      writeFileSync17(abs, content);
     }
   }
   return { wrappers: model.wrappers.length, fields: fields2, drift };
 }
 
 // src/hookgen/gen.ts
-import { readFileSync as readFileSync24, writeFileSync as writeFileSync17 } from "node:fs";
-import { join as join28 } from "node:path";
+import { readFileSync as readFileSync24, writeFileSync as writeFileSync18 } from "node:fs";
+import { join as join29 } from "node:path";
 var GAMEDATA_PATH = "games/cs2/gamedata/game.cs2.jsonc";
 var DTS_OUT4 = "packages/cs2/hooks.generated.d.ts";
 function runGenHooks(repoRoot2, opts) {
-  const raw = readFileSync24(join28(repoRoot2, GAMEDATA_PATH), "utf8");
+  const raw = readFileSync24(join29(repoRoot2, GAMEDATA_PATH), "utf8");
   const gd = JSON.parse(stripJsonComments(raw));
   const hooks = gd.hooks ?? {};
   const model = buildHookModel(hooks);
   const dts = emitHookDts(model);
   const drift = [];
-  const abs = join28(repoRoot2, DTS_OUT4);
+  const abs = join29(repoRoot2, DTS_OUT4);
   if (opts.check) {
     let cur = "";
     try {
@@ -10762,7 +11044,7 @@ function runGenHooks(repoRoot2, opts) {
     }
     if (cur !== dts) drift.push(DTS_OUT4);
   } else {
-    writeFileSync17(abs, dts);
+    writeFileSync18(abs, dts);
   }
   const hookCount = model.reduce((n3, ns) => n3 + ns.hooks.length, 0);
   return { hooks: hookCount, drift };
@@ -10770,7 +11052,7 @@ function runGenHooks(repoRoot2, opts) {
 
 // src/commands/codegen.ts
 function repoRoot() {
-  return join29(dirname7(fileURLToPath3(import.meta.url)), "..", "..", "..");
+  return join30(dirname7(fileURLToPath3(import.meta.url)), "..", "..", "..");
 }
 async function run9(kind, argv2) {
   const root = repoRoot();
@@ -10858,8 +11140,8 @@ async function run10(argv2) {
 }
 
 // src/engine-functions/migrate-v1.ts
-import { closeSync, existsSync as existsSync17, linkSync, lstatSync as lstatSync2, mkdirSync as mkdirSync11, openSync, readFileSync as readFileSync26, readdirSync as readdirSync5, renameSync as renameSync2, unlinkSync, writeFileSync as writeFileSync18 } from "node:fs";
-import { dirname as dirname8, isAbsolute as isAbsolute2, join as join30, relative as relative3, resolve as resolve24, sep as sep4 } from "node:path";
+import { closeSync, existsSync as existsSync17, linkSync, lstatSync as lstatSync2, mkdirSync as mkdirSync11, openSync, readFileSync as readFileSync26, readdirSync as readdirSync6, renameSync as renameSync2, unlinkSync, writeFileSync as writeFileSync19 } from "node:fs";
+import { dirname as dirname8, isAbsolute as isAbsolute2, join as join31, relative as relative3, resolve as resolve24, sep as sep4 } from "node:path";
 import { createHash as createHash5, randomUUID } from "node:crypto";
 import ts5 from "typescript";
 var PLATFORM3 = "linuxsteamrt64";
@@ -10986,11 +11268,11 @@ function hookOf(name, value, signatures, errors) {
 }
 function sourceFiles(dir, pkg, errors) {
   const result = /* @__PURE__ */ new Set();
-  const src = join30(dir, "src");
+  const src = join31(dir, "src");
   function walk(at) {
     if (!existsSync17(at)) return;
-    for (const item of readdirSync5(at, { withFileTypes: true })) {
-      const p = join30(at, item.name);
+    for (const item of readdirSync6(at, { withFileTypes: true })) {
+      const p = join31(at, item.name);
       if (item.isDirectory()) walk(p);
       else if (item.isFile() && /\.[cm]?[jt]sx?$/.test(item.name)) result.add(p);
     }
@@ -11013,7 +11295,7 @@ function sourceFiles(dir, pkg, errors) {
         return;
       }
       const stem = base.replace(/\.[cm]?[jt]sx?$/, "");
-      const candidates = [base, ...[".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs", ".cts", ".cjs"].map((x) => stem + x), ...["index.ts", "index.tsx", "index.js", "index.jsx"].map((x) => join30(base, x))];
+      const candidates = [base, ...[".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs", ".cts", ".cjs"].map((x) => stem + x), ...["index.ts", "index.tsx", "index.js", "index.jsx"].map((x) => join31(base, x))];
       const found = candidates.find((p) => contained(dir, p) && existsSync17(p) && lstatSync2(p).isFile());
       if (!found) {
         errors.push(`${at}: unresolved local module ${JSON.stringify(spec)}`);
@@ -11184,12 +11466,12 @@ function scanSource(files, calls, hooks, report) {
 }
 function analyzeV1Migration(pluginDir, options = {}) {
   const dir = resolve24(pluginDir);
-  const destination = join30(dir, "gamedata", "functions.jsonc");
+  const destination = join31(dir, "gamedata", "functions.jsonc");
   const report = { scope: SCOPE, package: dir, destination, entries: [], permissions: [], sourceReferences: [], generatedDeclarations: [], generatedDeclarationHashes: {}, recommendedEdits: [], ambiguities: [], filesChanged: [] };
   if (pathExists(destination) && !options.force) report.ambiguities.push(`${destination}: destination already exists; use --force to replace it`);
   let pkg;
   try {
-    pkg = parseFunctionFile(join30(dir, "package.json"), readFileSync26(join30(dir, "package.json"), "utf8"));
+    pkg = parseFunctionFile(join31(dir, "package.json"), readFileSync26(join31(dir, "package.json"), "utf8"));
   } catch (e) {
     report.ambiguities.push(`package.json: ${e.message}`);
     return report;
@@ -11311,7 +11593,7 @@ function analyzeV1Migration(pluginDir, options = {}) {
     }
   }
   report.output = author;
-  report.generatedDeclarations = ["gamedata.d.ts", "hooks.d.ts"].map((n3) => join30(dir, ".s2script", n3)).filter(existsSync17);
+  report.generatedDeclarations = ["gamedata.d.ts", "hooks.d.ts"].map((n3) => join31(dir, ".s2script", n3)).filter(existsSync17);
   for (const file of report.generatedDeclarations) {
     try {
       report.generatedDeclarationHashes[file] = createHash5("sha256").update(readFileSync26(file)).digest("hex");
@@ -11333,12 +11615,12 @@ function migrateV1Package(pluginDir, options = {}) {
   const report = analyzeV1Migration(pluginDir, options);
   if (report.ambiguities.length || !report.output) return report;
   const dest = report.destination;
-  const temp = join30(dirname8(dest), `.functions.jsonc.${process.pid}.${randomUUID()}.tmp`);
+  const temp = join31(dirname8(dest), `.functions.jsonc.${process.pid}.${randomUUID()}.tmp`);
   try {
     mkdirSync11(dirname8(dest), { recursive: true });
     const fd2 = openSync(temp, "wx", 384);
     try {
-      writeFileSync18(fd2, JSON.stringify(report.output, null, 2) + "\n");
+      writeFileSync19(fd2, JSON.stringify(report.output, null, 2) + "\n");
     } finally {
       closeSync(fd2);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "license": "MIT OR Apache-2.0",
   "description": "s2script SDK — the builtin capability types (imported as @s2script/sdk/entity, …) plus the `s2s` CLI for building Source 2 / CS2 plugins.",
   "type": "module",