@s2script/sdk 0.27.0 → 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/config.d.ts

@@ -1,7 +1,7 @@
 /** @s2script/config — typed access to the plugin's materialized config. NO runtime code. */
 /** A materialized config value: a scalar, or a nested section object of further values. */
 export type ConfigValue = string | number | boolean | { [k: string]: ConfigValue };
-/** The whole materialized config: top-level keys to {@link ConfigValue}s. Passed to `ctx.config.onChange`. */
+/** The whole materialized config: top-level keys to {@link ConfigValue}s. Passed to `config.onChange` handlers. */
 export type Config = Record<string, ConfigValue>;
 /**
  * Typed access to this plugin's materialized config values (declared under `s2script.config` in the manifest).
@@ -25,7 +25,7 @@ export declare const config: {
   writeFile(name: string, content: string): void;
   /**
    * Fires when this plugin's config file is re-materialized on disk. Ledgered per plugin.
-   * Not load-window-gated (safe from `OnPluginStart` or from `ctx.config.onChange`).
+   * Not load-window-gated (safe from `OnPluginStart` or from a `config.onChange` handler).
    */
   onChange(handler: (cfg: Config) => void): void;
 };

package/contracts/workshop.d.ts

@@ -10,7 +10,7 @@
  *
  * @example
  * import type { WorkshopService } from "@s2script/sdk/contracts/workshop";
- * const ws = ctx.tryUse<WorkshopService>("workshop");
+ * const ws = tryUse<WorkshopService>("workshop"); // in OnPluginStart
  * if (ws) {
  *   const map = await ws.currentMap();
  *   console.log(map ? `${map.title} (${map.id})` : "not a workshop map");

package/db.d.ts

@@ -15,9 +15,16 @@ export interface ExecuteResult {
 
 /** A driver-owned connection — what a {@link Driver} hands back from {@link Driver.connect}. */
 export interface DriverConnection {
-  /** Run a SELECT and resolve every result {@link Row}; `params` bind `?` placeholders. */
+  /**
+   * Run a SELECT and resolve every result {@link Row}; `params` bind `?` placeholders. Rejects
+   * with `AsyncQueueFull` or `AsyncPayloadTooLarge` before acceptance; `DatabaseResultTooLarge`
+   * when rows or retained bytes exceed the configured limit.
+   */
   query(sql: string, params?: SqlValue[]): Promise<Row[]>;
-  /** Run a non-SELECT statement and resolve its {@link ExecuteResult}; `params` bind `?` placeholders. */
+  /**
+   * Run a non-SELECT statement and resolve its {@link ExecuteResult}; `params` bind `?`
+   * placeholders. Rejects with `AsyncQueueFull` or `AsyncPayloadTooLarge` before acceptance.
+   */
   execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
   /** Close the underlying connection. */
   close(): Promise<void>;
@@ -40,9 +47,16 @@ export interface Driver {
 }
 /** A live database connection (delegates to its driver). */
 export interface Database {
-  /** Run a SELECT and resolve every result {@link Row}; `params` bind `?` placeholders. */
+  /**
+   * Run a SELECT and resolve every result {@link Row}; `params` bind `?` placeholders. Rejects
+   * with `AsyncQueueFull` or `AsyncPayloadTooLarge` before acceptance; `DatabaseResultTooLarge`
+   * when rows or retained bytes exceed the configured limit.
+   */
   query(sql: string, params?: SqlValue[]): Promise<Row[]>;
-  /** Run a non-SELECT statement and resolve its {@link ExecuteResult}; `params` bind `?` placeholders. */
+  /**
+   * Run a non-SELECT statement and resolve its {@link ExecuteResult}; `params` bind `?`
+   * placeholders. Rejects with `AsyncQueueFull` or `AsyncPayloadTooLarge` before acceptance.
+   */
   execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
   /** Close the connection. */
   close(): Promise<void>;