@s2script/sdk 0.11.0 → 0.13.0

package/README.md

@@ -34,6 +34,59 @@ per-capability subpaths (`@s2script/sdk/entity`, `@s2script/sdk/timers`, `@s2scr
 game-specific schema types ship separately in
 [`@s2script/cs2`](https://www.npmjs.com/package/@s2script/cs2).
 
+## Workspaces
+
+A directory whose root `package.json` carries an `s2script.workspace.plugins` glob list — next to
+npm's own `workspaces` field — is a **workspace**: a repo holding several plugins that build,
+publish, and version together.
+
+```json
+{
+  "name": "my-server-plugins",
+  "private": true,
+  "workspaces": ["plugins/*", "packages/*"],
+  "s2script": { "workspace": { "plugins": ["plugins/*"] } }
+}
+```
+
+```bash
+npx @s2script/sdk create --workspace my-server-plugins
+cd my-server-plugins
+npx @s2script/sdk create shop      # detects the workspace, writes plugins/shop (no per-plugin devDeps)
+npm install                        # links every member into node_modules
+npx @s2script/sdk build            # every plugin, dependency order; --filter <pattern> to narrow
+npx @s2script/sdk deploy           # build + publish, skipping `private` and already-shipped versions
+npx @s2script/sdk version          # applies pending changesets, cascading sibling version ranges
+```
+
+Finding no `s2script.workspace` marker above the target directory, every command behaves exactly as
+it does today — workspace mode is opt-in by construction. `s2s build <one-plugin-dir>` (naming a
+specific plugin rather than the root) always stays single-plugin mode even inside a workspace;
+`--filter` is the workspace-mode way to narrow to a subset, by package name (`@me/shop`, `@me/*`) or
+by path glob (`plugins/sh*`). `--stamp-version <v>` (build-only) rewrites every plugin's version
+*and* the sibling ranges that would otherwise break.
+
+**Sibling interfaces need no `.s2script/types/` copy.** npm already symlinks every workspace member
+into `node_modules` — declared as a dependency or not — so a consumer's `import type { ShopAPI }
+from "@me/shop"` resolves straight to `@me/shop`'s own published `types` file under
+`moduleResolution: "bundler"`, no config and no copy required. Contrast this with depending on a
+**registry** package (`s2s add @edge/admin-core`): that pulls the producer's `.d.ts` down into your
+own `.s2script/types/<dep>/index.d.ts`, because a registry producer isn't sitting in the same
+checkout — a byte-copy (hashed into `manifest.compiledAgainst`, re-verified against the producer's
+published hash at load) is the only way your build can see its shape at all, and it goes stale the
+moment the producer's interface changes until you re-run `s2s add`. A workspace sibling's contract
+can never go stale that way: the file your build resolves to *is* the producer's current contract,
+on the same disk, in the same commit. If a plugin still carries a pre-migration
+`.s2script/types/<dep>/` copy after joining a workspace, the live sibling wins and the build warns
+that the copy is now dead weight.
+
+**`private: true` means built, never published.** Ordinary npm/Changesets semantics, not a new
+field: `s2s build` builds every plugin in a workspace regardless of `private`, but `s2s deploy`
+prints a per-plugin plan that skips a `private: true` package by name instead of shipping it. That's
+what lets a workspace hold a large first-party or in-house plugin suite that must never reach the
+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.)
+
 ## Docs
 
 **[s2script.com/docs](https://s2script.com/docs)** — getting started, guides, and the full API

package/commands.d.ts

@@ -1,5 +1,7 @@
 /** @s2script/commands — register server commands. NO runtime code (injected at load). */
 
+import type { HookResultValue } from "./events";
+
 /**
  * Where a command was invoked from — SourceMod's *reply source*. Set by the dispatch path and
  * exposed as {@link CommandInvocation.replySource}; it is what {@link CommandInvocation.reply}
@@ -112,6 +114,23 @@ export declare const Commands: {
   handleChatTrigger(slot: number, message: string): { silent: boolean; ran: boolean } | null;
   /** The trigger characters — SM PublicChatTrigger (`"!"`) / SilentChatTrigger (`"/"`). Mutate to reconfigure. */
   readonly triggers: { public: string; silent: string };
+  /**
+   * Observe a CLIENT command by name — SourceMod's `AddCommandListener`.
+   *
+   * Unlike {@link register}, which CREATES a command, this hooks one that already exists — including
+   * commands the engine itself owns (`player_ping`, `jointeam`, `drop`, `buy`). Registering a
+   * ConCommand of an engine-owned name fails outright ("unable to link multiple ConCommands named
+   * X"), so this is the only way to see those.
+   *
+   * OBSERVE-BY-DEFAULT: the engine still handles the command as normal. Return
+   * `>= HookResult.Handled` to suppress its engine-side handling — but note that for a command with
+   * a visible effect (a ping marker, a team change) suppressing is usually NOT what you want.
+   *
+   * @example
+   * // Middle-mouse ping opens the shop, and still places the ping.
+   * ctx.commands.onClientCommand("player_ping", (slot) => { openShop(slot); });
+   */
+  onClientCommand(name: string, handler: (slot: number, argString: string) => HookResultValue | void): void;
   /** Every globally-registered command with its required admin `flags`: `0` = anyone, `-1` = console/server-only,
    * else the `ADMFLAG` bit mask (map bits→names in your plugin). The `sm_help` backend. */
   list(): { name: string; flags: number }[];