@s2script/sdk 0.18.0 → 0.20.0

package/dist/cli.js

@@ -3769,6 +3769,12 @@ function generatedDeclarationFiles(pluginDir) {
   const gd = join7(pluginDir, ".s2script", "gamedata.d.ts");
   return existsSync6(gd) ? [gd] : [];
 }
+function gamePackageDeclarationFiles(pkg, packagesDir) {
+  const deps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+  if (!("@s2script/cs2" in deps)) return [];
+  const hooks = join7(packagesDir, "cs2", "hooks.generated.d.ts");
+  return existsSync6(hooks) ? [hooks] : [];
+}
 function declaredModules(dtsFiles) {
   const out = /* @__PURE__ */ new Set();
   for (const f of dtsFiles) {
@@ -3837,7 +3843,8 @@ function typecheckPlugin(pluginDir, opts) {
     entry,
     join7(packagesDir, "sdk", "globals.d.ts"),
     ...localDts,
-    ...generatedDeclarationFiles(absDir)
+    ...generatedDeclarationFiles(absDir),
+    ...gamePackageDeclarationFiles(pkg, packagesDir)
   ];
   const tmp = mkdtempSync(join7(tmpdir(), "s2tc-"));
   try {
@@ -8528,7 +8535,7 @@ async function run8(argv2) {
 }
 
 // src/commands/codegen.ts
-import { dirname as dirname6, join as join27 } from "node:path";
+import { dirname as dirname6, join as join28 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/schemagen/gen.ts
@@ -9406,9 +9413,102 @@ function runGenNav(repoRoot2, opts) {
   return { wrappers: model.wrappers.length, fields, drift };
 }
 
+// src/hookgen/gen.ts
+import { readFileSync as readFileSync22, writeFileSync as writeFileSync17 } from "node:fs";
+import { join as join27 } from "node:path";
+
+// src/hookgen/model.ts
+function capitalize(name) {
+  return name.length === 0 ? name : name.charAt(0).toUpperCase() + name.slice(1);
+}
+function buildHookModel(hooks) {
+  const byNs = /* @__PURE__ */ new Map();
+  for (const name of Object.keys(hooks).sort()) {
+    const decl = hooks[name] ?? {};
+    const ns = decl.expose?.ctx;
+    if (!ns) continue;
+    const paramNames = decl.params ?? [];
+    const mutableSet = new Set(decl.mutable ?? []);
+    const params = paramNames.map((p) => ({ name: p, mutable: mutableSet.has(p) }));
+    const receiverAs = decl.receiver?.kind === "entity" ? decl.receiver.as ?? null : null;
+    const list = byNs.get(ns) ?? [];
+    list.push({ name, viewIface: `${capitalize(name)}View`, params, receiverAs });
+    byNs.set(ns, list);
+  }
+  return Array.from(byNs.keys()).sort().map((ns) => ({ ns, ctxIface: `Ctx${capitalize(ns)}`, hooks: byNs.get(ns) }));
+}
+
+// src/hookgen/emit-dts.ts
+var HEADER6 = "// GENERATED by `s2script gen-hooks` from gamedata/cs2/game.cs2.jsonc's `hooks` \u2014 DO NOT EDIT.";
+function emitViewIface(h2) {
+  const out = [`export interface ${h2.viewIface} {`];
+  for (const p of h2.params) {
+    const mod = p.mutable ? "" : "readonly ";
+    out.push(`  ${mod}${p.name}: number;`);
+  }
+  if (h2.receiverAs !== null) {
+    out.push(`  readonly ${h2.receiverAs}: EntityRef | null;`);
+  }
+  out.push("}", "");
+  return out;
+}
+function emitHookDts(model) {
+  const out = [
+    HEADER6,
+    'import type { HookResultValue } from "@s2script/sdk/events";',
+    'import type { EntityRef } from "@s2script/sdk/entity";',
+    ""
+  ];
+  for (const { hooks } of model) {
+    for (const h2 of hooks) {
+      out.push(...emitViewIface(h2));
+    }
+  }
+  for (const { ctxIface, hooks } of model) {
+    out.push(`export interface ${ctxIface} {`);
+    for (const h2 of hooks) {
+      out.push(`  ${h2.name}(handler: (view: ${h2.viewIface}) => HookResultValue | void): void;`);
+    }
+    out.push("}", "");
+  }
+  out.push('declare module "@s2script/sdk/plugin" {');
+  out.push("  interface PluginContext {");
+  for (const { ns, ctxIface } of model) {
+    out.push(`    readonly ${ns}: ${ctxIface};`);
+  }
+  out.push("  }");
+  out.push("}");
+  return out.join("\n") + "\n";
+}
+
+// src/hookgen/gen.ts
+var GAMEDATA_PATH = "gamedata/cs2/game.cs2.jsonc";
+var DTS_OUT4 = "packages/cs2/hooks.generated.d.ts";
+function runGenHooks(repoRoot2, opts) {
+  const raw = readFileSync22(join27(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 = join27(repoRoot2, DTS_OUT4);
+  if (opts.check) {
+    let cur = "";
+    try {
+      cur = readFileSync22(abs, "utf8");
+    } catch {
+    }
+    if (cur !== dts) drift.push(DTS_OUT4);
+  } else {
+    writeFileSync17(abs, dts);
+  }
+  const hookCount = model.reduce((n3, ns) => n3 + ns.hooks.length, 0);
+  return { hooks: hookCount, drift };
+}
+
 // src/commands/codegen.ts
 function repoRoot() {
-  return join27(dirname6(fileURLToPath3(import.meta.url)), "..", "..", "..");
+  return join28(dirname6(fileURLToPath3(import.meta.url)), "..", "..", "..");
 }
 async function run9(kind, argv2) {
   const root = repoRoot();
@@ -9437,7 +9537,7 @@ async function run9(kind, argv2) {
     } else {
       console.log(`gen-events: wrote ${r2.events} events`);
     }
-  } else {
+  } else if (kind === "nav") {
     const r2 = runGenNav(root, { check });
     if (check) {
       if (r2.drift.length) {
@@ -9449,6 +9549,18 @@ async function run9(kind, argv2) {
     } else {
       console.log(`gen-nav: wrote ${r2.wrappers} wrappers, ${r2.fields} fields`);
     }
+  } else {
+    const r2 = runGenHooks(root, { check });
+    if (check) {
+      if (r2.drift.length) {
+        console.error(`FAIL: generated files out of date \u2014 run \`s2s gen-hooks\`:
+  ${r2.drift.join("\n  ")}`);
+        process.exit(1);
+      }
+      console.log(`hook codegen up to date (${r2.hooks} hooks)`);
+    } else {
+      console.log(`gen-hooks: wrote ${r2.hooks} hooks`);
+    }
   }
 }
 
@@ -9464,7 +9576,8 @@ var COMMANDS = [
   { name: "config", summary: "Emit a plugin's default config file(s)", run: run8 },
   { name: "gen-schema", summary: "Regenerate schema accessors", run: (a2) => run9("schema", a2) },
   { name: "gen-events", summary: "Regenerate the event catalog", run: (a2) => run9("events", a2) },
-  { name: "gen-nav", summary: "Regenerate nav accessors", run: (a2) => run9("nav", a2) }
+  { name: "gen-nav", summary: "Regenerate nav accessors", run: (a2) => run9("nav", a2) },
+  { name: "gen-hooks", summary: "Regenerate the ctx hook augmentation", run: (a2) => run9("hooks", a2) }
 ];
 function find(name) {
   if (name === "publish") return COMMANDS.find((c2) => c2.name === "deploy");
@@ -9487,7 +9600,7 @@ var argv = process.argv.slice(2);
 var command = argv[0];
 function usage() {
   console.error(
-    "Usage:\n  s2s create [path] [--game cs2|none] [--name <pkg>] [--template minimal] [--library]\n             [--install npm|pnpm|yarn|bun|none] [--no-install] [-y]\n  s2s create --workspace <dir>\n  s2s build [dir|workspace root] [--filter <pattern>]... [--stamp-version <v>]\n            [--packages-dir <path>]\n  s2s login [--token s2s_\u2026] [--registry <url>]\n  s2s deploy [dir|workspace root] [--filter <pattern>]... [--dry-run] [--yes|--ci]\n             [--registry <url>] [--packages-dir <path>]\n  s2s version [dir] [--since <ref>]\n  s2s add <pkg>[@range] [--dir <plugin>] [--registry <url>]\n  s2s install [name[@range]...] [--file <path>] [--dir <plugins dir>] [--registry <url>]\n  s2s config gen <plugin.s2sp...> --out <dir>\n  s2s gen-schema [--check]\n  s2s gen-events [--check]\n  s2s gen-nav [--check]\n\nEnv: S2SCRIPT_REGISTRY_URL  S2SCRIPT_TOKEN (CI deploy)"
+    "Usage:\n  s2s create [path] [--game cs2|none] [--name <pkg>] [--template minimal] [--library]\n             [--install npm|pnpm|yarn|bun|none] [--no-install] [-y]\n  s2s create --workspace <dir>\n  s2s build [dir|workspace root] [--filter <pattern>]... [--stamp-version <v>]\n            [--packages-dir <path>]\n  s2s login [--token s2s_\u2026] [--registry <url>]\n  s2s deploy [dir|workspace root] [--filter <pattern>]... [--dry-run] [--yes|--ci]\n             [--registry <url>] [--packages-dir <path>]\n  s2s version [dir] [--since <ref>]\n  s2s add <pkg>[@range] [--dir <plugin>] [--registry <url>]\n  s2s install [name[@range]...] [--file <path>] [--dir <plugins dir>] [--registry <url>]\n  s2s config gen <plugin.s2sp...> --out <dir>\n  s2s gen-schema [--check]\n  s2s gen-events [--check]\n  s2s gen-nav [--check]\n  s2s gen-hooks [--check]\n\nEnv: S2SCRIPT_REGISTRY_URL  S2SCRIPT_TOKEN (CI deploy)"
   );
 }
 if (!command) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s2script/sdk",
-  "version": "0.18.0",
+  "version": "0.20.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",

package/ws.d.ts

@@ -13,17 +13,36 @@ export interface WebSocket {
   /** Close the connection. */
   close(): void;
 }
+/** Options for {@link WebSocket.connect}. */
+export interface WebSocketInit {
+  /**
+   * Extra headers to send on the opening handshake — the usual reason being a
+   * credential the server requires, e.g. `Authorization: Bearer <token>`.
+   *
+   * Headers the handshake owns are refused, and the connect rejects rather than
+   * silently dropping them: `Host`, `Connection`, `Upgrade`, any
+   * `Sec-WebSocket-*`, `Content-Length`, `Transfer-Encoding`. Values containing
+   * control characters are refused for the same reason.
+   */
+  headers?: Record<string, string>;
+}
+
 /** Entry point for opening WebSocket connections. */
 export declare const WebSocket: {
   /**
    * Connect to a WebSocket server (`wss://` for TLS) off the game thread.
    * @returns Resolves on the open handshake with the live {@link WebSocket} handle.
-   * @throws Rejects on connect failure (bad URL, refused, TLS/handshake error).
+   * @throws Rejects on connect failure (bad URL, refused, TLS/handshake error, or a refused header).
    * @example
    * import { WebSocket } from "@s2script/sdk/ws";
    * const ws = await WebSocket.connect("wss://ws.postman-echo.com/raw");
    * ws.onMessage((data) => { console.log("echo:", data); ws.close(); });
    * ws.send("hello-from-s2script");
+   * @example
+   * // A server that authenticates the handshake rather than the first frame.
+   * const ws = await WebSocket.connect("wss://maul.example/v2/ws", {
+   *   headers: { Authorization: `Bearer ${jwt}` },
+   * });
    */
-  connect(url: string): Promise<WebSocket>;
+  connect(url: string, init?: WebSocketInit): Promise<WebSocket>;
 };