@s2script/sdk 0.27.1 → 0.29.0

package/README.md

@@ -113,7 +113,88 @@ field: `s2s build` builds every plugin in a workspace regardless of `private`, b
 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.)
+deploy <dir>` on a single private plugin outside a workspace refuses the same way.) To publish a
+package that only your org can see, use npm's other mechanism, `access`, instead (see Publishing).
+
+### 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.
+
+**Source.** Like `npm publish`, every deploy also uploads the package's source as an npm-shaped
+tarball (every file under `package/`), downloadable from the package page. Files are chosen with
+npm's own rules: package.json `files` if present, otherwise everything minus `.npmignore` (or
+`.gitignore` where there is no `.npmignore`); package.json, README and LICENSE are always in;
+`node_modules`, `.git`, `.npmrc` and lockfiles never are. One deliberate difference: `.env` files
+are never packed. `s2s pack --dry-run` lists exactly what a deploy would send, and `s2s pack`
+writes the tarball (`<scope>-<name>-<version>.tgz`). The source of a public package is public, so
+check that list before the first deploy.
+
+**Restricted packages.** As on npm, a scoped package can be published **restricted**: only the
+members of its org can see or install it, and everyone else gets a 404. Use
+`s2s deploy --access restricted`, or `"publishConfig": { "access": "restricted" }` in package.json
+(the flag wins). Access is fixed when the package is first published. A deploy that names none
+keeps the current one. Before uploading, the CLI checks that the registry can keep the package
+restricted, and refuses otherwise, so it never goes out public by accident. `s2s install` and
+`s2s add` send your login, so members install restricted packages as usual. A server that only
+installs should use a read-only token (s2script.com → Deploy tokens) as `S2SCRIPT_TOKEN`.
+
+## Servers
+
+A game server lists its registry plugins as npm-style `dependencies` in
+`addons/s2script/plugins.json`, with a `plugins-lock.json` beside it. These are npm's shapes under
+their own names, so npm never treats the folder as a Node project. From the game directory,
+`s2s install <name>[@range]` adds a plugin (creating `plugins.json` the first time, like npm). Plain
+`s2s install` installs exactly the lock, and `s2s update` moves each plugin to the newest version
+its range allows. `s2s server init` writes both files from plugins already installed. The runtime
+runs the same update at every startup before loading plugins (`"autoUpdate": false` turns it off).
+See [INSTALL.md](https://github.com/s2script/s2script/blob/main/docs/INSTALL.md).
 
 ## Docs
 

package/commands.d.ts

@@ -57,7 +57,7 @@ export interface CommandInvocation {
    *
    * @example
    * // `!help` answers in chat; `sm_help` typed at a console answers in that console.
-   * command("sm_help", (cmd) => { cmd.reply("[SM] Commands: …"); return HookResult.Handled; });
+   * command("sm_help", (cmd) => { cmd.reply("[S2S] Commands: …"); return HookResult.Handled; });
    */
   reply(message: string): void;
   /**