@s2script/sdk 0.28.0 → 0.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "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",
@@ -21,6 +21,8 @@
   "devDependencies": {
     "@clack/prompts": "^1.7.0",
     "fflate": "^0.8.2",
+    "ignore": "^5.3.2",
+    "minimatch": "^10.2.6",
     "semver": "^7.8.5"
   },
   "publishConfig": {

package/phrases.d.ts

@@ -23,7 +23,7 @@
  * unresolved key renders as the key itself, so it should still read as a sentence.
  *
  * ```json
- * { "Gagged Player": "{green}[SM]{default} Gagged {1} player." }
+ * { "Gagged Player": "{green}[S2S]{default} Gagged {1} player." }
  * ```
  *
  * A translator adds `translations/<code>/<your-plugin>.phrases.json` — no code change, no rebuild.

package/plugins.d.ts

@@ -16,12 +16,15 @@ export interface PluginInfo {
    * - `"unloaded"` — on disk but manually unloaded via `unload` (not auto-reloaded until `load`/`reload`).
    */
   readonly state: "running" | "loading" | "waiting" | "failed" | "unloaded";
+  /** The folder under `plugins/` (e.g. `"disabled"`, `"fun"`) this plugin was loaded from by
+   * {@link Plugins.load} for this run only — it stays there on disk, so a restart leaves it off.
+   * null for a plugin loaded from `plugins/` itself. */
+  readonly folder: string | null;
 }
 /**
  * Enumerate and drive the plugin set at runtime (list / load / unload / reload).
  * @example
  * import { Plugins } from "@s2script/sdk/plugins";
- * // plugins/basecommands/src/plugin.ts:126 — sm plugins list
  * for (const p of Plugins.list()) cmd.reply(p.id + " — " + p.state);
  */
 export declare const Plugins: {
@@ -32,6 +35,32 @@ export declare const Plugins: {
   unload(id: string): boolean;
   /** Reload a plugin (unload + load from disk, deferred). false if the id is unknown. */
   reload(id: string): boolean;
-  /** Load a previously-unloaded plugin (deferred). false if it isn't currently unloaded. */
+  /**
+   * Load a plugin that isn't running (deferred): one unloaded earlier this run, by id — or, as
+   * `"<folder>/<plugin id>"` (e.g. `"fun/@edgegamers/jailbreak"`, `"disabled/@edge/rtv"`), one kept
+   * in any folder under `plugins/`, for THIS RUN ONLY. Only a folder prefix reaches into a folder;
+   * the id is mapped to its file for you; nothing outside `plugins/` is reachable. The file stays
+   * where it is (a restart leaves it off; for disabled/ plugins, `enable` makes it permanent).
+   * false if there is no such plugin. `unload` accepts the same `<folder>/<plugin id>` form.
+   */
   load(id: string): boolean;
+  /**
+   * Add registry plugins to the server's `addons/s2script/plugins.json` and install them with their
+   * dependencies (`sm plugins install`). A bare name records `^<latest>`; `name@range` records the
+   * range. `with` names optional members of the ONE bundle given. The files land in `plugins/`,
+   * where the loader picks them up — or, with `disabled`, in `plugins/disabled/`, where it never
+   * looks (kept current at startup, loaded once enabled). Resolves with report lines; rejects with
+   * the reason.
+   */
+  install(names: string[], opts?: { with?: string[]; disabled?: boolean }): Promise<string[]>;
+  /** Move the named plugins (all when omitted) to the newest version their plugins.json range allows. */
+  update(names?: string[]): Promise<string[]>;
+  /** Drop plugins from plugins.json; their files are removed (unless edited by hand) and unloaded. */
+  remove(names: string[]): Promise<string[]>;
+  /** One line per plugins.json dependency: current, wanted (newest in range) and latest version. */
+  outdated(): Promise<string[]>;
+  /** Move installed plugins out of plugins/disabled/ (they load) and record it in plugins.json. */
+  enable(names: string[]): Promise<string[]>;
+  /** Move installed plugins into plugins/disabled/ (they unload, and stay off across restarts). */
+  disable(names: string[]): Promise<string[]>;
 };

package/unsafe.d.ts

@@ -5,9 +5,9 @@
  * UNSAFE by design. A declared call reaches a real engine function; a declared hook patches
  * that function's prologue. The framework validates every descriptor at load and degrades a
  * failure to `null`, but it cannot prove your signature or vtable index names the function you
- * meant. Calls require manifest `permissions: ["engine:calls"]`; hooks require the separate
- * `"engine:hooks"` permission. Both also need an operator allow-list entry
- * (see docs/superpowers/specs/2026-07-24-plugin-gamedata-design.md §6 and ARCHITECTURE.md §2.0.7).
+ * meant. `s2s build` records `engine:calls` / `engine:hooks` in the manifest from your gamedata so
+ * `s2s inspect` and the registry can show what the plugin reaches into; nothing to declare by hand
+ * (see docs/superpowers/specs/2026-07-24-plugin-gamedata-design.md and ARCHITECTURE.md §2.0.7).
  */
 
 /**