@s2script/sdk 0.5.0 → 0.5.1

package/dist/cli.js

@@ -446,8 +446,8 @@ async function lintPlugin(pluginDir, program) {
   const results = await eslint.lintFiles(targets);
   const errorCount = results.reduce((n, r) => n + r.errorCount, 0);
   const formatter = await eslint.loadFormatter("stylish");
-  const output2 = String(await formatter.format(results));
-  return { ok: errorCount === 0, output: output2, errorCount };
+  const output3 = String(await formatter.format(results));
+  return { ok: errorCount === 0, output: output3, errorCount };
 }
 
 // src/build.ts
@@ -788,21 +788,21 @@ function emitJs(model) {
   for (const c of model.classes) {
     out.push(`  A[${S(c.className)}] = {`);
     for (const f of flattenedFields(model, c.className)) {
-      const resolve8 = `off(${S(f.declaringClass)},${S(f.rawName)})`;
+      const resolve10 = `off(${S(f.declaringClass)},${S(f.rawName)})`;
       let entry;
       if (f.accessorKind === "str") {
-        entry = `get: function () { return this.ref.readString(${resolve8}, ${f.strLen}); }`;
+        entry = `get: function () { return this.ref.readString(${resolve10}, ${f.strLen}); }`;
       } else if (f.accessorKind === "u64" || f.accessorKind === "i64") {
-        entry = `get: function () { var v = this.ref.${READ[f.accessorKind]}(${resolve8}); return v === null ? null : v.toString(); }`;
+        entry = `get: function () { var v = this.ref.${READ[f.accessorKind]}(${resolve10}); return v === null ? null : v.toString(); }`;
       } else if (VEC_INFO[f.accessorKind]) {
         const vi = VEC_INFO[f.accessorKind];
-        entry = `get: function () { var a = this.ref.readFloats(${resolve8}, ${vi.count}); return a === null ? null : new ${vi.cls}(a[0], a[1], a[2]); }`;
+        entry = `get: function () { var a = this.ref.readFloats(${resolve10}, ${vi.count}); return a === null ? null : new ${vi.cls}(a[0], a[1], a[2]); }`;
       } else {
-        entry = `get: function () { return this.ref.${READ[f.accessorKind]}(${resolve8}); }`;
+        entry = `get: function () { return this.ref.${READ[f.accessorKind]}(${resolve10}); }`;
       }
       if (f.writable) {
         const wm = WRITE[f.accessorKind];
-        entry += `, set: function (v) { var o = ${resolve8}; if (this.ref.${wm}(o, v)) this.ref.notifyStateChanged(o); }`;
+        entry += `, set: function (v) { var o = ${resolve10}; if (this.ref.${wm}(o, v)) this.ref.notifyStateChanged(o); }`;
       }
       out.push(`    ${S(f.propName)}: { ${entry} },`);
     }
@@ -1038,22 +1038,22 @@ function emitNavJs(model) {
     out.push(`  function ${w.wrapper}(root, path) { this.root = root; this.path = path; }`);
     out.push(`  Object.defineProperties(${w.wrapper}.prototype, {`);
     for (const f of w.fields) {
-      const resolve8 = `off(${S2(f.declaringClass)},${S2(f.rawName)})`;
+      const resolve10 = `off(${S2(f.declaringClass)},${S2(f.rawName)})`;
       let getter;
       const kind = f.accessorKind;
       if (kind === "u64") {
-        getter = `get: function () { var v = this.root.readUInt64Via(this.path, ${resolve8}); return v === null ? null : v.toString(); }`;
+        getter = `get: function () { var v = this.root.readUInt64Via(this.path, ${resolve10}); return v === null ? null : v.toString(); }`;
       } else if (kind === "i64") {
-        getter = `get: function () { var v = this.root.readInt64Via(this.path, ${resolve8}); return v === null ? null : v.toString(); }`;
+        getter = `get: function () { var v = this.root.readInt64Via(this.path, ${resolve10}); return v === null ? null : v.toString(); }`;
       } else if (VEC_INFO[kind]) {
         const vi = VEC_INFO[kind];
-        getter = `get: function () { var a = this.root.readFloatsChain(this.path, ${resolve8}, ${vi.count}); return a === null ? null : new ${vi.cls}(a[0], a[1], a[2]); }`;
+        getter = `get: function () { var a = this.root.readFloatsChain(this.path, ${resolve10}, ${vi.count}); return a === null ? null : new ${vi.cls}(a[0], a[1], a[2]); }`;
       } else if (kind === "handle") {
-        getter = `get: function () { return this.root.readHandleVia(this.path, ${resolve8}); }`;
+        getter = `get: function () { return this.root.readHandleVia(this.path, ${resolve10}); }`;
       } else {
         const method = READ_VIA[kind];
         if (!method) continue;
-        getter = `get: function () { return this.root.${method}(this.path, ${resolve8}); }`;
+        getter = `get: function () { return this.root.${method}(this.path, ${resolve10}); }`;
       }
       out.push(`    ${S2(f.propName)}: { ${getter} },`);
     }
@@ -1244,10 +1244,10 @@ function versionSpecFrom(status, stdout) {
   const v = (stdout ?? "").trim();
   return status === 0 && /^\d+\.\d+\.\d+/.test(v) ? `^${v}` : "latest";
 }
-function registryDevDeps(game, sdkVersion, resolve8 = resolvePublishedVersion) {
+function registryDevDeps(game, sdkVersion, resolve10 = resolvePublishedVersion) {
   const deps = {};
   for (const n of createPackageNames(game)) {
-    deps[`@s2script/${n}`] = n === "sdk" ? `^${sdkVersion}` : resolve8(`@s2script/${n}`);
+    deps[`@s2script/${n}`] = n === "sdk" ? `^${sdkVersion}` : resolve10(`@s2script/${n}`);
   }
   return deps;
 }
@@ -1451,7 +1451,7 @@ function generateDefaultJsonc(config) {
   return "{\n" + genEntries(config, 1) + "}\n";
 }
 function genEntries(entries, indent) {
-  const pad = "  ".repeat(indent);
+  const pad2 = "  ".repeat(indent);
   const keys = Object.keys(entries).filter((k) => !k.includes(".")).sort();
   let out = "";
   keys.forEach((key, i) => {
@@ -1461,15 +1461,15 @@ function genEntries(entries, indent) {
     const obj = raw;
     if (isDecl(obj)) {
       const desc = typeof obj.description === "string" ? obj.description : "";
-      out += `${pad}// ${String(obj.type)}${desc ? ` \u2014 ${desc}` : ""}
+      out += `${pad2}// ${String(obj.type)}${desc ? ` \u2014 ${desc}` : ""}
 `;
-      out += `${pad}${JSON.stringify(key)}: ${JSON.stringify(obj.default)}${comma}
+      out += `${pad2}${JSON.stringify(key)}: ${JSON.stringify(obj.default)}${comma}
 `;
     } else {
-      out += `${pad}${JSON.stringify(key)}: {
+      out += `${pad2}${JSON.stringify(key)}: {
 `;
       out += genEntries(obj, indent + 1);
-      out += `${pad}}${comma}
+      out += `${pad2}}${comma}
 `;
     }
   });
@@ -1505,13 +1505,386 @@ function runConfigGen(s2sps, outDir) {
   return { written, skipped };
 }
 
+// src/registry/login.ts
+import { createInterface as createInterface2 } from "node:readline/promises";
+import { stdin as input2, stdout as output2 } from "node:process";
+
+// src/registry/credentials.ts
+import { existsSync as existsSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync9, writeFileSync as writeFileSync7 } from "node:fs";
+import { homedir } from "node:os";
+import { join as join12 } from "node:path";
+function credentialsPath() {
+  return join12(homedir(), ".s2script", "credentials.json");
+}
+function defaultRegistryUrl() {
+  return process.env.S2SCRIPT_REGISTRY_URL?.replace(/\/$/, "") || "https://s2script.com";
+}
+function loadCredentials() {
+  const fromEnv = process.env.S2SCRIPT_TOKEN || process.env.S2SCRIPT_DEPLOY_TOKEN;
+  if (fromEnv) {
+    return { registryUrl: defaultRegistryUrl(), token: fromEnv };
+  }
+  const p = credentialsPath();
+  if (!existsSync7(p)) return null;
+  try {
+    const j = JSON.parse(readFileSync9(p, "utf8"));
+    if (!j.token) return null;
+    return {
+      registryUrl: (j.registryUrl || defaultRegistryUrl()).replace(/\/$/, ""),
+      token: j.token
+    };
+  } catch {
+    return null;
+  }
+}
+function saveCredentials(creds) {
+  const dir = join12(homedir(), ".s2script");
+  mkdirSync4(dir, { recursive: true });
+  writeFileSync7(
+    credentialsPath(),
+    JSON.stringify(
+      { registryUrl: creds.registryUrl.replace(/\/$/, ""), token: creds.token },
+      null,
+      2
+    ) + "\n",
+    { mode: 384 }
+  );
+}
+
+// src/registry/login.ts
+async function loginInteractive(opts) {
+  const registryUrl = (opts?.registryUrl || defaultRegistryUrl()).replace(/\/$/, "");
+  let token = opts?.token || process.env.S2SCRIPT_TOKEN || process.env.S2SCRIPT_DEPLOY_TOKEN;
+  if (!token) {
+    if (opts?.ci || !input2.isTTY) {
+      throw new Error(
+        "no deploy token: set S2SCRIPT_TOKEN or run `s2script login` interactively"
+      );
+    }
+    const rl = createInterface2({ input: input2, output: output2 });
+    try {
+      console.log(`Registry: ${registryUrl}`);
+      console.log("Create a deploy token at /account/tokens on the registry site, then paste it:");
+      token = (await rl.question("token: ")).trim();
+    } finally {
+      rl.close();
+    }
+  }
+  if (!token || !token.startsWith("s2s_")) {
+    throw new Error('token must start with "s2s_"');
+  }
+  const creds = { registryUrl, token };
+  saveCredentials(creds);
+  return creds;
+}
+
+// src/registry/deploy.ts
+import { readFileSync as readFileSync11 } from "node:fs";
+import { resolve as resolve7 } from "node:path";
+import AdmZip3 from "adm-zip";
+
+// src/types-pack.ts
+import { readFileSync as readFileSync10 } from "node:fs";
+import { gzipSync } from "node:zlib";
+function pad(buf, size) {
+  if (buf.length > size) throw new Error(`tar field overflow (${buf.length}>${size})`);
+  const out = Buffer.alloc(size, 0);
+  buf.copy(out);
+  return out;
+}
+function tarHeader(name, size, type) {
+  const header = Buffer.alloc(512, 0);
+  pad(Buffer.from(name, "utf8"), 100).copy(header, 0);
+  Buffer.from("0000644\0", "utf8").copy(header, 100);
+  Buffer.from("0000000\0", "utf8").copy(header, 108);
+  Buffer.from("0000000\0", "utf8").copy(header, 116);
+  const sizeOct = size.toString(8).padStart(11, "0") + "\0";
+  Buffer.from(sizeOct, "utf8").copy(header, 124);
+  const mtime = Math.floor(Date.now() / 1e3).toString(8).padStart(11, "0") + "\0";
+  Buffer.from(mtime, "utf8").copy(header, 136);
+  Buffer.from("        ", "utf8").copy(header, 148);
+  header[156] = type.charCodeAt(0);
+  Buffer.from("ustar\0", "utf8").copy(header, 257);
+  Buffer.from("00", "utf8").copy(header, 263);
+  let sum = 0;
+  for (let i = 0; i < 512; i++) sum += header[i];
+  const chk = sum.toString(8).padStart(6, "0") + "\0 ";
+  Buffer.from(chk, "utf8").copy(header, 148);
+  return header;
+}
+function tarFile(name, content) {
+  const header = tarHeader(name, content.length, "0");
+  const padLen = (512 - content.length % 512) % 512;
+  return Buffer.concat([header, content, Buffer.alloc(padLen, 0)]);
+}
+function packTypesTarball(input3) {
+  const dts = readFileSync10(input3.typesPath);
+  const pkgJson = Buffer.from(
+    JSON.stringify(
+      {
+        name: input3.name,
+        version: input3.version,
+        types: "api.d.ts",
+        s2script: {
+          kind: "interface",
+          ...input3.publishes ? { publishes: input3.publishes } : {}
+        }
+      },
+      null,
+      2
+    ) + "\n",
+    "utf8"
+  );
+  const tar = Buffer.concat([
+    tarFile("package/package.json", pkgJson),
+    tarFile("package/api.d.ts", dts),
+    Buffer.alloc(1024, 0)
+    // two zero blocks = EOF
+  ]);
+  return gzipSync(tar);
+}
+
+// src/registry/client.ts
+var RegistryError = class extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "RegistryError";
+  }
+};
+var RegistryClient = class {
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+    this.token = opts.token;
+    this.fetchFn = opts.fetch ?? fetch;
+  }
+  headers(extra) {
+    const h = { ...extra ?? {} };
+    if (this.token) h.Authorization = `Bearer ${this.token}`;
+    return h;
+  }
+  async deploy(opts) {
+    const fd = new FormData();
+    fd.set("manifest", JSON.stringify(opts.manifest));
+    fd.set("s2sp", new Blob([new Uint8Array(opts.s2sp)]), "plugin.s2sp");
+    if (opts.types && opts.types.length) {
+      fd.set("types", new Blob([new Uint8Array(opts.types)]), "types.tgz");
+    }
+    const res = await this.fetchFn(`${this.baseUrl}/api/v1/deploy`, {
+      method: "POST",
+      headers: this.headers(),
+      body: fd
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new RegistryError(
+        body.error || `deploy failed (${res.status})`,
+        res.status,
+        body
+      );
+    }
+    return body;
+  }
+  async resolve(name, range = "*") {
+    const u = new URL(`${this.baseUrl}/api/v1/resolve`);
+    u.searchParams.set("name", name);
+    u.searchParams.set("range", range);
+    const res = await this.fetchFn(u, { headers: this.headers() });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new RegistryError(
+        body.message || `resolve failed (${res.status})`,
+        res.status,
+        body
+      );
+    }
+    return body;
+  }
+  async downloadTypes(name, version) {
+    const u = new URL(`${this.baseUrl}/api/v1/download/types`);
+    u.searchParams.set("name", name);
+    u.searchParams.set("version", version);
+    const res = await this.fetchFn(u, { headers: this.headers() });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new RegistryError(
+        body.message || `types download failed (${res.status})`,
+        res.status,
+        body
+      );
+    }
+    return Buffer.from(await res.arrayBuffer());
+  }
+  async meta(name) {
+    const u = new URL(`${this.baseUrl}/api/v1/meta`);
+    u.searchParams.set("name", name);
+    const res = await this.fetchFn(u, { headers: this.headers() });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new RegistryError(`meta failed (${res.status})`, res.status, body);
+    }
+    return body;
+  }
+};
+
+// src/registry/deploy.ts
+async function deployPlugin(opts) {
+  const absDir = resolve7(opts.dir);
+  const pkg = JSON.parse(readFileSync11(resolve7(absDir, "package.json"), "utf8"));
+  const gate = assertPublishesTypes(pkg, absDir);
+  if (!gate.ok) throw new Error(`publish gate failed: ${gate.error}`);
+  const creds = loadCredentials();
+  if (!creds?.token) {
+    throw new Error(
+      opts.ci ? "S2SCRIPT_TOKEN required in CI" : "not logged in \u2014 run `s2s login` or set S2SCRIPT_TOKEN"
+    );
+  }
+  const outPath = await buildPlugin(absDir, opts.packagesDir);
+  const s2sp = readFileSync11(outPath);
+  const zip = new AdmZip3(s2sp);
+  const manifestEntry = zip.getEntry("manifest.json");
+  if (!manifestEntry) {
+    throw new Error(`built archive missing manifest.json: ${outPath}`);
+  }
+  const manifest = JSON.parse(manifestEntry.getData().toString("utf8"));
+  let types = null;
+  if (gate.typesPath) {
+    types = packTypesTarball({
+      name: typeof manifest.id === "string" ? manifest.id : pkg.name,
+      version: typeof manifest.version === "string" ? manifest.version : pkg.version,
+      typesPath: gate.typesPath,
+      publishes: hasPublishes(manifest.publishes) ? manifest.publishes : void 0
+    });
+  }
+  const client = new RegistryClient({
+    baseUrl: opts.registryUrl || creds.registryUrl || defaultRegistryUrl(),
+    token: creds.token
+  });
+  return client.deploy({ manifest, s2sp, types });
+}
+
+// src/registry/add.ts
+import {
+  mkdirSync as mkdirSync5,
+  writeFileSync as writeFileSync9,
+  readFileSync as readFileSync13,
+  existsSync as existsSync9
+} from "node:fs";
+import { join as join14, resolve as resolve8 } from "node:path";
+import { gunzipSync } from "node:zlib";
+
+// src/registry/npmrc.ts
+import { existsSync as existsSync8, readFileSync as readFileSync12, writeFileSync as writeFileSync8 } from "node:fs";
+import { join as join13 } from "node:path";
+function npmCompatRegistryUrl(registryUrl) {
+  return `${registryUrl.replace(/\/$/, "")}/npm/`;
+}
+function scopeFromPackageName(name) {
+  if (!name.startsWith("@")) return null;
+  const slash = name.indexOf("/");
+  if (slash < 2) return null;
+  return name.slice(1, slash);
+}
+function ensureScopeNpmrc(projectDir, packageName, registryUrl) {
+  const scope = scopeFromPackageName(packageName);
+  if (!scope || scope === "s2script") return null;
+  const compat = npmCompatRegistryUrl(registryUrl);
+  const key = `@${scope}:registry`;
+  const line = `${key}=${compat}`;
+  const npmrcPath = join13(projectDir, ".npmrc");
+  let existing = existsSync8(npmrcPath) ? readFileSync12(npmrcPath, "utf8") : "";
+  const lines = existing.split(/\r?\n/);
+  const idx = lines.findIndex((l) => l.trimStart().startsWith(`${key}=`) || l.trimStart().startsWith(`${key} =`));
+  if (idx >= 0) {
+    lines[idx] = line;
+  } else {
+    if (existing && !existing.endsWith("\n")) lines.push("");
+    lines.push(line);
+  }
+  const out = lines.filter((l, i, a) => !(l === "" && a[i - 1] === "")).join("\n");
+  writeFileSync8(npmrcPath, out.endsWith("\n") ? out : out + "\n");
+  return line;
+}
+
+// src/registry/add.ts
+function parseSpec(spec) {
+  if (spec.startsWith("@")) {
+    const at2 = spec.indexOf("@", 1);
+    if (at2 < 0) return { name: spec, range: "*" };
+    return { name: spec.slice(0, at2), range: spec.slice(at2 + 1) || "*" };
+  }
+  const at = spec.lastIndexOf("@");
+  if (at <= 0) return { name: spec, range: "*" };
+  return { name: spec.slice(0, at), range: spec.slice(at + 1) || "*" };
+}
+function extractTypesTarball(tgz, outDir) {
+  const tar = gunzipSync(tgz);
+  mkdirSync5(outDir, { recursive: true });
+  let offset = 0;
+  let wroteContract = false;
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512);
+    offset += 512;
+    if (header.every((b) => b === 0)) break;
+    const name = header.subarray(0, 100).toString("utf8").replace(/\0.*$/, "");
+    const sizeOct = header.subarray(124, 135).toString("utf8").replace(/\0.*$/, "").trim();
+    const size = parseInt(sizeOct, 8) || 0;
+    const content = tar.subarray(offset, offset + size);
+    offset += size + (512 - size % 512) % 512;
+    if (!name || name.endsWith("/")) continue;
+    const base = name.replace(/^package\//, "");
+    if (base === "package.json") {
+      writeFileSync9(join14(outDir, "package.json"), content);
+    } else if (base === "api.d.ts" || base === "index.d.ts") {
+      writeFileSync9(join14(outDir, "index.d.ts"), content);
+      wroteContract = true;
+    }
+  }
+  if (!wroteContract && !existsSync9(join14(outDir, "index.d.ts"))) {
+    throw new Error("types tarball missing package/api.d.ts (or index.d.ts)");
+  }
+}
+async function addPackage(opts) {
+  const absDir = resolve8(opts.pluginDir);
+  const { name, range } = parseSpec(opts.spec);
+  const creds = loadCredentials();
+  const client = new RegistryClient({
+    baseUrl: opts.registryUrl || creds?.registryUrl || defaultRegistryUrl(),
+    token: creds?.token
+  });
+  const resolved = await client.resolve(name, range);
+  if (!resolved.hasTypes) {
+    throw new Error(`${name}@${resolved.version} has no types artifact (runtime-only package?)`);
+  }
+  const tgz = await client.downloadTypes(name, resolved.version);
+  const typesDir = join14(absDir, ".s2script", "types", ...name.split("/"));
+  extractTypesTarball(tgz, typesDir);
+  const pkgPath = join14(absDir, "package.json");
+  const pkg = JSON.parse(readFileSync13(pkgPath, "utf8"));
+  pkg.s2script = pkg.s2script ?? {};
+  pkg.s2script.pluginDependencies = pkg.s2script.pluginDependencies ?? {};
+  const major = resolved.version.split(".")[0] ?? "0";
+  pkg.s2script.pluginDependencies[name] = range.startsWith("^") || range === "*" ? `^${major}.0.0` : range.includes(".") ? range : `^${resolved.version}`;
+  writeFileSync9(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+  const registryUrl = opts.registryUrl || creds?.registryUrl || defaultRegistryUrl();
+  const npmrcLine = ensureScopeNpmrc(absDir, name, registryUrl);
+  return {
+    name: resolved.name,
+    version: resolved.version,
+    reviewState: resolved.reviewState,
+    typesDir,
+    npmrcLine
+  };
+}
+
 // src/cli.ts
 import { fileURLToPath as fileURLToPath3 } from "node:url";
-import { dirname as dirname3, join as join12, resolve as resolve7 } from "node:path";
+import { dirname as dirname3, join as join15, resolve as resolve9 } from "node:path";
 var argv = process.argv.slice(2);
 var command = argv[0];
 function repoRootFromCli() {
-  return join12(dirname3(fileURLToPath3(import.meta.url)), "..", "..", "..");
+  return join15(dirname3(fileURLToPath3(import.meta.url)), "..", "..", "..");
 }
 function parseFlag(args, name) {
   const eq = args.find((a) => a.startsWith(`${name}=`));
@@ -1600,6 +1973,68 @@ if (command === "gen-schema") {
     console.error(String(e instanceof Error ? e.message : e));
     process.exit(1);
   }
+} else if (command === "login") {
+  const args = argv.slice(1);
+  try {
+    const creds = await loginInteractive({
+      token: parseFlag(args, "--token"),
+      registryUrl: parseFlag(args, "--registry") || defaultRegistryUrl(),
+      ci: hasFlag(args, "--ci")
+    });
+    console.log(`logged in \u2192 ${creds.registryUrl} (credentials saved)`);
+  } catch (e) {
+    console.error(String(e instanceof Error ? e.message : e));
+    process.exit(1);
+  }
+} else if (command === "deploy" || command === "publish") {
+  const args = argv.slice(1);
+  const pos = positionals(args, ["--packages-dir", "--registry"]);
+  const dir = pos[0] ?? ".";
+  try {
+    const packagesDir = resolvePackagesDir({
+      explicit: parseFlag(args, "--packages-dir"),
+      pluginDir: resolve9(dir),
+      fromCliUrl: import.meta.url
+    });
+    const result = await deployPlugin({
+      dir,
+      packagesDir,
+      registryUrl: parseFlag(args, "--registry"),
+      ci: hasFlag(args, "--ci")
+    });
+    console.log(`deployed ${result.name}@${result.version} (${result.reviewState})`);
+    if (result.reviewState === "unreviewed") {
+      console.log("note: Not reviewed by s2script \u2014 listed with a disclaimer until approved.");
+    }
+  } catch (e) {
+    console.error(String(e instanceof Error ? e.message : e));
+    process.exit(1);
+  }
+} else if (command === "add") {
+  const args = argv.slice(1);
+  const pos = positionals(args, ["--dir", "--registry"]);
+  const spec = pos[0];
+  if (!spec) {
+    console.error("Usage: s2s add <pkg>[@range]");
+    process.exit(1);
+  }
+  try {
+    const result = await addPackage({
+      pluginDir: parseFlag(args, "--dir") || ".",
+      spec,
+      registryUrl: parseFlag(args, "--registry")
+    });
+    console.log(`added ${result.name}@${result.version} \u2192 ${result.typesDir}`);
+    if (result.npmrcLine) {
+      console.log(`npmrc: ${result.npmrcLine}  (types-only; npm install ${result.name} also works)`);
+    }
+    if (result.reviewState === "unreviewed") {
+      console.log("note: Not reviewed by s2script \u2014 types pulled; use at your own risk.");
+    }
+  } catch (e) {
+    console.error(String(e instanceof Error ? e.message : e));
+    process.exit(1);
+  }
 } else if (command === "config" && argv[1] === "gen") {
   const args = argv.slice(2);
   const outDir = parseFlag(args, "--out") ?? process.cwd();
@@ -1623,7 +2058,7 @@ if (command === "gen-schema") {
   try {
     const packagesDir = resolvePackagesDir({
       explicit: packagesDirFlag,
-      pluginDir: resolve7(dir),
+      pluginDir: resolve9(dir),
       fromCliUrl: import.meta.url
     });
     console.log(await buildPlugin(dir, packagesDir));
@@ -1633,7 +2068,7 @@ if (command === "gen-schema") {
   }
 } else {
   console.error(
-    "Usage:\n  s2s create [path] [--game cs2|none] [--name <pkg>] [--template minimal]\n             [--install npm|pnpm|yarn|bun|none] [--no-install] [-y]\n  s2s build <dir> [--packages-dir <path>]\n  s2s config gen <plugin.s2sp...> --out <dir>\n  s2s gen-schema [--check]\n  s2s gen-events [--check]\n  s2s gen-nav [--check]"
+    "Usage:\n  s2s create [path] [--game cs2|none] [--name <pkg>] [--template minimal]\n             [--install npm|pnpm|yarn|bun|none] [--no-install] [-y]\n  s2s build <dir> [--packages-dir <path>]\n  s2s login [--token s2s_\u2026] [--registry <url>]\n  s2s deploy [dir] [--ci] [--registry <url>] [--packages-dir <path>]\n  s2s add <pkg>[@range] [--dir <plugin>] [--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)"
   );
   process.exit(1);
 }

package/entity.d.ts

@@ -15,6 +15,8 @@
  * time" footgun). Obtain refs from the engine (events, `findByClass`, `readHandle`, …).
  */
 export declare class EntityRef {
+  /** This entity's slot index in the game entity system. Paired with the host-minted
+   *  {@link EntityRef.id} for slot validation (books first, then identity-slot match). */
   readonly index: number;
   /** The host-minted liveness id for this ref (books key). Not the raw engine serial. */
   readonly id: number;
@@ -80,21 +82,33 @@ export declare class EntityRef {
   /** Write an int32 at the end of a pointer chain (each hop deref'd, liveness-gated at the root). Returns
    *  false on a stale ref or a null hop. Used to clear a flag on a pointer-referenced sub-object. */
   writeInt32Via(pathOffs: number[], finalOff: number, value: number): boolean;
+  /** Read an i8 (sign-extended) at the end of a pointer chain (each hop deref'd, liveness-gated at the root); null if the root is stale or any hop is null. */
   readInt8Via(pathOffs: number[], finalOff: number): number | null;
+  /** Read an i16 (sign-extended) through a pointer chain; null if the root is stale or any hop is null. */
   readInt16Via(pathOffs: number[], finalOff: number): number | null;
+  /** Read a u8 through a pointer chain; null if the root is stale or any hop is null. */
   readUInt8Via(pathOffs: number[], finalOff: number): number | null;
+  /** Read a u16 through a pointer chain; null if the root is stale or any hop is null. */
   readUInt16Via(pathOffs: number[], finalOff: number): number | null;
+  /** Read a u32 through a pointer chain; null if the root is stale or any hop is null. */
   readUInt32Via(pathOffs: number[], finalOff: number): number | null;
+  /** Read an f32 through a pointer chain; null if the root is stale or any hop is null. */
   readFloat32Via(pathOffs: number[], finalOff: number): number | null;
+  /** Read a bool through a pointer chain; null if the root is stale or any hop is null. */
   readBoolVia(pathOffs: number[], finalOff: number): boolean | null;
+  /** Read a u64 as a BigInt through a pointer chain; null if the root is stale or any hop is null. */
   readUInt64Via(pathOffs: number[], finalOff: number): bigint | null;
+  /** Read an i64 as a BigInt through a pointer chain; null if the root is stale or any hop is null. */
   readInt64Via(pathOffs: number[], finalOff: number): bigint | null;
+  /** Decode a `CEntityHandle` at the end of a pointer chain into a liveness-gated {@link EntityRef}; null if the root is stale, any hop is null, or the handle is dead. */
   readHandleVia(pathOffs: number[], finalOff: number): EntityRef | null;
   /** Write a scalar through a pointer chain (write mirror of `read*Via`). Liveness-gated at the root;
    *  returns false on a stale ref, an unresolved hop, or a bad offset/kind. Does NOT notifyStateChanged —
    *  the caller decides (many sub-object fields, e.g. the fire gate, are server-authoritative).
    *  (`writeInt32Via` is declared above alongside `readInt32Via`.) */
   writeFloat32Via(pathOffs: number[], finalOff: number, value: number): boolean;
+  /** Write a bool through a pointer chain (write mirror of {@link EntityRef.readBoolVia}; shares the
+   *  no-notify semantics on {@link EntityRef.writeFloat32Via}). False on a stale ref, an unresolved hop, or a bad offset/kind. */
   writeBoolVia(pathOffs: number[], finalOff: number, value: boolean): boolean;
   /** Read a `CEntityHandle` at `offset`, decode it, and return a live `EntityRef` — or null if stale/invalid. */
   readHandle(offset: number): EntityRef | null;
@@ -138,7 +152,12 @@ export type EntityKeyValueMap = { [key: string]: string | number | boolean };
 /** Create a new entity by class name. WITHOUT keyvalues: create only — set fields, then call
  *  `.spawn()`. WITH keyvalues: create + DispatchSpawn(keyvalues) in one call — a non-null result is
  *  a LIVE, SPAWNED entity (on spawn failure the entity is removed and null returned). The created
- *  entity is game-world-owned (NOT auto-removed on plugin unload) — the plugin owns cleanup. */
+ *  entity is game-world-owned (NOT auto-removed on plugin unload) — the plugin owns cleanup.
+ *  @example
+ *  import { createEntity } from "@s2script/sdk/entity";
+ *  const wt = createEntity("point_worldtext", { message: "s2-ekv-proof", fullbright: true });
+ *  if (wt) wt.remove();
+ */
 export declare function createEntity(className: string, keyvalues?: EntityKeyValueMap): EntityRef | null;
 
 /** The payload delivered to an `Entity.onOutput` handler. */
@@ -155,6 +174,13 @@ export interface OutputEvent {
   delay: number;
 }
 
+/**
+ * Entry point for entity lookup by class name.
+ * @example
+ * import { Entity } from "@s2script/sdk/entity";
+ * const triggers = Entity.findByClass("trigger_multiple");
+ * for (const t of triggers) console.log(t.index, t.name);
+ */
 export declare const Entity: {
   /** Find every entity whose designer-name (class) exactly matches `className`. Returns liveness-gated refs. */
   findByClass(className: string): EntityRef[];